![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
The IButton graph node interface.
This interface represents a common clickable or touchable button surface. A button by itself does not actually have any renderable geometry; instead, it only holds a specific surface shape on which any pointing events are evaluated in 3D space.
In general, a button can be in one of 3 available states: "Up", "Down" or "Disabled". For devices that provide a point input method other than a touch screen, such as a mouse, there also exists an additional "Hover" state. Internally, a button node acts similar to a Graph::ISwitch node, managing visibility of a subset of its child nodes that are assigned to these states. Depending on the actual state the button is in, the respective child node gets activated, and all other ones deactivated. If a child node is not assigned to one of these states, it is left unmanaged.
In addition, it is possible to define a single child node implementing the Graph::ITimeline interface to react on state changes. The assigned timeline will then be started to run up to a given time value set for that state.
Use the button's Graph::IScalable base interface to control the actual size of the button in 3D space; by default, predefined shapes such as rectangles and ellipses have an X and Y extent of 1.
Get the constant Graph::INode interface. This method returns a constant pointer to the node's Graph::INode interface, to be able to query common node properties such as active state, visibility or ID.
Murl.Graph.INode GetNodeInterface()
Get the constant Graph::ITransform interface. This method returns a constant pointer to the node's Graph::ITransform interface, to be able to query the node's transformation matrix and depth order.
Murl.Graph.ITransform GetTransformInterface()
Get the constant IFrameBufferNodeTarget container. This method returns a constant pointer to the node's IFrameBufferNodeTarget container, which allows to query the frame buffer object the button object delegates its input to.
Murl.Graph.IGenericNodeTarget.GraphIFrameBuffer GetFrameBufferNodeTarget()
Enable or disable the button. When the button is disabled, it is still being processed and drawn, but not reacting on any user input. To define the node that is active in the disabled state, use SetStateNodeId() or SetStateChildIndex() with IEnums::BUTTON_STATE_DISABLED.
Boolean SetEnabled(Boolean enabled)
enabled | If false, the button gets disabled. |
Check if the button is enabled.
Boolean IsEnabled()
Set which faces of the button are active.
Boolean SetActiveFaces(Murl.IEnums.PolygonFaces faces)
faces | One of the available IEnums::PolygonFaces enumeration values. |
Check which faces of the button are active.
Murl.IEnums.PolygonFaces GetActiveFaces()
Set the button's active node ID for a given state. Calling this method assigns one of the button's nodes to a given internal button state. If done so, that node will be activated whenever the button changes to this state, and deactivated when it changes to a different state.
Boolean SetStateNodeId(Murl.IEnums.ButtonState state, String nodeId)
state | The internal state to which the given node will be assigned. |
nodeId | The node ID of the node to assign. |
Get the ID of the button's active node for a given state.
String GetStateNodeId(Murl.IEnums.ButtonState state)
state | The internal state for which to query the assigned node. |
Set the button's active child for a given state. Calling this method assigns one of the button's children to a given internal button state. If done so, that child will be activated whenever the button changes to this state, and deactivated when it changes to a different state. All children that are not assigned to a specific button state behave normally.
As an example, a button may have four Graph::IParametersState children representing different button colors, each assigned to one of the four possible internal states, and a Graph::PlaneGeometry as an additional fifth child without state assignment. Depending on the button's current state, one of these parameter sets will be selected, and the plane geometry will be rendered in different colors.
Boolean SetStateChildIndex(Murl.IEnums.ButtonState state, Integer childIndex)
state | The internal state to which the given child will be assigned. |
childIndex | The zero-based index of the child node to assign. |
Get the index of the button's active child for a given state.
Integer GetStateChildIndex(Murl.IEnums.ButtonState state)
state | The internal state for which to query the assigned child. |
Set the target time value for a given state. When a timeline child node is defined via SetTimelineNodeId() or SetTimelineChildIndex(), this method sets the target time value to run to when the button is entering the given button state.
Boolean SetStateAnimationTime(Murl.IEnums.ButtonState state, Number time)
state | The button state for which to set the target time value. |
time | The target time value. |
Get the target time value set for a given state.
Number GetStateAnimationTime(Murl.IEnums.ButtonState state)
state | The button state for which to query the target time. |
Reset the target time value for a given state to 0.
Boolean ResetStateAnimationTime(Murl.IEnums.ButtonState state)
state | The button state for which to reset the target time value. |
Query if a target time value was set for a given button state.
Boolean IsStateAnimationTimeSet(Murl.IEnums.ButtonState state)
state | The button state to query. |
Define a timeline node from within the current graph namespace.
Boolean SetTimelineNodeId(String nodeId)
nodeId | The node ID of the timeline to assign. |
Query the node ID of an assigned timeline child.
String GetTimelineNodeId()
Define a timeline node among the button's children.
Boolean SetTimelineChildIndex(Integer nodeIndex)
nodeIndex | The zero-based child index of the timeline child to assign. |
Query the child index of an assigned timeline child.
Integer GetTimelineChildIndex()
Set the shape of the button's touch area.
Boolean SetShape(Murl.IEnums.TouchAreaShape shape)
shape | The shape to use. |
Get the shape of the button's touch area.
Murl.IEnums.TouchAreaShape GetShape()
Set the horizontal container alignment. The given alignment values specify how the text container is actually positioned with respect to the node's world position.
Boolean SetContainerAlignment(Murl.IEnums.AlignmentX alignmentX, Murl.IEnums.AlignmentY alignmentY)
alignmentX | The horizontal container alignment. |
alignmentY | The vertical container alignment. |
Set the horizontal container alignment. See SetContainerAlignment().
Boolean SetContainerAlignmentX(Murl.IEnums.AlignmentX alignmentX)
alignmentX | The horizontal container alignment. |
Set the vertical container alignment. See SetContainerAlignment().
Boolean SetContainerAlignmentY(Murl.IEnums.AlignmentY alignmentY)
alignmentY | The vertical container alignment. |
Get the horizontal container alignment.
Murl.IEnums.AlignmentX GetContainerAlignmentX()
Get the vertical container alignment.
Murl.IEnums.AlignmentY GetContainerAlignmentY()
Set the horizontal and vertical borders used for alignment.
Boolean SetBorder(Number borderX, Number borderY)
borderX | The horizontal border. |
borderY | The vertical border. |
Set the horizontal border used for alignment.
Boolean SetBorderX(Number borderX)
borderX | The horizontal border. |
Set the vertical border used for alignment.
Boolean SetBorderY(Number borderY)
borderY | The vertical border. |
Get the horizontal border used for alignment.
Number GetBorderX()
Get the vertical border used for alignment.
Number GetBorderY()
Set the output coordinate reference size. Generally, output coordinates are represented by values ranging from -1.0 to 1.0. As a convenience, this method can be used to set an arbitrary reference size for both dimensions of the button; this way it is possible to specify integer (pixel) values instead of (quite unreadable) floats. By default, both sizeX and sizeY are set to 1.0. See also Graph::IPlaneGeometry::SetTextureSize() for a texture equivalent, and Graph::IFrameBuffer::SetInCoordSize() for the counterpart taking the button's out coordinates as input. Note that if it is desired to map button coordinates directly to texture coordinates e.g. for using a button on a frame buffer, it may be useful to call SetOutCoord()/SetOutCoordSize() and the frame buffer's SetInCoord()/SetInCoordSize() with values equivalent to the texture coordinate values of the plane displaying the frame buffer contents.
Boolean SetOutCoordSize(Number sizeX, Number sizeY)
sizeX | The horizontal coordinate reference size. |
sizeY | The vertical coordinate reference size. |
Set the horizontal output coordinate reference size. See SetOutCoordSize().
Boolean SetOutCoordSizeX(Number sizeX)
sizeX | The horizontal coordinate reference size. |
Set the vertical output coordinate reference size. See SetOutCoordSize().
Boolean SetOutCoordSizeY(Number sizeY)
sizeY | The vertical coordinate reference size. |
Get the horizontal output coordinate reference size. See SetOutCoordSize().
Number GetOutCoordSizeX()
Get the vertical output coordinate reference size. See SetOutCoordSize().
Number GetOutCoordSizeY()
Set the button's output coordinate range. This method sets the button's start and end output coordinates. In contrast to a button event's local intersection point, which always represents the actual intersection in object-space 3D coordinates, an event's output coordinate represents a 2D intersection on the button's clickable surface. This can be interpreted analogously to a renderable geometry, with 3D vertex coordinates and 2D texture coordinates.
Boolean SetOutCoord(Number x1, Number y1, Number x2, Number y2)
x1 | The start coordinate in X direction. |
y1 | The start coordinate in Y direction. |
x2 | The end coordinate in X direction. |
y2 | The end coordinate in Y direction. |
Set the button's output coordinate start. See SetOutCoord().
Boolean SetOutCoord1(Number x1, Number y1)
x1 | The start coordinate in X direction. |
y1 | The start coordinate in Y direction. |
Set the button's output coordinate end. See SetOutCoord().
Boolean SetOutCoord2(Number x2, Number y2)
x2 | The end coordinate in X direction. |
y2 | The end coordinate in Y direction. |
Set the button's horizontal start output coordinate. See SetOutCoord().
Boolean SetOutCoordX1(Number x1)
x1 | The start coordinate in X direction. |
Set the button's vertical start output coordinates. See SetOutCoord().
Boolean SetOutCoordY1(Number y1)
y1 | The start coordinate in Y direction. |
Set the button's horizontal end output coordinate. See SetOutCoord().
Boolean SetOutCoordX2(Number x2)
x2 | The end coordinate in X direction. |
Set the button's vertical end output coordinates. See SetOutCoord().
Boolean SetOutCoordY2(Number y2)
y2 | The end coordinate in Y direction. |
Get the button's horizontal start output coordinate. See SetOutCoord().
Number GetOutCoordX1()
Get the button's vertical start output coordinate. See SetOutCoord().
Number GetOutCoordY1()
Get the button's horizontal end output coordinate. See SetOutCoord().
Number GetOutCoordX2()
Get the button's vertical end output coordinate. See SetOutCoord().
Number GetOutCoordY2()
Enable or disable output coordinate clipping. By default, clipping is disabled. If the button delegates its events to a given frame buffer (see GetFrameBufferNodeTarget()), this means that other buttons defined in the frame buffer also receive events even if they are actually outside this buttons range. Set enabled to true to restrict the frame buffer's input event area to this button's bounds.
Boolean SetOutCoordClippingEnabled(Boolean enable)
enable | If true, output coordinates are being clipped. |
Check if output coordinate clipping is enabled
Boolean IsOutCoordClippingEnabled()
Set the mouse button this button responds to.
Boolean SetResponseButton(Murl.IEnums.MouseButton button)
button | The mouse button used for input. |
Get the mouse button this button responds to.
Murl.IEnums.MouseButton GetResponseButton()
Enable or disable event pass through.
Boolean SetPassEventsEnabled(Boolean enable)
enable | If true events are passed through underlying buttons. |
Check event pass through is enabled.
Boolean IsPassEventsEnabled()
Set the maximum number of simultaneous touch events.
Boolean SetMaxNumberOfEvents(Integer value)
value | The maximum number of touch events that are evaluated simultaneously. |
Get the maximum number of simultaneous touch events.
Integer GetMaxNumberOfEvents()
Reset the tracking of all current events. Set the button state to IEnums::BUTTON_STATE_UP if enabled otherwise to IEnums::BUTTON_STATE_DISABLED.
Boolean ResetEvents()
Get the total number of active events. This method returns the total number of active input events, including any non-tracked events and events that are already in the "up" state. For mouse-like devices, this simply means move events without any button pressed. For touch screen-like devices, there is no actual move event in the "up" state, so any active event retains the state immediately before the finger was lifted.
Integer GetNumberOfActiveEvents()
Get the unique ID of a specific active event.
Integer GetActiveEventId(Integer activeEventIndex)
activeEventIndex | The event's index, in the range from 0 to GetNumberOfActiveEvents() - 1. |
Get the number of currently tracked events. This method returns the number of currently tracked events, i.e. all those events that began with a "down" action inside the button's bounds.
Integer GetNumberOfTrackedEvents()
Get the unique ID of a specific tracked event.
Integer GetTrackedEventId(Integer trackedEventIndex)
trackedEventIndex | The event's index, in the range from 0 to GetNumberOfTrackedEvents() - 1. |
Check if a given event has received updates from any input device during the most recent logic tick. Has to be considered when using GetLocalEventDelta().
Boolean HasEventUpdate(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Get the type of input device that reported the event with a given ID.
Murl.IEnums.InputDeviceType GetEventDeviceType(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Get the output coordinate of an event with a given ID, in 2D space.
Murl.Math.Vector GetEventOutCoord(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Get the position of an event with a given ID, in 3D object space.
Murl.Math.Vector GetLocalEventPosition(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Get the current position delta of an event with a given ID, in object space. If HasEventUpdate() returns false the delta is zero and should be ignored.
Murl.Math.Vector GetLocalEventDelta(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Check if a given event is in the "tracked" state.
Boolean IsEventTracked(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Check if a given event's incidence point is within the button's bounds. As an example, for a rectangular button (SetShape(IEnums::TOUCH_AREA_SHAPE_RECTANGLE)) without additional scale factor, this method returns true whenever the event's local X and Y coordinates are both in the range from -0.5 to +0.5.
Boolean IsEventInside(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Check if a given event is in the pressed state.
Boolean IsEventPressed(Integer id)
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Check if the button was pressed. This method returns true when a "down" action occurred during the most recent logic tick at a coordinate within the button's bounds, and the button was not already in the "down" state.
Boolean WasPressed()
Check if the button was released inside. This method returns true when the button was actually released during the most recent logic tick, i.e. when first a "down" action occurred on that button, and later on the corresponding "up" action occurred at a coordinate within the button's bounds.
Boolean WasReleasedInside()
Check if the button was released outside. This method returns true when a pending click action on the button was actually dismissed during the most recent logic tick, i.e. when first a "down" action occurred on that button, and later on the corresponding "up" action occurred at a coordinate outside the button's bounds.
Boolean WasReleasedOutside()
Get the position of the current button event, in object space. This method returns the current position of the last WasReleasedInside(), WasPressed() or WasReleased() event.
Murl.Math.Vector GetEventPosition()
Get the current button state.
Murl.IEnums.ButtonState GetButtonState()