Creating triggers for application actions

Every application action must have a trigger so that users are able to perform it.

There are 6 ways to create a trigger for an action:

1. automatically,
2. via LFD widgets,
3. by ui methods,
4. in an .fm2 form directly,
5. in a master or user action defaults file.

This means that even though end users of your application will see no difference, you will use different methods to manipulate different triggers.

Creating a trigger for an action automatically

If an action is not associated with any trigger, Lycia will create it automatically in the form of a toolbar button:

At runtime,

4gl developers can manipulate automatically created triggers by these functions:

• fgl_setactionlabel()
• fgl_setkeylabel()
• fgl_dialog_setactionlabel()
• fgl_dialog_setkeylabel()

For example,

Creating a trigger for an action as a widget

The usual way to create a trigger for an action is to add a corresponding widget to an .fm2 form.

Most often, actions are triggered by these widgets:

• Button
• ToolbarButton
• MenuCommand

You can also use these widgets to trigger an action:

BlobViewer Calendar Canvas CheckBox ComboBox

FunctionField Label ListBox RadioGroup Slider

Spinner TextArea TextField TimeEditField WebComponent

To use a widget as a trigger for the action, you must follow these steps:

1. Think about the actions you need to perform and invent their names (=identifiers).
2. Define the actions with these names in your 4gl code.

   ...

   ON ACTION act1

     DISPLAY "one"

   ...

3. Choose what widget you want to use to trigger this action.
4. Add this widget to your .fm2 form.

   

   You can read about adding widgets to the form on every widget's page, e.g., ToolbarButton or MenuCommand.

5. Specify an event for this widget in the Properties pane.

   Usually, these events are available – onInvoke, onTouched, onKey, and onMouse:

   

6. Choose the type of the event and specify its actionName.

   To associate the trigger with a definite property, you must use the same name as in the 4gl code:

   

Now the trigger is added to the form and action can be performed at runtime:

7. Modify the look and feel of the trigger, if necessary).

   You can change the look and feel of any trigger by setting its properties:

   image

   text

   place

   tooltip

   visible

   

4gl developers can manipulate these widget triggers by their properties (as shown above) or via the corresponding ui methods.

 

Creating a trigger for an action by ui methods

This way is close to the previous one but requires a certain level of 4gl expertise.

To be able to create triggers in this way, you must know how to create and manipulate the elements of the ui.<Widget> data type and how to use different ui methods.

You can read about ui methods and elements in the page of the corresponding widget. For example, ui.Button or ui.MenuCommand.

To create a trigger for the action by ui methods, you must follow these steps:

1. Think about the actions you need to perform and invent their names (=identifiers).
2. Define the actions with these names in your 4gl code.

   ...

   ON ACTION act1

     DISPLAY "one"

   ...

3. Choose what widget you want to use to trigger this action.
4. Define the variable of this ui.<Widget> data type.

   DEFINE tb_button ui.ToolbarButton

5. Define a variable of ui.BackgroundServerEventHandler data type to set an event for this widget.

   DEFINE buttonEvent ui.BackgroundServerEventHandler

6. Create this widget and add it to your form.

   Please remember that some widgets – like Button, MenuBar, or ToolbarButton – can be created by ui methods at runtime and other widgets – like Toolbar – cannot be created by ui emthods at runtime and must be added to the form in Lycia Form Designer.

   Here is an example of creating a toolbar button by ui methods at runtime:

   DEFINE tb_group ui.ToolbarGroup

   DEFINE tb_button ui.ToolbarButton

   ...

   LET tb_group = ui.ToolbarGroup.Create("tbg","toolbar")

   LET tb_button = ui.ToolbarButton.Create("bt1","tbg")

   CALL tb_button.SetText("form button")

7. Specify an event for this widget by these ui methods – ui.BackgroundServerEventHandler.Create(), setCallBackAction(), and setOnInvoke().

   LET buttonEvent = ui.BackgroundServerEventHandler.Create()

   CALL buttonEvent.SetCallBackAction("display")

   CALL tb_button.SetOnInvoke(buttonEvent)

   Do not forget to use the correct names of the actions.

4gl developers can manipulate these triggers by the corresponding ui methods (e.g., setText(), setImage(), setTooltip(), etc).

 

Creating a trigger for an action directly in an .fm2 form

Every form element of a .fm2 form file has a property, actions, that allows creating triggers for application actions:

This property has all the attributes of the trigger:

To create a trigger for the action in a .fm2 form directly, you must follow these steps:

1. Think about the actions you need to perform and invent their names (=identifiers).
2. Define the actions with these names in your 4gl code.

   ...

   ON ACTION act1

     DISPLAY "one"

   ...

3. In the .fm2, add an action in the actions property of the form element.

   

4. Specify its identifier – to associate the trigger with a definite property, you must use the same name as in the 4gl code.

5. Set optional attributes, if necessary.

   • accelerator
   • actionImage
   • comment
   • defaultView
   • order
   • place
   • showInContextMenu
   • statical
   • text
   • validate

More details about the property, actions, is here.

Creating a trigger for an action in system, master, and user action defaults files

SystemActionDefaults.fm2 is a global configuration file containing the predefined application actions, i.e. the application actions applied to all Lycia-based 4gl applications. However, if you need to customize action defaults, configure the Master action defaults file or User action defaults file: they override the System action defaults file. The System action defaults file can be overwritten at Lycia updates, so please refrain from editing it.

Master action defaults file is an action defaults file that contains default attributes for actions that can be performed in the 4gl application. Master action defaults files have the name of the program, are stored together with it, and are loaded automatically when the application is run.

User action defaults file is a user-defined configuration file with extension .ad2 or .fm2 that contains default attributes for actions that can be performed in several different 4gl applications in order to secure their common runtime behavior or change it according to current tasks and purposes. It has a higher priority than the Master action defaults file.

All these files have the same basic structure as any .fm2 form including the property, actions, that is used to create triggers for the application actions.

The algorithm of creating a trigger for an application action in an action defaults file is almost the same as in the .fm2 form directly. The difference is in the scope to which this action will be applied:

• If the action trigger is added to SystemActionDefaults.fm2, the corresponding action will be available for all the Lycia-based 4gl applications.
• If the action trigger is added to a user action defaults file, the corresponding action will be available for all the Lycia-based 4gl applications in which this user action defaults file is called.
• If the action trigger is added to a master action defaults file, the corresponding action will be available for the current 4gl application.
• If the action trigger is added to an .fm2 form directly, the corresponding action will be available only until this form is open.

To create a trigger for the action in an action defaults file, you must follow these steps:

1. Think about the actions you need to perform and invent their names (=identifiers).
2. Define the actions with these names in your 4gl code.

   ...

   ON ACTION act1

     DISPLAY "one"

   ...

3. Open with the administrator privileges (S, u, m) or create (u, m) the necessary action defaults file.
4. In the action defaults file, add the necessary action in the actions property of the form element.

   

5. Specify its identifier – to associate the trigger with a definite property, you must use the same name as in the 4gl code.

6. Set optional attributes, if necessary.

   • accelerator
   • actionImage
   • comment
   • defaultView
   • order
   • place
   • showInContextMenu
   • statical
   • text
   • validate
7. Save the action defaults file.
8. Rebuild the affected programs.