Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.IButton

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.


Table members

Inherited


Murl.Graph.IScalable

Methods


GetNodeInterface()

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()

Returns
Murl.Graph.INode The constant Graph::INode interface, or null if not available

GetTransformInterface()

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()

Returns
Murl.Graph.ITransform The constant Graph::ITransform interface, or null if not available

GetFrameBufferNodeTarget()

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()

Returns
Murl.Graph.IGenericNodeTarget.GraphIFrameBuffer The constant IFrameBufferNodeTarget container, or null if not available

SetEnabled(enabled)

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)

Parameters
enabledIf false, the button gets disabled.
Returns
Boolean true if successful.

IsEnabled()

Check if the button is enabled.

Boolean IsEnabled()

Returns
Boolean true if enabled.

SetActiveFaces(faces)

Set which faces of the button are active.

Boolean SetActiveFaces(Murl.IEnums.PolygonFaces faces)

Parameters
facesOne of the available IEnums::PolygonFaces enumeration values.
Returns
Boolean true if successful.

GetActiveFaces()

Check which faces of the button are active.

Murl.IEnums.PolygonFaces GetActiveFaces()

Returns
Murl.IEnums.PolygonFaces One of the available IEnums::PolygonFaces enumeration values.

SetStateNodeId(state, nodeId)

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)

Parameters
stateThe internal state to which the given node will be assigned.
nodeIdThe node ID of the node to assign.
Returns
Boolean true if successful.

GetStateNodeId(state)

Get the ID of the button's active node for a given state.

String GetStateNodeId(Murl.IEnums.ButtonState state)

Parameters
stateThe internal state for which to query the assigned node.
Returns
String The ID of the assigned node, or an empty string if there is no present assignment for the givent state.

SetStateChildIndex(state, childIndex)

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)

Parameters
stateThe internal state to which the given child will be assigned.
childIndexThe zero-based index of the child node to assign.
Returns
Boolean true if successful.

GetStateChildIndex(state)

Get the index of the button's active child for a given state.

Integer GetStateChildIndex(Murl.IEnums.ButtonState state)

Parameters
stateThe internal state for which to query the assigned child.
Returns
Integer The zero-based index into the button's array of children, or -1 if there is no present assignment for the givent state.

SetStateAnimationTime(state, time)

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)

Parameters
stateThe button state for which to set the target time value.
timeThe target time value.
Returns
Boolean true if successful.

GetStateAnimationTime(state)

Get the target time value set for a given state.

Number GetStateAnimationTime(Murl.IEnums.ButtonState state)

Parameters
stateThe button state for which to query the target time.
Returns
Number The target time value.

ResetStateAnimationTime(state)

Reset the target time value for a given state to 0.

Boolean ResetStateAnimationTime(Murl.IEnums.ButtonState state)

Parameters
stateThe button state for which to reset the target time value.
Returns
Boolean true if successful.

IsStateAnimationTimeSet(state)

Query if a target time value was set for a given button state.

Boolean IsStateAnimationTimeSet(Murl.IEnums.ButtonState state)

Parameters
stateThe button state to query.
Returns
Boolean true if a target time value was set for the given state.

SetTimelineNodeId(nodeId)

Define a timeline node from within the current graph namespace.

Boolean SetTimelineNodeId(String nodeId)

Parameters
nodeIdThe node ID of the timeline to assign.
Returns
Boolean true if successful.

GetTimelineNodeId()

Query the node ID of an assigned timeline child.

String GetTimelineNodeId()

Returns
String The node id of the assigned timeline child, or an empty string if no timeline was assigned or a child was explicitly assigned by its child index.

SetTimelineChildIndex(nodeIndex)

Define a timeline node among the button's children.

Boolean SetTimelineChildIndex(Integer nodeIndex)

Parameters
nodeIndexThe zero-based child index of the timeline child to assign.
Returns
Boolean true if successful.

GetTimelineChildIndex()

Query the child index of an assigned timeline child.

Integer GetTimelineChildIndex()

Returns
Integer The zero-based child index of the assigned timeline child, or -1 if no explicit child was assigned or a different timeline node was used from the current namespace via SetTimelineNodeId().

SetShape(shape)

Set the shape of the button's touch area.

Boolean SetShape(Murl.IEnums.TouchAreaShape shape)

Parameters
shapeThe shape to use.
Returns
Boolean true if successful.

GetShape()

Get the shape of the button's touch area.

Murl.IEnums.TouchAreaShape GetShape()

Returns
Murl.IEnums.TouchAreaShape The touch area's shape.

SetContainerAlignment(alignmentX, alignmentY)

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)

