Button2D
- Last UpdatedFeb 19, 2025
- 5 minute read
The Button2D node provides full pushbutton functionality. A button can assume different states. You can assign a different image or color to each state.
Platform support
This node is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-Portable WASM platforms.
|
XR-WIN |
XR-P-WIN |
XR-P-IOS |
XR-P-AND |
XR-P-WASM |
|---|---|---|---|---|
|
Full support |
Full support |
Full support |
Full support |
Full support |
|
|
|
|
|
|
Button modes
Button2D supports three button behaviors.
|
Behavior |
Description |
|---|---|
|
push |
A standard stateless pushbutton. When the button is released, it returns to original position. |
|
toggle |
A stateful button. When clicked, the toggle switches its state between pressed and released. Use buttonDown parameter to read toggle state. Toggle buttons do not support Over state. |
|
radio |
A grouped stateful button. Create a group of radio buttons by setting them all to radio mode and assigning the same radioGroup name. Only one button in the radio group can be in pressed state. Pressing another button releases the previously pressed button. |
Button states
The Button2D has different states. Each state corresponds to an image or color that may be defined.
|
State |
When |
Corresponding image |
Corresponding color (if image is not set) |
|---|---|---|---|
|
Normal |
Enabled, no over, no click |
image |
color |
|
Over |
Enabled, over, no click |
imageOver |
colorOver |
|
Click |
Enabled, Click |
imageDown |
colorDown |
|
Disabled |
Not enabled |
imageDisabled |
colorDisabled |
Code example
This is a code example for Button2D.
Button2D name="aButton" templateInfo="Button2D|aButton" position="128.932 472.892" order="1" size="200 50" visible="true" image="light_orange.tga" imageDown="yellow.tga"/>
Image color filter modes
The following options define the strategy to use when applying a color filter to an image:
-
none—The selected color is not applied to the images.
-
screen—The selected color is added to the image. This makes the image brighter and has more effect on dark colors. Black color is colored, light colors will tend to white, and white color stays white (since it is already the lightest color possible). This mode is suited to color black or dark glyphs by a selected color.
-
multiply—The image colors are multiplied by the selected color. This makes the images darker and has more effect on light colors. White color is colored, dark colors will tend to black, and black color stays black (since it is already the darkest color possible). This mode is suited to color white or light glyphs by a selected color.
-
overlay—Applies both screen and multiply strategies to the image by the selected color. This keeps the image brightness almost the same, has a balanced influence on light and dark colors, and allows to color both black and white.
-
invert—Inverts the color of the displayed image. The selected color is not used in this mode.
Button2D fields
These are the fields for Button2D node. Only the node-specific fields are indicated, not fields obtained by inheritance.
Field inheritance: NodeBase > RectBase2D > Button2D
|
Fields |
Type |
Use |
Default value |
Description |
|---|---|---|---|---|
|
buttonDown |
sbool |
Optional |
Read only |
true when the button is pressed. |
|
changeOnUp |
sbool |
Optional |
false |
This field enables custom behavior of the buttonDown update for toggle and radio button modes. When set to false, buttonDown changes on mouse down, when set to true, it changes on mouse up. |
|
clicked |
sevent |
Optional |
Read only |
Raised when a click is completed (mouseDown and mouseUp inside button area). |
|
color |
svec3 |
Optional |
0.6 0.6 0.6 |
The color used for normal/released state. |
|
colorDown |
svec3 |
Optional |
1 1 1 |
The color used for Clicked state, if no imageDown is set. |
|
colorDisabled |
svec3 |
Optional |
0.6 0.6 0.6 |
The color used for Disabled state, if no imageDisabled is set. |
|
colorOver |
svec3 |
Optional |
0.6 0.6 0.6 |
The color used for Over state, if no imageOver is set. |
|
doubleClicked |
sevent |
Optional |
Read only |
Raised when the interval between two clicks is less than doubleClickedDelay. |
|
doubleClickedDelay |
sfloat |
Optional |
0.5 |
Maximum interval, in seconds, between two clicks to recognize a double-click. |
|
enabled |
sbool |
Optional |
true |
Enabled button interaction. |
|
imageDisabled |
sstring |
Optional |
|
The image shown when disabled. |
|
imageDisabledColorFilter |
svec4 |
Optional |
127, 127, 127 |
A solid color that is blended to the imageDisabled, supports alpha channel. For more information about different blend strategies, see Image color filter modes. |
|
imageDisabledColorFilter Mode |
senum |
Optional |
none |
Defines the strategy used to blend the color selected in imageDisabledColorFilter to the displayed imageDisabled, The following options are available: none, screen, multiply, color, invert. See Image color filter modes section for details. |
|
imageDown |
sstring |
Optional |
|
The Clicked state image. |
|
imageDownColorFilter |
svec4 |
Optional |
147, 56, 51 |
A solid color that is blended on the displayed imageDown, supports alpha channel. For more information about different blend strategies, see Image color filter modes. |
|
imageDownColorFilterMode |
senum |
Optional |
none |
Defines the strategy used to blend the color selected in imageDownColorFilter on the displayed imageDown. The following options are available: none, screen, multiply, color, invert. See Image color filter modes section for details. |
|
imageNormal |
sstring |
Optional |
|
The Normal state image. |
|
imageNormalColorFilter |
svec4 |
Optional |
0, 175, 239 |
A solid color that is blended on the displayed imageNormal, supports alpha channel. For more information about different blend strategies, see Image color filter modes. |
|
imageNormalColorFilterMode |
senum |
Optional |
none |
Defines the strategy used to blend the color selected in imageNormalColorFilter on the displayed imageNormal, the following options are available: none, screen, multiply, color, invert. See Image color filter modes section for details. |
|
imageOver |
sstring |
Optional |
|
The Over state image. |
|
imageOverColorFilter |
svec4 |
Optional |
0, 175, 79 |
A solid color that is blended on the displayed imageOver, supports alpha channel. For more information about different blend strategies, see Image color filter modes. |
|
imageOverColorFilterMode |
senum |
Optional |
none |
Defines the strategy used to blend the color selected in imageOverColorFilteron the displayed imageOver. The following options are available: none, screen, multiply, color, invert. See Image color filter modes section for details. |
|
mode |
senum |
push |
Specify the button type as push, toggle, or radio. These values must be in lowercase. |
|
|
mouseDown |
sevent |
Optional |
Read only |
Raised when pressing mouse left button inside button area. |
|
mouseUp |
sevent |
Optional |
Read only |
Raised when releasing mouse left button inside button area or exiting button area with mouse left button pressed. |
|
radioGroup |
sstring |
Optional |
Used only if mode is set to radio. All the buttons set to radio mode that have the same radioGroup string value are grouped together. |