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

The ITouchable property interface.

This interface provides common properties of a touchable input object.


Table members

Methods


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.

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.

SetOutCoordClippingEnabled(enable)

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)

Parameters
enableIf true, output coordinates are being clipped.
Returns
Boolean true if successful.

IsOutCoordClippingEnabled()

Check if output coordinate clipping is enabled

Boolean IsOutCoordClippingEnabled()

Returns
Boolean true if enabled.

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.