Command animation

On the ribbon Draw tab, in the Animations group, select Command to add the animation to a selected object or group of objects. The animation enables you to click on the object or press a pre-defined key to execute the command at runtime. Double-click on the object to view its object properties.

The Command animation provides one tag for each one of the events supported by it. More than one event can be configured simultaneously for the same Command animation:

• On Down: Executes the command/script once when the user clicks on the object with the left mouse button.

• On While: Keeps executing the command/script continuously while the mouse pointer is pressed on the object. The period (in milliseconds) of execution for the command/script is set in the Rate field from the Configuration dialog screen, except for the VBScript option, which is executed as fast as possible.

• On Up: Executes the command/script once when the user releases the left mouse button on the object.

• On Right Down: Executes the command/script once when the user clicks on the object with the right mouse button.

• On Right Up: Executes the command/script once when the user releases the right mouse button on the object.

• On Double Click: Executes the command/script once when the user double-clicks on the object with the left mouse button.

• On Touch, On Touch Start, On Touch Delta, On Touch Completed: These events are used for multi-touch gestures. For more information, see About Touch Events.

  Note: The events On Right Down, On Right Up and On Double Click are not supported in projects running on Windows Embedded target systems.

  Note: The events On Touch, On Touch Start, On Touch Delta, and On Touch Completed are visible in the Object Properties dialog for Embedded targets, but they are not supported in projects running on Linux target systems.

  Tip: An asterisk (*) on an event tab indicates that something is configured for that event. This makes it easier to see at a glance which events are configured.

Type menu: This setting defines the type of action that must be executed by the event of the Command animation. Each event has its own type. Therefore, the same Command animation can be configured with different types of action for different events. The following types are supported:

Config button: Launches the Configuration dialog, where the Command animation can be fully configured.

Back to button: Click to go back to the object properties of the underlying Button object.

Configuration dialog

This dialog allows you to fully configure the Command animation…

The event tabs (for example, On Down, On While, etc.) and the Type menu are the same as in the Object Properties dialog described above. The remaining settings are shared for all events:

• Options pane:

  • Enable Focus checkbox: When this option is checked, the object that the Command animation was applied to can receive the focus during runtime by the navigation keys.

  • Force checkbox: When this option is selected, any project tag that receives a value will trigger events as if the tag changed, even if the new value is equal to the old value. For example, if a tag has a value of 0 and the Command animation runs a procedure that writes 0 to that tag, all other tasks in the project runtime will recognize that the tag changed, even though it did not. This option is useful for making sure that events triggered by tag changes (for example, Write on Tag Change on a communication driver) are always triggered when the Command animation is used.

    Please keep in mind that if the tag's value does not actually change, the tag's timestamp (tagname->Timestamp) is not updated either.

    Force applies to both the procedure run by the Command animation itself and any global procedures called in that procedure, as long as they are run on the project runtime client where the Command animation is used (that is, on the device where the button is pushed).

    Force does not apply to global procedures that are run on the project runtime server using the function RunGlobalProcedureOnServer, even if the function is called in the procedure run by the Command animation. If you want to force tag changes in global procedures run on the server, use the function ForceTagChange.

  • Beep checkbox: When this option is checked, a short beep is played when the Command is executed. This option is useful to provide an audio feed-back to the user, indicating that the Command was executed. It does not indicate, however, if the action triggered by the Command animation was successful or not.

  • Release checkbox: When this option is checked, the On Up event is executed when you drag the cursor (or your finger) out of the object area (whether the button was released or not). This option is useful to make sure that the On Up event will always be executed after an On Down event, even if the user releases the mouse cursor out of the object area before releasing it.

  • Confirm checkbox: When this option is checked, user will have to answer a confirmation question before executing the command. This option is useful for decreasing the accidental triggering of critical events during runtime.

  • E-Sign checkbox: When this option is checked, the user will be prompted to enter the Electronic Signature before executing the command.

  • Key Only checkbox: When this option is checked, the user can only use the keyboard shortcut (configured in the Key pane described below) to execute commands.

• Disable: Disables action by the user when the result of the expression configured in this field is TRUE (value different from 0).

• Security: Security access level required to use the Command animation.

• Key group: Shortcut used to trigger the events On Down, While Down and On Up using a keyboard. (In other words, pressing this keyboard shortcut is the same as clicking the left mouse button.) This option is especially useful when creating projects for runtime devices that do not provide a mouse or touch-screen interface — the keyboard is the only physical interface available to interact with your project during runtime.

  • Shift, Ctrl, or Alt boxes: Click to create a key combination key, meaning the Shift, Ctrl and/or Alt key must be pressed with the key specified in the drop-down list.

  • Click the browse button (…) to open the Key Modifier dialog, which enables you to modify your combination keys. You can choose Left, Right or Left or Right to specify the position on the keyboard of the Shift, Ctrl or Alt key in the key combination. If you choose Left or Right, the command will be executed any time either of these keys is pressed in combination with the key specified in the drop-down list.

    Tip: If you have defined custom keys for your project, you can select them in this list. For more information, see Define custom keys for screen objects.