Actions

An action is triggered by an event, such as a click. When triggered, an action causes one of eight different effects. In the case of the Set State action, the effect can be reverted by a second trigger.

These are the eight types of actions:

• Set State—Changes the property values of one or more elements.
• Open Web—Open the specified URL.
• Download File—Downloads a file.
• Play Sound—Plays a sound asset.
• Open Page—Opens a .dg5 file.
• Close Page—Closes the current .dg5 file.
• Logout—Logs the user out of DGLux5.
• Data—Interacts with data metrics.

You can create a new action via the Actions panel. In the case of Set State or Data actions, you can also create an action via the dataflow without using the Actions panel.

To create an action via the Actions panel:

1. Select the component.
2. Open the Actions panel, behind the Property Inspector.

3. Click Add Action, and choose the action type from the list, as shown in the following image.

   

To create a Set State action via the dataflow:

1. Open any dataflow model.
2. Add a State block.

To create a Data action via the dataflow:

1. Open any dataflow model.
2. In the Data panel or Metrics panel, find the data action that you want to create. Available data actions can be found in right-click menus on data nodes or metrics.

3. Drag the action name from its right-click menu to the dataflow window, as shown in the following image.

   

When an action is created, its properties appear in the Actions panel and in the dataflow. You can edit the action in either of these places.

To define the event that invokes or reverts an action, you can use the Actions panel or you can use a binding.

These steps allow you to specify a mouse event that belongs to the currently selected component.

1. Click the drop-down menu next to Command in the Actions panel.

2. Choose a command, as shown in the following image.

   

   See Command Types.

In the case of a Set State action, you can also specify a revert trigger by choosing one of the following commands:

• onClickOn & Off: The first click invokes the action. The second click reverts the action.
• onMouseDown & Up: Clicking and holding the mouse button invokes the action. Releasing the mouse button reverts the action.
• onMouseEnter & Leave: Moving the cursor over the object invokes the action. Moving the cursor away from the object reverts the action.
• onDragOver & Leave: Dragging an object over the object invokes the action. Releasing the mouse button or moving the cursor away from the object reverts the action. In order to use onDragOver & Leave, you must enable the draggable Advanced property of the object to be dragged, and you must enable the droppable Advanced property of the object that owns the action.

These steps allow you to specify any event that belongs to any component. These steps use the Advanced Properties panel, but you can also find various event properties in the dataflow or the Property Inspector.

1. To use an Advanced property, select the component that owns the property, and then select the Advanced tab behind the Property Inspector.

2. Hover over the event, and double-click the blue dot, as shown in the following image.

   

   A binding pop-up appears representing the event.

   

3. Select the Actions tab.

4. Create a binding from the event in the pop-up to the Invoke or Revert trigger for the action.

   
   Binding an event from the Advanced properties

5. Close the pop-up.

Set State actions change the properties of one more more elements. To specify the paths and values of these properties, you record property changes.

To record a Set State action:

1. In the Actions panel, hover over the action, and then click Record, as shown in the following image.

   

   While you are recording, a red flashing rectangle surrounds the document window.

2. Use the Outline and Property Inspector to change all of the properties that you want to change when the action is triggered and revert when the action is invoked.

3. Click Finish Recording State, as shown in the following image.

   

These steps allow you to create a Set State action that changes a property to a bound value instead of an absolute value.

To create this effect:

1. Follow the steps in How to Edit a Set State Action by Recording, but in step 2, set the value to a dummy value.
2. Open the dataflow that contains the State block.
3. Click and drag the binding source.

4. Drop the binding source on the change n property.

   The binding replaces the dummy value.

After creating a Set State action, you can edit it via a special popup.

You can open this popup via the dataflow window or the Actions panel. To open the popup, click the i icon for the property, as shown in the following image.

This popup lets you edit the original and changed property values, as well as the following animation preferences:

• easing and easingBack: Specifies the rate of change over time for animation when invoking and reverting, respectively. The value of easing or easingBack can be one of the following:
  • Linear: The animation's rate of change is constant.
  • Ease In: The animation starts slowly and accelerates linearly as it executes.
  • Ease Out: The animation starts with a fast change rate and decelerates linearly as it executes.
  • Ease In Out: The animation starts slowly, accelerates linearly, and then decelerates linearly as it executes.
  • Cubic In: The animation starts slowly and accelerates cubically as it executes.
  • Cubic Out: The animation starts with a fast change rate and decelerates cubically as it executes.
  • Cubic In Out: The animation starts slowly, accelerates cubically, and then decelerates cubically as it executes.
  • Elastic In: The animation's rate of change starts on a small-amplitude sine wave. The sine wave grows as the animation executes.
  • Elastic Out: The animation's rate of change starts on a large-amplitude sine wave. The sine wave decays as the animation executes.
  • Elastic In Out: The animation's rate of change starts on a small-amplitude sine wave. The sine wave grows and then decays as the animation executes.
  • Bounce: The animation starts with a fast change rate, and decelerates to zero with an effect similar to a ball falling and bouncing on a floor.
• strength and strengthBack: Affects the differential or the change rate of the easing or easingBack function. A value of 0.5 is the default. Values below 0.5 decrease the differential or the change rate, making the easing appear less pronounced. Values above 0.5 increase the differential or the change rate, making the easing appear more pronounced.

