Using the Button nodes

Use the Button nodes to create interactions through clicking, tapping, or pressing a key on the keyboard. Use Button 3D to create a 3D button and Button 2D to create a 2D button.

Kanzi allows you to create buttons using:

The difference between the two approaches is that when you use the state manager you always know in which state the button is. For example, when a user clicks a button created with triggers and actions, the action sends the message, but your application is not aware of the state of the button. When you use the state manager, you can always check which state the button is in and even revert the state when needed. See Creating state managers.

When you use triggers and actions to create a button, and the user clicks the visual representation of a button, the action generates a message that travels to the button node where you can define the behavior for that message.

When you create a Button node, Kanzi by default adds a Button: Click trigger to that node. When a Button node has focus, it receives input from the keyboard keys Space, Enter, and Enter on the numeric pad. Use scripting functions to get and set the node that currently has focus in the project. See Scripting reference and Using triggers.

You can add other triggers to a Button node as well. For example, you can add messages that are triggered when a user presses down a mouse button or cancels a click. See Using triggers.

When you create a button it does not have a visual shape. To make a button visible, add to the button a node with content. You can make a Button 2D node visible also by filling its background with a brush. See Adjusting the appearance of 2D nodes.

To learn how to create a button complete the button tutorial. See Tutorial: Creating a button.

Creating a button

To create a button:

  1. In the Project press Alt and right-click the node where you want to create a button and select either Button 3D, or Button 2D.
    Note that you can create a 3D node only inside 3D nodes, and 2D node only inside 2D nodes.
  2. In the Project add a visual shape to the button.
    For example, if you created a 3D button, add a Box, if you created a 2D button add an Image.
  3. In the Project select the button, in the Node Components > Triggers section in the Button: Click trigger click the Add dropdown menu, and select an action.
    For example, select the Write Log action and set its Log Message property to <Name>.
    In the Preview when you click the visual representation of the button the Write Log action writes the name of that node to the Log window.
  4. (Optional) Use the Button triggers that come with Kanzi to define the behavior of Button nodes. See Using triggers and Button triggers.

Controlling the behavior of a Button node

In Kanzi, to control the behavior of a Button node you can:

Using a state manager to set button states

Use a state manager to define how a Button node reacts to user input. For example, you can set how a button looks when the user presses or releases that button. You can learn this by completing a tutorial. See Tutorial: Creating a button.

To learn how to use a state manager in your Kanzi application, see Tutorial: Use state managers to control your application

To use a state manager to set button states:

  1. In the Project select the Button node for which you want to create states and in the State Tools create a state manager for that node.
  2. Create two states, one that defines the button when it is pressed, and another that defines the button when it is released.
  3. For each state, set the value of the property which sets the visual shape of the Button node.
    For example, to set how a Button 2D node looks when it is pressed, in the Image node set the Image property to the image which you want to use when the button is pressed.
  4. In the State Tools for the state manager which controls the Button states set the Controller Property to Is Down.
    In a state manager the value of the property you select as the Controller Property defines the conditions when each state in a state group is active.
    Here you use the Is Down property to transition to a state based on the value of that property. The Is Down property controls whether a Button node is in a pressed or non-pressed state.
  5. In the State Tools set the value of the Controller Property in the Pressed state to True. By doing so your Kanzi application uses the Pressed state when the button is pressed and the Released state when the button is not pressed.
  6. In the State Tools click Edit State Manager to deactivate the State Tools.

Using Button triggers

Use the Button triggers that come with Kanzi to define the behavior of Button nodes. To learn more about using triggers, see Using triggers.

Enabling the double-click gesture for a Button node

Use the double-click gesture to enable users to double-click or double-tap buttons in your Kanzi application. Use the Double Click trigger to react to the double-click gesture. For example, you can change the appearance of a Button node when the user double-clicks or double-taps that node.

By default if two clicks occur within 250 milliseconds, Kanzi recognizes them as a double-click gesture. To use a different time, create and configure a multi-click manipulator using the Kanzi Engine API. See Using the multi-click manipulator.

To enable the double-click gesture for a Button node:

  1. In the Project select the Button node for which you want to enable the double-click gesture and in the Properties set the Double-Click Enabled property to enabled.
  2. In the Node Components > Triggers section add the Double Click trigger.
  3. In the Node Components > Triggers section click the Add dropdown menu for the Double Click trigger, select an action, and configure the action. See Using triggers and Actions reference.

Setting the appearance of a Button 2D node

To set the appearance of 2D nodes:

Using the Button 3D node in the API

For details, see the Button3D class in the API reference.

Using the Button 2D node in the API

For details, see the Button2D class in the API reference.

See also

Tutorial: Creating a button

Using the Toggle Button nodes

Using the Toggle Button Group nodes

Buttons

Tutorial: Use state managers to control your application

Creating state managers

Using triggers

Using the multi-click manipulator