Module page_curl

This plugin provides a page curl widget, the basic idea being to give the look and feel of turning a physical page as in a book or magazine.

To use the plugin, add the following in build.settings:


 plugins = { 
["plugin.pagecurl"] = { publisherId = "com.xibalbastudios" } }

Sample code is available here.

Functions

PageCurlWidget:Begin () Puts the widget in batching mode.
PageCurlWidget:Capture (target) Captures a target and sets it as the current page.
PageCurlWidget:Commit () If a batch is in progress, commits it.
PageCurlWidget:Detach ([into]) The display object underlying the page is removed from the widget's control.
PageCurlWidget:DisableTouch (no_reset) Disables all touch controls.
PageCurlWidget:EnableExpansion (enable) Enables or disables expansion.
PageCurlWidget:EnableInnerShadows (enable) Enables or disables inner shadows.
PageCurlWidget:GetGrabRegions () Gets the currently touchable regions.
PageCurlWidget:GetSize () Gets the (unexpanded) page size.
PageCurlWidget:PrepareSnapshot ([width[, height]]) Prepares a snapshot and sets it as the current page.
PageCurlWidget:SetBackTextureMethod (how) Sets the back texture behavior.
PageCurlWidget:SetBlankRect ([opts]) Sets a blank rectangle as the current page.
PageCurlWidget:SetColor (...) Sets the widget's color.
PageCurlWidget:SetColorMethod (how) Sets the color behavior.
PageCurlWidget:SetDirection (dir) Sets the curl direction used by touch.
PageCurlWidget:SetEdgeEffect (how) Sets the edge effect.
PageCurlWidget:SetFrontAndBackImages (front, back[, opts]) Sets two images as the current page, one for the front side and another for the back.
PageCurlWidget:SetImage (name[, opts]) Sets an image as the current page.
PageCurlWidget:SetTouchSides (how) Enables touch on multiple sides, disabling the rest.
NewPageCurlWidget ([opts]) Constructs a new page curl widget.


Functions

PageCurlWidget:Begin ()
Puts the widget in batching mode.

The motivation is to mitigate the potentially expensive overhead that comes with updating the widget's graphics machinery, e.g. creating new shaders, when several setter methods are to be called in succession. Instead, the intermediate values are merely recorded, but not acted upon until the batch is committed, cf. PageCurlWidget:Commit.

When batching is already in progress, this is a no-op.

N.B. #1 This is irrelevant to touch-related methods.

N.B. #2 Until the batch has been committed, the widget will be in an irregular state. In the interim, polling the widget's curl properties and getter methods will not in general yield correct results. Touch controls will likewise be out of sync.

PageCurlWidget:Capture (target)
Captures a target and sets it as the current page.

This will commit any batch in progress, cf. PageCurlWidget:Begin.

Parameters:

PageCurlWidget:Commit ()
If a batch is in progress, commits it. Otherwise, this is a no-op.

See also:

PageCurlWidget:Detach ([into])
The display object underlying the page is removed from the widget's control. Aside from changing parents, it keeps its most recent state; however, the widget is no longer able to affect it, and vice versa.

The widget itself is cleared to a blank rect; this will commit any batch in progress, cf. PageCurlWidget:Begin.

Parameters:

  • into DisplayGroup Group that will receive the object. If absent, the stage is used.

Returns:

    pobject Detached object.

See also:

PageCurlWidget:DisableTouch (no_reset)
Disables all touch controls.

Parameters:

  • no_reset bool Leave the page as is?

See also:

PageCurlWidget:EnableExpansion (enable)
Enables or disables expansion.

As a page curls, it tends to spill out of the boundaries of the underlying display object. To accommodate this, the object can effectively be expanded, and its textures will be read with this in mind.

When expansion is disabled, out-of-bounds pixels are clipped. This might suffice, for instance, if the area around the widget is already obscured, say when it fills the screen.

Expansion is enabled by default.

Parameters:

  • enable bool Enable expansion?
PageCurlWidget:EnableInnerShadows (enable)
Enables or disables inner shadows.

Once a page has begun curling, a subtle shadow can be applied inside the curl to convey the reduced incidence of light.

Inner shadows are enabled by default.

Parameters:

  • enable bool Enable inner shadows?
PageCurlWidget:GetGrabRegions ()
Gets the currently touchable regions.

The widget does not draw any of its touch components, but this method lets users know where those are, for instance in order to overlay custom display objects.

Returns:

    table Any (or none) of the bottom, left, right, or top keys may be present, corresponding to the sides enabled for touch. Their values are tables with x, y, width, and height members, matching the current center and size of the given side's grab region.

See also:

PageCurlWidget:GetSize ()
Gets the (unexpanded) page size.

Returns:

  1. uint Page width...
  2. uint ...and height.

See also:

PageCurlWidget:PrepareSnapshot ([width[, height]])
Prepares a snapshot and sets it as the current page. (When the widget is already using a snapshot, it simply updates that one.)

This will commit any batch in progress, cf. PageCurlWidget:Begin.