Parameters
alignmentXThe horizontal container alignment.
alignmentYThe vertical container alignment.
Returns
Boolean true if successful.

SetContainerAlignmentX(alignmentX)

Set the horizontal container alignment. See SetContainerAlignment().

Boolean SetContainerAlignmentX(Murl.IEnums.AlignmentX alignmentX)

Parameters
alignmentXThe horizontal container alignment.
Returns
Boolean true if successful.

SetContainerAlignmentY(alignmentY)

Set the vertical container alignment. See SetContainerAlignment().

Boolean SetContainerAlignmentY(Murl.IEnums.AlignmentY alignmentY)

Parameters
alignmentYThe vertical container alignment.
Returns
Boolean true if successful.

GetContainerAlignmentX()

Get the horizontal container alignment.

Murl.IEnums.AlignmentX GetContainerAlignmentX()

Returns
Murl.IEnums.AlignmentX The horizontal container alignment.

GetContainerAlignmentY()

Get the vertical container alignment.

Murl.IEnums.AlignmentY GetContainerAlignmentY()

Returns
Murl.IEnums.AlignmentY The vertical container alignment.

SetBorder(borderX, borderY)

Set the horizontal and vertical borders used for alignment.

Boolean SetBorder(Number borderX, Number borderY)

Parameters
borderXThe horizontal border.
borderYThe vertical border.
Returns
Boolean true if successful.

SetBorderX(borderX)

Set the horizontal border used for alignment.

Boolean SetBorderX(Number borderX)

Parameters
borderXThe horizontal border.
Returns
Boolean true if successful.

SetBorderY(borderY)

Set the vertical border used for alignment.

Boolean SetBorderY(Number borderY)

Parameters
borderYThe vertical border.
Returns
Boolean true if successful.

GetBorderX()

Get the horizontal border used for alignment.

Number GetBorderX()

Returns
Number The horizontal border.

GetBorderY()

Get the vertical border used for alignment.

Number GetBorderY()

Returns
Number The vertical border.

SetOutCoordSize(sizeX, sizeY)

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)

Parameters
sizeXThe horizontal coordinate reference size.
sizeYThe vertical coordinate reference size.
Returns
Boolean true if successful.

SetOutCoordSizeX(sizeX)

Set the horizontal output coordinate reference size. See SetOutCoordSize().

Boolean SetOutCoordSizeX(Number sizeX)

Parameters
sizeXThe horizontal coordinate reference size.
Returns
Boolean true if successful.

SetOutCoordSizeY(sizeY)

Set the vertical output coordinate reference size. See SetOutCoordSize().

Boolean SetOutCoordSizeY(Number sizeY)

Parameters
sizeYThe vertical coordinate reference size.
Returns
Boolean true if successful.

GetOutCoordSizeX()

Get the horizontal output coordinate reference size. See SetOutCoordSize().

Number GetOutCoordSizeX()

Returns
Number The horizontal output coordinate reference size.

GetOutCoordSizeY()

Get the vertical output coordinate reference size. See SetOutCoordSize().

Number GetOutCoordSizeY()

Returns
Number The vertical output coordinate reference size.

SetOutCoord(x1, y1, x2, y2)

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)

Parameters
x1The start coordinate in X direction.
y1The start coordinate in Y direction.
x2The end coordinate in X direction.
y2The end coordinate in Y direction.
Returns
Boolean true if successful.

SetOutCoord1(x1, y1)

Set the button's output coordinate start. See SetOutCoord().

Boolean SetOutCoord1(Number x1, Number y1)

Parameters
x1The start coordinate in X direction.
y1The start coordinate in Y direction.
Returns
Boolean true if successful.

SetOutCoord2(x2, y2)

Set the button's output coordinate end. See SetOutCoord().

Boolean SetOutCoord2(Number x2, Number y2)

Parameters
x2The end coordinate in X direction.
y2The end coordinate in Y direction.
Returns
Boolean true if successful.

SetOutCoordX1(x1)

Set the button's horizontal start output coordinate. See SetOutCoord().

Boolean SetOutCoordX1(Number x1)

Parameters
x1The start coordinate in X direction.
Returns
Boolean true if successful.

SetOutCoordY1(y1)

Set the button's vertical start output coordinates. See SetOutCoord().

Boolean SetOutCoordY1(Number y1)

Parameters
y1The start coordinate in Y direction.
Returns
Boolean true if successful.

SetOutCoordX2(x2)

Set the button's horizontal end output coordinate. See SetOutCoord().

Boolean SetOutCoordX2(Number x2)

Parameters
x2The end coordinate in X direction.
Returns
Boolean true if successful.

SetOutCoordY2(y2)

Set the button's vertical end output coordinates. See SetOutCoord().