Open Web actions open the specified URL.

When you edit an Open Web action:

• Use a full URL, including http:// or https://.

• (Optional) Use the Target property to specify where the file should open.

  See an online reference like this one for more information about targets.

Download File actions download the specified file.

When you edit a Download File action:

• The file can be a path relative to the root of this project, or it can be an absolute path to a file outside the project.
• For a file in this project, drag the file from the Project panel to the Input property.
• For Type, specify path to download the file at the path specified by the Input field. Specify data to download a file that contains the object or string in the Input field.
• (Optional) For File Name, specify the name and extension that the file should have when it is downloaded.

Play Sound actions play the specified sound asset.

When you edit a Play Sound action:

• The URL can be a path relative to the root of this project, or it can be an absolute path to a file outside the project.
• For a file in this project, drag the file from the Project panel to the Input property.

Open Page actions open the specified .dg5 file. They can be used to create Back and Forward buttons.

When you edit an Open Page action:

• For Destination, choose back if this is a Back button, forward if this is a Forward button, or dashboard if this button should open a specific .dg5.
• For Dashboard, enter the .dg5 file path.
• Set Self to TRUE if the page should open in this tab, FALSE if it should open in a new window or tab.

Close Page actions close the current .dg5 file.

A Close Page action's only editable properties are its invoke trigger and whether or not it is enabled.

Logout actions log the user out of DGLux5.

A Logout action's only editable properties are its invoke trigger and whether or not it is enabled.

Data actions execute available actions on the data source.

To edit a data action:

• To specify an action, right-click the data node or metric to display a list of actions, then click the action you want to use, and drag it to drag data action here in the Actions panel, as shown in the following image.

  

• The parameters for the action appear in the Actions panel and the dataflow, as shown in the following image. These parameters depend on the action that you chose.

  

To see how an action works at runtime, use Preview mode or the Viewer.

To revert a Set State action while testing, click its Revert trigger in the Actions panel.

To delete an action:

• Hover over the action, and click Remove.

These are the command types available in the Actions panel:

• onClick
• onMouseDown
• onMouseUp
• onMouseEnter
• onMouseLeave
• onMouseMove
• onDoubleClick
• onRightClick
• onClickOn
• onClickOff
• onMouseUpGlobal
• onMouseWheel
• onDragStart
• onDragEnd
• onDragOver
• onDragLeave
• onDragDrop
• onClickOn & Off
• onMouseDown & Up
• onMouseEnter & Leave
• onDragOver & Leave

For descriptions of these commands, see an event handlers reference like this one.

onClickOn and onClickOff are events that can work together to invoke and revert an action.

A command with an ampersand (&), such as onClickOn & Off, assigns events to both the Invoke and Revert triggers, if the action is a Set State action. A command with no ampersand assigns an event to the Invoke trigger only.

Dataflow blocks automatically appear in the dataflow when you create an action. You can use these blocks to edit your action.

See Dataflow Blocks Reference.

See clickThrough.

In this tutorial, you use Set State actions to create a button that changes appearance on hover and on mouse down. Then, you use a Data action to set a data value when the button is clicked.

To create this Submit button:

1. Add a text input component and a text component to the Stage, as shown in the following image.

   

2. Set the Fill property of the text component to a non-null value, as shown in the following image.

   

3. Give the text component a box shadow effect with an alpha value of 0%, as shown in the following image.

   

4. To change color on hover, create a Set State action on the text component:
   1. In the Outline, choose the text component.
   2. Choose the Actions panel, behind the Property Inspector.

   3. Click Add Action, and choose Set State, as shown in the following image.

      

   4. For Command, choose onMouseEnter & Leave.

   5. Click Record, as shown in the following image.

      

   6. Change the background fill of the text component, as shown in the following image.

      

   7. Click Finish Recording State, as shown in the following image.

      

   8. To test your hover action, use Preview mode and move the cursor over the Submit button.
5. To change the shadow alpha on mouse down, create a second Set State action on the text component:
   1. Click Add Action, and choose Set State.
   2. For Command, choose onMouseDown & Up.

   3. Click the Record button next to the second action, as shown in the following image.

      

   4. Change the alpha value of the box shadow to 100%, as shown in the following image.

      

   5. Click Finish Recording State.
   6. To test your mouse down action, use Preview mode and click the Submit button.
6. To commit data on click, create a Data action on the text component:
   1. Click Add Action, and choose Data Action.
   2. For Command, choose onMouseUp.

   3. Right-click a writeable data metric, and drag the @set, Set, or similar action to drag data action here, as shown in the following image.

      

      Available data actions vary based on your data source.

   4. In the Outline, choose the text input component.

   5. Hover over the Value property and double-click the blue dot to open a small binding pop-up for this property, as shown in the following image.

      

   6. Re-select the text component and the Actions panel.

   7. Bind the value of the text input component to the value property of the data action or a similar property, as shown in the following image.

      

   8. To test your data action, use Preview mode. Enter a value in the text input component and click the Submit button.

      The metric value in the Metrics panel changes.

      The following image demonstrates the results of clicking the Submit button:

      

More video tutorials are here.

This community forum post shows a use case for creating actions:

• Single Click Widget to Change Boolean