ButtonShape2D

The ButtonShape2D node provides full pushbutton and toggle functionality. A ButtonShape2D can assume four different states: Normal, Over, Down, and Disabled. A different image and/or shape can be assigned to each state.

ButtonShape2D facilitates the design of 2D adaptive interfaces by providing configuration parameters that allow to easy management of how the graphic scales and aligns when the ButtonShape2D size or aspect ratio does not match the graphic size or aspect ratio.

Platform support

This element is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-P WASM platforms.

Button modes

ButtonShape2D supports three button behaviors.

Button states

The ButtonShape2D has four different states: Normal, Over, Down, and Disabled. Different images and shape colors can be defined for each state.

Adaptive size support

ButtonShape2D provides functionalities to manage how the displayed image behaves when the node rect has a different size and aspect ratio from the displayed image. The behavior is configured independently through these parameters.

Wrap mode

The imageWrapMode and shapeWrapMode fields define how the graphics is wrapped in the node rect,

stretch—The simplest behavior is achieved with the stretch style. This behaves exactly as a Button2D node and stretches the graphic so that is covers the entire rect area.

fit—The fit behavior makes the graphic keep its original aspect ratio and keeps the whole graphic inside the node rect by possibly displaying a padding on the top, bottom, left, or right corners depending on the container aspect ratio and selected imageWrapAlignment.

fill—The fill behavior makes the graphic keep its original aspect ratio and fills all the available space in the node rect by possibly cropping the graphic on the top, bottom, left, or right corners depending on the container aspect ratio and selected imageWrapAlignment. The logic is to fill either the width or height of the node rect (whichever needs the major expansion of the graphic to be covered) and crop the graphic on the other measure.

fill_width—The fill_width behavior makes the graphic keep its original aspect ratio and fills all the available width in the node rect by possibly cropping the graphic or displaying a padding on the top or bottom, depending on the container aspect ratio and selected imageWrapAlignment. The logic is to fill the width of the node rect and crop or pad the graphic on the height.

fill_height—The fill_height behavior makes the graphic keep its original aspect ratio and fills all the available height in the node rect by possibly cropping the graphic or displaying a padding on the top or bottom, depending on the container aspect ratio and selected imageWrapAlignment. The logic is to fill the height of the node rect and crop or pad the graphic on the width.

original_size—The original_size behavior makes the graphic keep its original aspect ratio regardless of the size and aspect ratio of the container, padding, and cropping of the image may occur in both width and height when the node rect size is different from the graphic size depending on the selected imageWrapAlignment.

Wrap alignment

The imageWrapAlignment and shapeWrapAlignment fields define how to align the graphic inside the node rect when a wrap mode (different from stretch) is applied.

The most effective way to test the effect of this parameter is to render an image in a bigger container and specify original_size as imageWrapMode. A small image will display inside a bigger node rect and the effect of selecting an alignment is clearly different between different options.

By selecting an imageWrapMode such as fill_width, the imageWrapAlignment options left, center, and right will have the same result. This is due to the image already filling all the horizontal space.

center—The center behavior aligns the graphic at the center of the rect node.

top—The top behavior aligns the graphic at the center of the rect node and keeps it horizontally centered.

bottom—The bottom behavior aligns the graphic at the bottom of the rect node and keeps it horizontally centered.

left—The left behavior aligns the graphic at the left of the rect node and keeps it vertically centered.

right—The right behavior aligns the graphic at the right of the rect node and keeps it vertically centered.

top_left—The top_left behavior aligns the graphic at the top-left corner of the rect node.

top_right—The top_right behavior aligns the graphic at the top-right corner of the rect node.

bottom_left—The bottom_left behavior aligns the graphic at the bottom-left corner of the rect node.

bottom_right—The bottom_right behavior aligns the graphic at the bottom-right corner of the rect node.

Image functionalities

ButtonShape2D can display a different image for each of its states: Normal, Over, Down, Disabled.

PNG and TGA image formats are supported. GIF is also supported, but animation of GIF is not. The first frame will be displayed for animated gif.

Image default state

If one or more of the Over, Down, or Disabled states do not have a defined image field, the image defined in the imageNormal field will be used as default image for the state without an image. Therefore, it is possible to provide only one image if there is no need to change image on state change.

Shape functionalities

ButtonShape2D can draw a shape that can have a border. The shape can be picked from three predefined shapes: rectangle, rounded_rectangle, and circle, or can be custom defined.

For each of its states: Normal, Over, Down, and Disabled, it is possible to specify different colors to differentiate the state.

Color parameters

The color parameters can be different for each state.

Configuration parameters

Other configuration parameters related to the shape are shared by the four states. The shape and border can change their color in different states, but the shape itself always stays the same.

isOverGraphics

ButtonShape2D provides the isOverGraphics field that gives control of the over state of the pointer with a pixel-perfect check. This field is true if the pixel of the ButtonShape2D graphic underlying the pointer position is colored with an alpha > 0, false otherwise.

pixelPerfectOver

The pixelPerfectOver flag drives the pushbutton functionality with pixel perfect interaction. If set to true, overing and clicking the button will be triggered only if the pixel of the ButtonShape2D graphic underlying the pointer position is colored with an alpha > 0 (uses isOverGraphics as check). Otherwise, interactions will be triggered relying on the whole node rect. This parameter is set to true by default.

renderToTexture2D

ButtonShape2D supports the rendering to a Texture2D. Pushbutton functionality is supported as well.

Code example

This is a code example for the ButtonShape2D node. It creates a node with different images for each state, overlayed to a rounded_rectangle shape which color changes for each different state.

<ButtonShape2D name="ButtonShape2D"

templateInfo="ButtonShape2D|ButtonShape2D"

position="100 100"

size="200 150"

imageNormal="image_normal.png"

imageDown="image_down.png"

imageOver="image_over.png"

imageDisabled="image_disabled.png"

shapeStyle="rounded_rectangle"

shapeNormalColor="0 0.68 0.93 1"

shapeNormalBorderColor="0.44 0.44 0.44 1"

shapeOverColor="0 0.62 0.84 1"

shapeOverBorderColor="0.25 0.25 0.25 1"

shapeDownColor="0.52 0.86 1 1"

shapeDownBorderColor="0.55 0.55 0.55 1"

shapeDisabledColor="0.25 0.25 0.24 1"

shapeDisabledBorderColor="0.067 0.067 0.067 1" />

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.

  

ButtonShape2D fields

These are the fields for ButtonShape2D node. Only the node-specific fields are indicated, fields obtained by inheritance are not.

Field inheritance: NodeBase > RectBase2D > ButtonShape2D