Back to Contents

Action Defaults

Summary:

• Basics
• Syntax
• Usage
  • Action Default attributes
  • Global Action Defaults
  • Form Action Defaults
  • Defining keyboard accelerators
  • Default accelerators for predefined actions
  • Controlling data validation when an action is invoked
  • Text attribute shows default action view
• Examples

See also: Dynamic User Interface, Predefined Actions, Action Defaults and MENU.

Basics

Action Defaults allow you to define default attributes for graphical objects (action views) associated with actions.

For example, you can specify the default text, comment, and image to use on graphical objects (buttons, toolbar items, and so on) bound to an action across all forms in the application.

You can centralize common action defaults in a global action defaults (.4ad) file. You can also define action defaults at the form level.

Syntax

Action defaults are defined in the .4ad file with the following syntax:

<ActionDefaultList>
  <ActionDefault name="action-name" [ attribute=value [...] ] />
  [...]
</ActionDefaultList>

Notes:

1. action-name identifies the action.
2. attribute is the name of an attribute.
3. value defines the value to be assigned to attribute.

Usage

Action defaults are provided to centralize the decoration attributes and accelerator keys for action views (graphical objects associated with actions). It is strongly recommended that you centralize these decoration attributes to avoid specifying them in all the source files that define the same action view.

Each attribute of an action view element bound to an action handler in the program will automatically be set to the value defined in the Action Defaults, if there is no value explicitly specified in the element definition for that attribute.

Note that in some situations, the action view can be bound to an action by specifying a sub-dialog and/or field name prefix. For those views, the action defaults defined with the corresponding action name will be used to set the attributes with the default values. In other words, the prefix will be ignored. For example, if an action view is defined with the name "custlist.append", it will get the action defaults defined for the "append" action.

Action Defaults can be defined globally for the whole program or at the form level. Global Action Defaults are loaded from a default 4ad file or by using the ui.Interface.loadActionDefaults() method. Form Action Defaults can be specified in the form file or can be loaded with the ui.Form.loadActionDefaults() method.

For example, in most cases a print action needs a text decoration "Print", with a printer icon image and a CONTROL-P accelerator key. Those attributes can be centralized in the Action Defaults. Some action views of the print action may need specific attributes; for example, if the current form handles customer addresses, the comment attribute of a print button might be "Print current customer information". In this case you can define Action Defaults at the form level, which have a higher priority than the global Action Defaults. Additionally, if some action views must have a different image in the same form, you can specify the image attribute in the definition of each element to overwrite the defaults. For example, the toolbar button bound to the print action might have a small image, while the print button in the form might have a large one.

The final attribute values used for graphical elements are set based on the following priority:

1. Attribute defined in the action view element definition itself.
2. Attribute defined for the element action in the form Action Defaults.
3. Attribute defined for the element action in the global Action Defaults.

The following code defines a BUTTON in the form specification file:

01 ATTRIBUTES
02  BUTTON b1: print, TEXT="Do Print";
03 END

if the form Action Defaults define:

and the global Action Defaults define:

the button object will get the following final attribute values:

• text = "Do Print"
• image = "smiley"
• comment = "Print orders"

and the accelerator will be CONTROL-P.

Action Default attributes

The following attributes can be defined with Action Defaults:

Global Action Defaults

Global Action Defaults are defined in an XML file with the "4ad" extension. By default, the runtime system searches for a file named "default.4ad" in the current directory. If this file does not exist, it searches in the directories defined in the DBPATH/FGLRESOURCEPATH environment variable. If no file was found using the environment variable(s), standard action default settings are loaded from the "FGLDIR/lib/default.4ad" file.

Warning: Global Action Defaults must be defined in a unique file; you cannot combine several "4ad" files.

You can override the default search by loading a specific Action Defaults file with the ui.Interface.loadActionDefaults() method. This method accepts a filename with or without the "4ad" extension. If you omit the file extension (recommended), the runtime system adds the extension automatically. If the file does not exist in the current directory, the directories defined in the DBPATH/FGLRESOURCEPATH environment variable are searched.

Form Action Defaults

Action Defaults can be defined at the form level. When action defaults are defined in the form file, action views get the attributes defined locally.

You can define form action defaults with the ACTION DEFAULTS section in the form specification file.  If you want to use common action defaults in several forms, you can use the preprocessor include directive to integrate an external file.

You can also load Form Action Defaults dynamically with the ui.Form.loadActionDefaults() method. This method accepts a filename with or without the "4ad" extension. If you omit the file extension (recommended), the runtime system adds the extension automatically. If the file does not exist in the current directory, the directories defined in the DBPATH/FGLRESOURCEPATH environment variable are searched.

Defining keyboard accelerators

When using the ON ACTION clause in a dialog instruction, action defaults accelerators are applied in both GUI and TUI mode. For backward compatibility, this is not done in TUI mode when using the ON KEY clause.

The traditional ON KEY clause in a dialog like INPUT implicitly defines the acceleratorName attribute for the action, and the corresponding action default accelerator will be ignored. For example, when you define an ON KEY(F10) block, the first accelerator will be "F10", even if an action default defines an accelerator "F5" for the action "F10". However, you can set other accelerators with the acceleratorName2,  acceleratorName3 and acceleratorName4 attributes in action defaults.

In menus, the behavior is a bit different, see the COMMAND and COMMAND KEY clause in MENU.

Default accelerators for predefined actions

If no accelerator is specified in action defaults for a Predefined Action, the runtime system sets one or more default accelerators according to the user interface mode. For example, the accept action will get the Return and Enter keys in GUI mode, but in TUI mode, the Escape key would be used.

If you want to force an action to have no accelerator, you can use "none" as accelerator name.

Controlling data validation when an action is invoked

The validate attribute defines the behavior of the dialog for data validation when an action is invoked. For more details, see Interaction Model.

Text attribute shows default action view

When creating actions with ON KEY (or COMMAND KEY without a command name in a MENU), the default action view (i.e. button in action frame) is invisible. However, if you define a text attribute for a function key or a control-x key, the default button is made visible. Remember you can control the visibility of the default action view with the defaultView Action Default attribute.

See also Setting Key Labels, a feature supported for backward compatibility. 

Examples

Example 1: Loading a Action Defaults file:

Some Action Defaults in XML format (exit action has Localized Strings):

01 <ActionDefaultList>
02    <ActionDefault name="print" text="Print" image="printer" comment="Print report" />
03    <ActionDefault name="modify" text="Update" comment="Update the record" />
04    <ActionDefault name="exit" text="Quit" image="byebye" comment="Exit the program" validate="no" >
05        <LStr text="common.exit.text" comment="common.exit.comment" />
06    </ActionDefault>
07 </ActionDefaultList>

The program loading the action defaults file:

01 MAIN
02   CALL ui.Interface.loadActionDefaults("mydefaults")
03 END MAIN

Example 2: Actions defaults in a form file:

01 ACTION DEFAULTS
02   ACTION accept ( COMMENT="Commit order record changes" )
03   ACTION cancel ( TEXT="Stop", IMAGE="stop", ACCELERATOR=SHIFT-F2, VALIDATE=NO )
04   ACTION print ( COMMENT="Print order information", ACCELERATOR=CONTROL-P, ACCELERATOR2=F5 )
05   ACTION zoom1 ( COMMENT="Open items list", CONTEXTMENU=NO )
06   ACTION zoom2 ( COMMENT="Open customers list" )
07 END