<< Click to Display Table of Contents >> Navigation: Object Reference > Events and Actions |
With events and the corresponding actions, dynamic behavior can be added to a project.
Almost all objects support a certain set of events. For these events certain actions can be configured.
This chapter lists a description of all available events and actions. What event and what action is supported by an object, can be found in the documentation for that object.
To assign an action to the event of an object, select the Events tab on top of the property table of the selected object.
Then press the ... button of the event that shall be configured.
Note: Events that are specific to CAN protocols are explained in the protocol's manual chapter.
For some events a repeat period can be configured (e.g. OnProjektRepeat or OnPageRepeat). This period is always a multiple of 100 milliseconds (which means that the fastest period is 100ms). It is not guaranteed that the actions can be triggered exactly in the specified period, a slight deviation is possible (based on CPU load and other circumstances at runtime). A value has to be entered in this field for the periodic execution to work. If a device is equipped with an internal sound card (speaker and/or line-out), an audio file can be played back when certain events happen. Audio OutputThe Audio Output dialog allows to assign an audio file that will be played back when the event occurs. The following elements of the dialog can be used for configuration: •Select Audio File: Use the Browse button to select an audio file from the file system (There are different default audio files pre-configured for an event or alarms that can be directly used) •No Audio button: Press this button if no audio shall be played for the event. •Size of Audio File: This shows the size of the selected audio file (very large files might add a delay before they are played and increase the size of the project package that needs to be transfered to the device) •Volume: Select the desired volume with the slider. Note that the final volume is dependent on the values of the beeper volume variables. •Repetition Count: How often the audio file shall be repeated can be configured here (1 means that the audio file is played once). Please note that the file is not saved if the repetition count is set to 0. •Playback Delay: If a repetition count greater than 1 is defined (see above), a playback gap can be configured. Enter a time in milliseconds that defines the gap (pause) between each repetition. The following audio codecs have been verified on the device: •MPEG AAC Audio (mp4a) (usually the file extension is .m4a or .aac, but .mp4 also works, if there is no video stream) •MPEG Audio layer 1/2/3 (mpga) (usually the file extension is .mp3) •Vorbis Audio (vorb) (usually the file extension is .oga or .ogg) •Raw wave files in different format (tested: PCM S16 LE (araw), PCM U8 (araw)) (usually the file extension is .wav) Windows Media Audio (.wma) is currently NOT supported. Media files that include a video stream do NOT work for these events. Please use a Multimedia Player for this. |
OnProjektInitThis event is only triggered once when the project is loaded before any other event. Allowed actions: •Execute Script OnProjektExitThis event is only triggered once when the PClient is exited on the device. This will normally not happen during normal operation, only when updating the project on the device. Allowed actions: •Execute Script OnProjektRepeatThis event is triggered repeatedly with a configurable period. This is the only repeat event that is triggered regardless of the active page (see OnPageRepeat). Allowed Actions: •Execute Script OnPowerOnThis event is triggered as soon as the device enters the On (normal operation) state but only if it was in low power or sleep mode before (switch ignition on). If the device just did a cold boot, this event is not triggered. Allowed actions: •Execute Script •Set Value OnLowPowerThis event is triggered as soon as the ignition is switched off and the device enters low power mode. Allowed actions: •Execute Script •Set Value OnSleepThis event is triggered as soon as the device awakes from sleep mode (not before going into sleep). Allowed actions: •Execute Script •Set Value OnPageInitThis event is triggered as soon as a new page is loaded. Allowed actions: •Execute Script OnPageExitThis event is triggered as soon as a page is left. Allowed actions: •Execute Script OnPageRepeatThis event is periodically triggered when the page is loaded. Allowed actions: •Execute Script OnPressThis event is triggered either if an object on screen is pressed via touchscreen or encoder or if a softkey is pressed. Allowed actions: •Execute Script •Jump To Page •Set Value (Not for Frame object) •Next Softkey Level (Softkey object only) •Previous Softkey Level (Softkey object only) •Navigate Up (Softkey and function key object only) •Navigate Down (Softkey and function key object only) •Navigate Confirm (Softkey and function key object only) •Open PDF Reader (Not for Frame object) •Set Media Player Command (only for devices that support the playback of audio / video) OnReleaseThis event is triggered either if an object on screen was pressed via touchscreen or if a softkey was pressed via physical keys and has now been released. Allowed actions: •Execute Script •Jump To Page •Set Value (Not for Frame object) •Next Softkey Level (Softkey object only) •Previous Softkey Level (Softkey object only) •Navigate Up (Softkey and function key object only) •Navigate Down (Softkey and function key object only) •Navigate Confirm (Softkey and function key object only) •Open For Input (Softkey and Button object only) •Open PDF Reader (Not for Frame object) •Set Media Player Command (only for devices that support the playback of audio / video)
Please note that this event behaves differently depending on the state of the Latching property of the according object. If latching is activated, this event will not be executed on a release after a press, but instead on the second press after a first press has activated the pressed state of the object. In this case, the release of the object will never execute an event.
Please also note that from this version on, devices with capacitive touch will behave differently when sliding away from a button: When sliding away from a button, in earlier versions of the program, the button would stay pressed. Then, when the finger is released, the OnRelease event would be executed. Now, as soon as the finger leaves the button, the button becomes de-pressed WITHOUT the release event being executed!
OnLongPressThis event is triggered either if an object on screen is pressed via touchscreen or if a softkey is pressed via physical keys for longer than the configured Long Press Time (see project properties). Allowed actions: •Execute Script •Jump To Page •Set Value (Not for Frame object) •Next Softkey Level (Softkey object only) •Previous Softkey Level (Softkey object only) •Navigate Up (Softkey and function key object only) •Navigate Down (Softkey and function key object only) •Navigate Confirm (Softkey and function key object only) •Open PDF Reader (Not for Frame object) •Set Media Player Command (only for devices that support the playback of audio / video)
OnLongReleaseThis event is triggered either if an object on screen is pressed via touchscreen or if a softkey is pressed via physical keys for longer than the configured Long Press Time (see project properties) and was released again. Allowed actions: •Execute Script •Jump To Page •Set Value (Not for Frame object) •Next Softkey Level (Softkey object only) •Previous Softkey Level (Softkey object only) •Navigate Up (Softkey and function key object only) •Navigate Down (Softkey and function key object only) •Navigate Confirm (Softkey and function key object only) •Open PDF Reader (Not for Frame object) •Set Media Player Command (only for devices that support the playback of audio / video)
Please note that this event behaves differently depending on the state of the Latching property of the according object. If latching is activated, this event will be executed at a release after a long press if the pressed state was not activated yet. If the pressed state was activated, the event will not be executed at a release after a long press.
OnDblClickThis event is triggered either if an object on screen is pressed via touchscreen or if a softkey is pressed via physical keys twice within the double click time (300ms). Allowed actions: •Execute Script •Jump To Page •Set Value (Not for Frame object) •Next Softkey Level (Softkey object only) •Previous Softkey Level (Softkey object only) •Navigate Up (Softkey and function key object only) •Navigate Down (Softkey and function key object only) •Navigate Confirm (Softkey and function key object only) •Open PDF Reader (Not for Frame object) •Set Media Player Command (only for devices that support the playback of audio / video)
Please note that this event behaves differently depending on the state of the Latching property of the according object. If latching is activated, this event will never be executed.
Here are the possible scenarios for press/release events when using a button or softkey with latching deactivated: •Short press, then release -> OnPress and OnRelease are executed •Long press, then release -> OnPress, then OnLongPress, then OnLongRelease AND OnRelease are executed •Double click -> OnPress, then OnRelease, then OnDblClick, then again Release are executed
Here are the scenarios for press/release events when using a button or softkey with latching activated: •Short press, then release -> OnPress is executed on the first press, OnRelease is executed the second press. No actions for the release of the button / softkey. •Long press, then release -> OnPress, then OnLongPress on the first press. OnLongRelease on the first release. OnRelease on the second press. No action for the second release. •Double click -> Double click behaves like a short press and release. No double click event will be executed with latching activated.
OnEnabledWithoutFocusThis event is triggered when the object has lost focus (it was either enabled with focus or open for input before). Allowed actions: •Execute Script •Jump To Page •Set Value •Set Media Player Command (only for devices that support the playback of audio / video) (only for buttons and softkeys) OnEnabledWithFocusThis event is triggered when the user navigates to this object so that it gets into the EnabledWithFocus navigation border state. It only has focus but is not open for input. Allowed actions: •Execute Script •Jump To Page •Set Value •Set Media Player Command (only for devices that support the playback of audio / video) (only for buttons and softkeys) OnOpenForInputThis event is triggered as soon as an object is made for open for input to edit it's value. Allowed actions: •Execute Script •Jump To Page •Set Value OnValueChangeThis event is triggered as soon as the value that the object displays is changed (either by user or by a referenced variable). Allowed actions: •Execute Script •Jump To Page •Set Value OnEnterNewValueThis event is triggered after the user has entered a new value for the object (not the same value). Note: This event is only fired for objects that have the property "Send Value Directly" disabled. If "Send Value Directly" is enabled, the event will not occur and the assigned action will not be executed. Allowed actions: •Execute Script •Jump To Page •Set Value OnEnterValueThis event is triggered after the user has finished editing the value of the object regardless if the value has changed or not. Allowed actions: •Execute Script •Jump To Page •Set Value OnEscapeThe OnEscape event is triggered if an object is open for input and the user pressed the Escape key to cancel the input. Allowed actions: •Execute Script •Jump To Page •Set Value OnGetValueThis event is currently not supported. OnValueChangeByOwnerThis is a variable event. It is triggered as soon as the owner of the variable writes a new value to the variable. This event can be set in the Variable Manager Allowed actions: •Set Value •Scale Value •Execute Script OnValueChangeRequestThis is a variable event. It is triggered as soon as anyone that is not the owner of the variable tries to set a new value. Allowed actions: •Set Value •Scale Value •Execute Script |
Various actions can be assigned to an event. See above for what action can be configured for which event.
No ActionThis is the default setting for any event. To select an action, open the drop-down menu and select one of the available actions. To disable the current action, choose No Action. Please note that when No Action is selected, all settings of the previously selected action are removed. Execute ScriptThe execute script action can trigger the execution of a JavaScript file. See the JavaScript documentation for more information. Properties: •Script File The JavaScript file that shall be executed •New Script File Not really a property, rather a short-cut which will open the new script dialog. •Import Script File Not really a property, rather a short-cut to import an existing script file from another location •Edit selected Script File Not really a property, rather a short-cut to open the JavaScript editor with the currently selected script file. •Execute on every Xth Event This property allows the execution of the JavaScript to not happen every time the event is triggered but only at e.g. every 5th event: This can act as kind of a low-pass filter for value change events. Jump To PageThe jump to page action triggers a change to another page in the project. Properties: •Jump To Select the page from the drop down list to which the project shall change Set ValueWith the set value action a fixed value can be set to a variable. Properties: •Variable Select the variable that's value shall be set •Value Either a number or a string depending on the variable type Scale ValueWith this action a value of a variable can be scaled. The following formula is used for that: scaledValue = (((Value + Offset1) * Multiplier) / Divisor) + Offset2 Properties: •Offset1 •Multiplier •Divisor •Offset2 Next Softkey LevelWith this action the next softkey level in a softkey frame can be shown. Properties: None Previous Softkey LevelWith this action the previous softkey level in a softkey frame can be shown. Properties: None Navigate UpThis action simulates one click of the encoder. It moves the focus frame one position up in the object hierarchy. Properties: None Navigate DownThis action simulates one click of the encoder. It moves the focus frame one position down in the object hierarchy. Properties: None Navigate ConfirmThis action simulates an encoder press. It opens an object for input or confirms the value when the object is already open for input. Properties: None Set Media Player Command
Properties: •Media Player ID The ID of the Media Player object that shall be controlled. •Command The command that shall be executed. The following commands are available: ▪play ▪stop ▪pause ▪previous ▪mute ▪unmute ▪set volume ▪set position ▪shuffle ▪loop •Value A value can be set for the set volume and set position command. Open For InputWith the open for input action it is possible to open one object on the current page for input so that the user can directly edit it without the need to navigate to it. Properties: •Object ID The ID of the object that shall be made open for input Open PDF ReaderIt is possible to show PDF documents in a separate application. With this action the external PDF reader can be opened. Consequently the PDF reader has to be closed before one can see the project again. Even alarms will be hidden behind the PDF reader on i.MX 6 based devices.
Properties: •PDF File To Open A PDF file can be selected that will be copied to <project directory>/terminal_files/additional_files. The PDF reader on the device will then show this file when opening. •Show file open button The PDF reader can show a "File Open Button" that enables the user to open other PDF files from the file system or external media. If this button shall be shown, this property has to enabled. This property only has an effect if the PDF reader is opened with a file. If it is opened without a PDF file, the "File Open Button" is always shown. Notes about viewing PDFs: Handling of PDFs may need a lot of CPU power and may consume a lot of memory (especially when loading a new page). To improve the user experience the following points should be taken into consideration: •All fonts used in the PDF should be embedded in the document so the PDF reader does not have to search for a matching system font. •If the PDF document contains embedded graphics, they should be saved in the same resolution (DPI) as the display of the target device. •The whole PDF document should already have the correct size to display at 100% on the target device so that the user does not need to zoom in or out. •If your system needs very fast response times on the CAN bus, it should be tested if these response times can be kept while displaying a PDF or switching pages in the PDF reader. Set Media Player CommandThe available actions for the Media Player are described here. Toggle Video DisplayThis action is currently not supported and has no effect at runtime. Temporarily Display VideoThis action is currently not supported and has no effect at runtime. |