![]() |
Murl Engine API
Version 2018.3
|
The IButton graph node interface. More...
#include <murl_graph_i_button.h>
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.
Public Member Functions | |
virtual INode * | GetNodeInterface ()=0 |
Get the mutable Graph::INode interface. More... | |
virtual const INode * | GetNodeInterface () const =0 |
Get the constant Graph::INode interface. More... | |
virtual ITransform * | GetTransformInterface ()=0 |
Get the mutable Graph::ITransform interface. More... | |
virtual const ITransform * | GetTransformInterface () const =0 |
Get the constant Graph::ITransform interface. More... | |
virtual IFrameBufferNodeTarget * | GetFrameBufferNodeTarget ()=0 |
Get the mutable IFrameBufferNodeTarget container. More... | |
virtual const IFrameBufferNodeTarget * | GetFrameBufferNodeTarget () const =0 |
Get the constant IFrameBufferNodeTarget container. More... | |
virtual Bool | SetEnabled (Bool enabled)=0 |
Enable or disable the button. More... | |
virtual Bool | IsEnabled () const =0 |
Check if the button is enabled. More... | |
virtual Bool | SetActiveFaces (IEnums::PolygonFaces faces)=0 |
Set which faces of the button are active. More... | |
virtual IEnums::PolygonFaces | GetActiveFaces () const =0 |
Check which faces of the button are active. More... | |
virtual Bool | SetStateNodeId (IEnums::ButtonState state, const String &nodeId)=0 |
Set the button's active node ID for a given state. More... | |
virtual const String & | GetStateNodeId (IEnums::ButtonState state) const =0 |
Get the ID of the button's active node for a given state. More... | |
virtual Bool | SetStateChildIndex (IEnums::ButtonState state, SInt32 childIndex)=0 |
Set the button's active child for a given state. More... | |
virtual SInt32 | GetStateChildIndex (IEnums::ButtonState state) const =0 |
Get the index of the button's active child for a given state. More... | |
virtual Bool | SetStateAnimationTime (IEnums::ButtonState state, Real time)=0 |
Set the target time value for a given state. More... | |
virtual Real | GetStateAnimationTime (IEnums::ButtonState state) const =0 |
Get the target time value set for a given state. More... | |
virtual Bool | ResetStateAnimationTime (IEnums::ButtonState state)=0 |
Reset the target time value for a given state to 0. More... | |
virtual Bool | IsStateAnimationTimeSet (IEnums::ButtonState state) const =0 |
Query if a target time value was set for a given button state. More... | |
virtual Bool | SetTimelineNodeId (const String &nodeId)=0 |
Define a timeline node from within the current graph namespace. More... | |
virtual const String & | GetTimelineNodeId () const =0 |
Query the node ID of an assigned timeline child. More... | |
virtual Bool | SetTimelineChildIndex (SInt32 nodeIndex)=0 |
Define a timeline node among the button's children. More... | |
virtual SInt32 | GetTimelineChildIndex () const =0 |
Query the child index of an assigned timeline child. More... | |
virtual Bool | SetShape (IEnums::TouchAreaShape shape)=0 |
Set the shape of the button's touch area. More... | |
virtual IEnums::TouchAreaShape | GetShape () const =0 |
Get the shape of the button's touch area. More... | |
virtual Bool | SetContainerAlignment (IEnums::AlignmentX alignmentX, IEnums::AlignmentY alignmentY)=0 |
Set the horizontal container alignment. More... | |
virtual Bool | SetContainerAlignmentX (IEnums::AlignmentX alignmentX)=0 |
Set the horizontal container alignment. More... | |
virtual Bool | SetContainerAlignmentY (IEnums::AlignmentY alignmentY)=0 |
Set the vertical container alignment. More... | |
virtual IEnums::AlignmentX | GetContainerAlignmentX () const =0 |
Get the horizontal container alignment. More... | |
virtual IEnums::AlignmentY | GetContainerAlignmentY () const =0 |
Get the vertical container alignment. More... | |
virtual Bool | SetBorder (Real borderX, Real borderY)=0 |
Set the horizontal and vertical borders used for alignment. More... | |
virtual Bool | SetBorderX (Real borderX)=0 |
Set the horizontal border used for alignment. More... | |
virtual Bool | SetBorderY (Real borderY)=0 |
Set the vertical border used for alignment. More... | |
virtual Real | GetBorderX () const =0 |
Get the horizontal border used for alignment. More... | |
virtual Real | GetBorderY () const =0 |
Get the vertical border used for alignment. More... | |
virtual Bool | SetOutCoordSize (Real sizeX, Real sizeY)=0 |
Set the output coordinate reference size. More... | |
virtual Bool | SetOutCoordSizeX (Real sizeX)=0 |
Set the horizontal output coordinate reference size. More... | |
virtual Bool | SetOutCoordSizeY (Real sizeY)=0 |
Set the vertical output coordinate reference size. More... | |
virtual Real | GetOutCoordSizeX () const =0 |
Get the horizontal output coordinate reference size. More... | |
virtual Real | GetOutCoordSizeY () const =0 |
Get the vertical output coordinate reference size. More... | |
virtual Bool | SetOutCoord (Real x1, Real y1, Real x2, Real y2)=0 |
Set the button's output coordinate range. More... | |
virtual Bool | SetOutCoord1 (Real x1, Real y1)=0 |
Set the button's output coordinate start. More... | |
virtual Bool | SetOutCoord2 (Real x2, Real y2)=0 |
Set the button's output coordinate end. More... | |
virtual Bool | SetOutCoordX1 (Real x1)=0 |
Set the button's horizontal start output coordinate. More... | |
virtual Bool | SetOutCoordY1 (Real y1)=0 |
Set the button's vertical start output coordinates. More... | |
virtual Bool | SetOutCoordX2 (Real x2)=0 |
Set the button's horizontal end output coordinate. More... | |
virtual Bool | SetOutCoordY2 (Real y2)=0 |
Set the button's vertical end output coordinates. More... | |
virtual Real | GetOutCoordX1 () const =0 |
Get the button's horizontal start output coordinate. More... | |
virtual Real | GetOutCoordY1 () const =0 |
Get the button's vertical start output coordinate. More... | |
virtual Real | GetOutCoordX2 () const =0 |
Get the button's horizontal end output coordinate. More... | |
virtual Real | GetOutCoordY2 () const =0 |
Get the button's vertical end output coordinate. More... | |
virtual Bool | SetResponseButton (IEnums::MouseButton button)=0 |
Set the mouse button this button responds to. More... | |
virtual IEnums::MouseButton | GetResponseButton () const =0 |
Get the mouse button this button responds to. More... | |
virtual Bool | SetPassEventsEnabled (Bool enable)=0 |
Enable or disable event pass through. More... | |
virtual Bool | IsPassEventsEnabled () const =0 |
Check event pass through is enabled. More... | |
virtual Bool | SetMaxNumberOfEvents (UInt32 value)=0 |
Set the maximum number of simultaneous touch events. More... | |
virtual UInt32 | GetMaxNumberOfEvents () const =0 |
Get the maximum number of simultaneous touch events. More... | |
virtual Bool | ResetEvents ()=0 |
Reset the tracking of all current events. More... | |
virtual UInt32 | GetNumberOfActiveEvents () const =0 |
Get the total number of active events. More... | |
virtual UInt32 | GetActiveEventId (UInt32 activeEventIndex) const =0 |
Get the unique ID of a specific active event. More... | |
virtual UInt32 | GetNumberOfTrackedEvents () const =0 |
Get the number of currently tracked events. More... | |
virtual UInt32 | GetTrackedEventId (UInt32 trackedEventIndex) const =0 |
Get the unique ID of a specific tracked event. More... | |
virtual Bool | HasEventUpdate (UInt32 id) const =0 |
Check if a given event has received updates from any input device during the most recent logic tick. More... | |
virtual IEnums::InputDeviceType | GetEventDeviceType (UInt32 id) const =0 |
Get the type of input device that reported the event with a given ID. More... | |
virtual const Vector & | GetEventOutCoord (UInt32 id) const =0 |
Get the output coordinate of an event with a given ID, in 2D space. More... | |
virtual const Vector & | GetLocalEventPosition (UInt32 id) const =0 |
Get the position of an event with a given ID, in 3D object space. More... | |
virtual const Vector & | GetLocalEventDelta (UInt32 id) const =0 |
Get the current position delta of an event with a given ID, in object space. More... | |
virtual Bool | IsEventTracked (UInt32 id) const =0 |
Check if a given event is in the "tracked" state. More... | |
virtual Bool | IsEventInside (UInt32 id) const =0 |
Check if a given event's incidence point is within the button's bounds. More... | |
virtual Bool | IsEventPressed (UInt32 id) const =0 |
Check if a given event is in the pressed state. More... | |
virtual Bool | WasPressed () const =0 |
Check if the button was pressed. More... | |
virtual Bool | WasReleasedInside () const =0 |
Check if the button was released inside. More... | |
virtual Bool | WasReleasedOutside () const =0 |
Check if the button was released outside. More... | |
virtual const Vector & | GetEventPosition () const =0 |
Get the position of the current button event, in object space. More... | |
virtual IEnums::ButtonState | GetButtonState () const =0 |
Get the current button state. More... | |
![]() | |
virtual Bool | SetScaleFactor (const Vector &scaleFactor)=0 |
Set individual scaling factors for the X, Y and Z axes. More... | |
virtual Bool | SetScaleFactor (Real x, Real y, Real z)=0 |
Set individual scaling factors for the X, Y and Z axes. More... | |
virtual Bool | SetScaleFactor (Real s)=0 |
Set a uniform scaling factor for all three axes. More... | |
virtual Bool | SetScaleFactorX (Real x)=0 |
Set the scaling factor for the X axis only. More... | |
virtual Bool | SetScaleFactorY (Real y)=0 |
Set the scaling factor for the Y axis only. More... | |
virtual Bool | SetScaleFactorZ (Real z)=0 |
Set the scaling factor for the Z axis only. More... | |
virtual const Vector & | GetScaleFactor () const =0 |
Get the scaling factors for the X, Y and Z axes. More... | |
virtual Real | GetScaleFactorX () const =0 |
Get the scaling factor for the X axis. More... | |
virtual Real | GetScaleFactorY () const =0 |
Get the scaling factor for the Y axis. More... | |
virtual Real | GetScaleFactorZ () const =0 |
Get the scaling factor for the Z axis. More... | |
|
pure virtual |
Get the mutable Graph::INode interface.
This method returns a mutable pointer to the node's Graph::INode interface, to be able to query or modify common node properties such as active state, visibility or ID.
|
pure virtual |
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.
|
pure virtual |
Get the mutable Graph::ITransform interface.
This method returns a mutable pointer to the node's Graph::ITransform interface, to be able to query or modify the node's transformation matrix and depth order.
|
pure virtual |
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.
|
pure virtual |
Get the mutable IFrameBufferNodeTarget container.
This method returns a mutable pointer to the node's IFrameBufferNodeTarget container, which allows to set or query the frame buffer object the button object delegates its input to.
|
pure virtual |
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.
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.
enabled | If false, the button gets disabled. |
|
pure virtual |
Check if the button is enabled.
|
pure virtual |
Set which faces of the button are active.
faces | One of the available IEnums::PolygonFaces enumeration values. |
|
pure virtual |
Check which faces of the button are active.
|
pure virtual |
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.
state | The internal state to which the given node will be assigned. |
nodeId | The node ID of the node to assign. |
|
pure virtual |
Get the ID of the button's active node for a given state.
state | The internal state for which to query the assigned node. |
|
pure virtual |
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.
state | The internal state to which the given child will be assigned. |
childIndex | The zero-based index of the child node to assign. |
|
pure virtual |
Get the index of the button's active child for a given state.
state | The internal state for which to query the assigned child. |
|
pure virtual |
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.
state | The button state for which to set the target time value. |
time | The target time value. |
|
pure virtual |
Get the target time value set for a given state.
state | The button state for which to query the target time. |
|
pure virtual |
Reset the target time value for a given state to 0.
state | The button state for which to reset the target time value. |
|
pure virtual |
Query if a target time value was set for a given button state.
state | The button state to query. |
Define a timeline node from within the current graph namespace.
nodeId | The node ID of the timeline to assign. |
|
pure virtual |
Query the node ID of an assigned timeline child.
Define a timeline node among the button's children.
nodeIndex | The zero-based child index of the timeline child to assign. |
|
pure virtual |
Query the child index of an assigned timeline child.
|
pure virtual |
Set the shape of the button's touch area.
shape | The shape to use. |
|
pure virtual |
Get the shape of the button's touch area.
|
pure virtual |
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.
alignmentX | The horizontal container alignment. |
alignmentY | The vertical container alignment. |
|
pure virtual |
Set the horizontal container alignment.
alignmentX | The horizontal container alignment. |
|
pure virtual |
Set the vertical container alignment.
alignmentY | The vertical container alignment. |
|
pure virtual |
Get the horizontal container alignment.
|
pure virtual |
Get the vertical container alignment.
Set the horizontal and vertical borders used for alignment.
borderX | The horizontal border. |
borderY | The vertical border. |
Set the horizontal border used for alignment.
borderX | The horizontal border. |
Set the vertical border used for alignment.
borderY | The vertical border. |
|
pure virtual |
Get the horizontal border used for alignment.
|
pure virtual |
Get the vertical border used for alignment.
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.
sizeX | The horizontal coordinate reference size. |
sizeY | The vertical coordinate reference size. |
Set the horizontal output coordinate reference size.
See SetOutCoordSize().
sizeX | The horizontal coordinate reference size. |
Set the vertical output coordinate reference size.
See SetOutCoordSize().
sizeY | The vertical coordinate reference size. |
|
pure virtual |
Get the horizontal output coordinate reference size.
See SetOutCoordSize().
|
pure virtual |
Get the vertical output coordinate reference size.
See SetOutCoordSize().
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.
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().
x1 | The start coordinate in X direction. |
y1 | The start coordinate in Y direction. |
Set the button's output coordinate end.
See SetOutCoord().
x2 | The end coordinate in X direction. |
y2 | The end coordinate in Y direction. |
Set the button's horizontal start output coordinate.
See SetOutCoord().
x1 | The start coordinate in X direction. |
Set the button's vertical start output coordinates.
See SetOutCoord().
y1 | The start coordinate in Y direction. |
Set the button's horizontal end output coordinate.
See SetOutCoord().
x2 | The end coordinate in X direction. |
Set the button's vertical end output coordinates.
See SetOutCoord().
y2 | The end coordinate in Y direction. |
|
pure virtual |
Get the button's horizontal start output coordinate.
See SetOutCoord().
|
pure virtual |
Get the button's vertical start output coordinate.
See SetOutCoord().
|
pure virtual |
Get the button's horizontal end output coordinate.
See SetOutCoord().
|
pure virtual |
Get the button's vertical end output coordinate.
See SetOutCoord().
|
pure virtual |
Set the mouse button this button responds to.
button | The mouse button used for input. |
|
pure virtual |
Get the mouse button this button responds to.
Enable or disable event pass through.
enable | If true events are passed through underlying buttons. |
|
pure virtual |
Check event pass through is enabled.
Set the maximum number of simultaneous touch events.
value | The maximum number of touch events that are evaluated simultaneously. |
|
pure virtual |
Get the maximum number of simultaneous touch events.
|
pure virtual |
Reset the tracking of all current events.
Set the button state to IEnums::BUTTON_STATE_UP if enabled otherwise to IEnums::BUTTON_STATE_DISABLED.
|
pure virtual |
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.
Get the unique ID of a specific active event.
activeEventIndex | The event's index, in the range from 0 to GetNumberOfActiveEvents() - 1. |
|
pure virtual |
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.
|
pure virtual |
Get the unique ID of a specific tracked event.
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().
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
|
pure virtual |
Get the type of input device that reported the event with a given 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.
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.
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.
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Check if a given event is in the "tracked" state.
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.
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
Check if a given event is in the pressed state.
id | The ID of the event to query, retrieved from GetActiveEventId() or GetTrackedEventId(). |
|
pure virtual |
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.
|
pure virtual |
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.
|
pure virtual |
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.
|
pure virtual |
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.
|
pure virtual |
Get the current button state.