Boolean SetOutCoordY2(Number y2)

Parameters
y2The end coordinate in Y direction.
Returns
Boolean true if successful.

GetOutCoordX1()

Get the button's horizontal start output coordinate. See SetOutCoord().

Number GetOutCoordX1()

Returns
Number The start coordinate in X direction.

GetOutCoordY1()

Get the button's vertical start output coordinate. See SetOutCoord().

Number GetOutCoordY1()

Returns
Number The start coordinate in Y direction.

GetOutCoordX2()

Get the button's horizontal end output coordinate. See SetOutCoord().

Number GetOutCoordX2()

Returns
Number The end coordinate in X direction.

GetOutCoordY2()

Get the button's vertical end output coordinate. See SetOutCoord().

Number GetOutCoordY2()

Returns
Number The end coordinate in Y direction.

SetResponseButton(button)

Set the mouse button this button responds to.

Boolean SetResponseButton(Murl.IEnums.MouseButton button)

Parameters
buttonThe mouse button used for input.
Returns
Boolean true if successful.

GetResponseButton()

Get the mouse button this button responds to.

Murl.IEnums.MouseButton GetResponseButton()

Returns
Murl.IEnums.MouseButton The mouse button used for input.

SetPassEventsEnabled(enable)

Enable or disable event pass through.

Boolean SetPassEventsEnabled(Boolean enable)

Parameters
enableIf true events are passed through underlying buttons.
Returns
Boolean true if successful.

IsPassEventsEnabled()

Check event pass through is enabled.

Boolean IsPassEventsEnabled()

Returns
Boolean true if events are passed through underlying buttons.

SetMaxNumberOfEvents(value)

Set the maximum number of simultaneous touch events.

Boolean SetMaxNumberOfEvents(Integer value)

Parameters
valueThe maximum number of touch events that are evaluated simultaneously.
Returns
Boolean true if successful.

GetMaxNumberOfEvents()

Get the maximum number of simultaneous touch events.

Integer GetMaxNumberOfEvents()

Returns
Integer The maximum number of touch events that are evaluated simultaneously.

ResetEvents()

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()

Returns
Boolean true if successful.

GetNumberOfActiveEvents()

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()

Returns
Integer The total number of active events.

GetActiveEventId(activeEventIndex)

Get the unique ID of a specific active event.

Integer GetActiveEventId(Integer activeEventIndex)

Parameters
activeEventIndexThe event's index, in the range from 0 to GetNumberOfActiveEvents() - 1.
Returns
Integer The active event's ID.

GetNumberOfTrackedEvents()

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()

Returns
Integer The number of currently tracked events.

GetTrackedEventId(trackedEventIndex)

Get the unique ID of a specific tracked event.

Integer GetTrackedEventId(Integer trackedEventIndex)

Parameters
trackedEventIndexThe event's index, in the range from 0 to GetNumberOfTrackedEvents() - 1.
Returns
Integer The tracked event's ID.

HasEventUpdate(id)

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)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Boolean true if the event has received updates.

GetEventDeviceType(id)

Get the type of input device that reported the event with a given ID.

Murl.IEnums.InputDeviceType GetEventDeviceType(Integer id)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Murl.IEnums.InputDeviceType The input device type.

GetEventOutCoord(id)

Get the output coordinate of an event with a given ID, in 2D space.

Murl.Math.Vector GetEventOutCoord(Integer id)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Murl.Math.Vector A const reference to the event's current out coordinate.

GetLocalEventPosition(id)

Get the position of an event with a given ID, in 3D object space.

Murl.Math.Vector GetLocalEventPosition(Integer id)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Murl.Math.Vector A const reference to the event's current local position.

GetLocalEventDelta(id)

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)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Murl.Math.Vector A const reference to the event's current local position delta.

IsEventTracked(id)

Check if a given event is in the "tracked" state.

Boolean IsEventTracked(Integer id)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Boolean true if the event is currently tracked.

IsEventInside(id)

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)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Boolean true if the event is inside.

IsEventPressed(id)

Check if a given event is in the pressed state.

Boolean IsEventPressed(Integer id)

Parameters
idThe ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId().
Returns
Boolean true if the event is currently in the pressed state.

WasPressed()

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()

Returns
Boolean true if the button was pressed.

WasReleasedInside()

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()

Returns
Boolean true if the button was clicked.

WasReleasedOutside()

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()

Returns
Boolean true if the button was released.

GetEventPosition()

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()

Returns
Murl.Math.Vector A const reference to the event's current local position.

GetButtonState()

Get the current button state.

Murl.IEnums.ButtonState GetButtonState()

Returns
Murl.IEnums.ButtonState The current button state.