Module lib.frames
Frames: stacks of shado objects (including sub-frames).
Functions
| Frame:new () | Create a new, empty frame. |
| Frame:add (item, x, y) | Add an item to a frame, at the top. |
| Frame:remove (item) | Remove a shado object from the frame. |
| Frame:top (item) | Bring a shado object to the top of a frame. |
| Frame:bottom (item) | Drop a shado object to the bottom of a frame. |
| Frame:hide (item) | Hide a shado object in a frame (effectively, make it transparent). |
| Frame:show (item) | Show a shado object in a frame. |
| Frame:moveTo (item, x, y) | Move an object in a frame to a new location. |
| Frame:get (i) | Retrieve an object from a frame. |
| Frame:getLamp (x, y) | Get the computed "lamp" value for a frame at location
(x, y). |
| Frame:press (x, y, how) | The default handler for button press events. |
| Frame:routePress00 (x, y) | Internal function for routing press-on events. |
Functions
- Frame:new ()
- Create a new, empty frame.
- Frame:add (item, x, y)
-
Add an item to a frame, at the top. Calls can be cascaded, thus:
frame:add(item1, x1, y1):add(item2, x2, y2)Note: an item should not be added to a frame more than once. (TODO Test for this.)
Parameters:
- item the shado object to add
- x
the horizontal location,
1being the origin - y
the vertical location,
1being the origin
Returns:
-
the frame
- Frame:remove (item)
-
Remove a shado object from the frame.
Raises an error if the item isn't present.
TODO Calls to remove should chain.
Parameters:
- item the shado object to remove
- Frame:top (item)
-
Bring a shado object to the top of a frame.
Raises an error if the item isn't present.
TODO Calls to top should chain.
Parameters:
- item the shado object to raise
- Frame:bottom (item)
-
Drop a shado object to the bottom of a frame.
Raises an error if the item isn't present.
TODO Calls to bottom should chain.
Parameters:
- item the shado object to lower
- Frame:hide (item)
-
Hide a shado object in a frame (effectively, make
it transparent). This does not affect its response
to button presses.
Parameters:
- item the object to hide
- Frame:show (item)
-
Show a shado object in a frame. This does
not affect its response to button presses.
Parameters:
- item the object to show
- Frame:moveTo (item, x, y)
-
Move an object in a frame to a new location.
Origin is
(1, 1).Returns the frame, for chaining.Parameters:
- item the object to move
- x the new X location
- y the new Y location
Returns:
-
the frame
- Frame:get (i)
-
Retrieve an object from a frame. The topmost
object is at index
1. Throws an error if the index is less than1or greater than the number of objects present.Parameters:
- i the index of the desired object
Returns:
-
the object
- Frame:getLamp (x, y)
-
Get the computed "lamp" value for a frame at location
(x, y). If the frame is empty, or the coordinates(x, y)are outside any objects in the frame, the result will betypes.LampState.THRU.Parameters:
- x the X location to examine
- y the Y location to examine
Returns:
-
the lamp value
See also:
- Frame:press (x, y, how)
-
The default handler for button press events. It returns
false, which will cause press events to be passed into the frame's component objects. Override to handle buttons in the frame itself, rather than its components.Parameters:
- x the X location of the press
- y the Y location of the press
- how
the kind of button event:
1for press,0for release.
Returns:
false - Frame:routePress00 (x, y)
-
Internal function for routing press-on events. Returns a
RouteResultobject so that the corresponding press-off can be handled properly.If the frame itself does not handle the press, then the constituent objects are interrogated from top to bottom, until one does handle it (by returning a result from its routePress00 method). If there is no result, then the frame as a whole has not handled the press, so return
nil.Parameters:
- x TODO
- y if we care: what if stack content changes as a result of press() calls? (We should dup.)