Parameters:

  • width uint Snapshot width... (If absent, the page's current value is reused.)
  • height uint ...and height. (Ditto.)

Returns:

    SnapshotObject The snapshot. Well-behaved code will change neither its position nor its dimensions and scale, nor manually remove it (see instead PageCurlWidget:Detach), but otherwise this is meant to be used like any snapshot.
PageCurlWidget:SetBackTextureMethod (how)
Sets the back texture behavior.

If how is unrecognized, this is a no-op.

Parameters:

  • how string

    One of the following:

    • "same": The front texture is reused on the back of the page. This is the default.
    • "none": The back of the page is blank, i.e. it has no texture.

See also:

PageCurlWidget:SetBlankRect ([opts])
Sets a blank rectangle as the current page.

This will commit any batch in progress, cf. PageCurlWidget:Begin.

Parameters:

  • opts table

    Configuration options. Fields:

    • width: Width to assign to page... (If absent, the current value is retained.)
    • height: ...and the height. (Ditto.)
PageCurlWidget:SetColor (...)
Sets the widget's color. This behaves like object:setFillColor, albeit constrained by the widget's color method.

White, i.e. 1, 1, 1, 1, is the default.

Parameters:

See also:

PageCurlWidget:SetColorMethod (how)
Sets the color behavior.

If how is unrecognized, this is a no-op.

Parameters:

  • how string

    One of the following:

    • "both": Color is applied to the front and back sides of the page. This is the default behavior.
    • "front_only": Color affects only the front side of the page.
    • "back_only": Color affects only the back side of the page.

See also:

PageCurlWidget:SetDirection (dir)
Sets the curl direction used by touch. Touch is enabled in the appropriate region and disabled elsewhere.

If dir is unrecognized, this is a no-op.

Parameters:

  • dir string One of "bottom_to_top", "left_to_right", "right_to_left", or "top_to_bottom".

See also:

PageCurlWidget:SetEdgeEffect (how)
Sets the edge effect.

Once a page has been curled a bit, its back side comes into view. An effect may be applied on or near the edges of this back leaf.

If how is unrecognized, this is a no-op.

Parameters:

  • how string

    One of the following:

    • "edge": Thin dark lines demarcate the back side edges. This is the default.
    • "none": No effect: back side pixels are not set off from those in front.
    • "shadow": Soft shadows overlay the front side of the page near the back's edges.
PageCurlWidget:SetFrontAndBackImages (front, back[, opts])
Sets two images as the current page, one for the front side and another for the back.

Parameters:

  • front string Filename of the front image...
  • back string ...and back image.

    This will commit any batch in progress, cf. PageCurlWidget:Begin.

  • opts table

    Configuration options. Fields:

    • dir1: Base directory of front... (The default is system.ResourceDirectory.)
    • dir2: ...and back. (Ditto.)
    • width: Width to assign to page... (When absent, the current value is retained.)
    • height: ...and the height. (Ditto.)
PageCurlWidget:SetImage (name[, opts])
Sets an image as the current page.

The back side of the page is determined by the back texture method, cf. PageCurlWidget:SetBackTextureMethod.

This will commit any batch in progress, cf. PageCurlWidget:Begin.

Parameters:

  • name string Filename of the image.
  • opts table

    Configuration options. Fields:

    • dir: Base directory of name. (When absent, this is system.ResourceDirectory.)
    • width: Width to assign to page... (If absent, the current value is retained.)
    • height: ...and the height. (Ditto.)
PageCurlWidget:SetTouchSides (how)
Enables touch on multiple sides, disabling the rest.

In each case, the curl direction is toward the opposite side, e.g. for the right side, the direction is right-to-left.

If how is unrecognized, this is a no-op.

Parameters:

  • how string This may be "bottom_and_top" or "left_and_right".

See also:

NewPageCurlWidget ([opts])
Constructs a new page curl widget.

The PageCurlWidget type derives from GroupObject. Well-behaved code should leave its children alone, as well as its dimensions and scale, but may otherwise treat it as a normal display group.

In addition to the properties common to all display groups, PageCurlWidget introduces edge_x, edge_y, angle, and angle_radians. These may be both read and written, say as local angle = my_curl_widget.angle and my_curl_widget.edge_x = .3.

The edge_x and edge_y properties mark a point along the edge where the page begins to curl, the so-called "curling axis". (Any such point is fine.) The coordinate system goes from left to right horizontally and top to bottom vertically, with a value of 0 corresponding to the left-hand side or top, and 1 to the right-hand side or bottom.

The angle property describes the direction of the outward-facing normal to this edge, i.e. along the direction of curl. Angles are denominated in degrees, going clockwise. The angle_radians property is provided as an alternative, accepting radians instead. This is merely a convenience, as both modify the same state.

The widget is designed for both programmatic and touch-based usage.

When touch is enabled, the widget dispatches the "page_dragged" event during any touch movement that updates the page. The widget can be accessed from a listener as event.target, and the side being touched (one of "bottom", "left", "top", or "right") is available as event.dir.

Likewise, "page_grabbed" and "page_released" events are fired when touch begins and ends, respectively. The target and dir members may again be found in event.

Parameters:

  • opts table

    Constructor options. Fields:

    • left: When present, this is the x-coordinate of the widget's left-hand side... (The default is 0.)
    • top: ...and this is the y-coordinate of its top. (The default is 0.)
    • width: The width of the initial (blank) rect... (When absent, a default is used.)
    • h: ...and the height. (Ditto.)
    • size: A positive integer used to size the grabbable regions, for touch purposes. This specifies both the thickness of each grab region and the amount of cushion added to include touches that are only slightly out-of-bounds. For instance, the bottom will have width and height of size + page width and size, respectively, whereas the right-hand side has size, size + page height. (When absent, a default is used.)

Returns:

    PageCurlWidget New page curl widget.
generated by LDoc 1.4.0