Developer

Button

The Agentry Client user interface definition provides multiple button types.

A screen button defines a button control that appears on a Client screen. The button may be a standard button control, a tool bar button, a menu or menu item, or as a separator. A button is defined to execute an action when clicked or tapped, unless defined as a menu or separator. When executing an action, the button also defines the target object instance provided to the action for processing.

The button definition itself allows for different Button Types. These include a traditional button, called an Action Button; an item to be added to the Action menu displayed on the Agentry Client’s menu bar, called an Application Menu; a Toolbar Button, which is displayed on the Agentry Client’s tool bar; and a Separator button, which places extra space between other button definitions, or a separator line in a menu.

In addition, an Action Button can be defined to be a Popup Menu button. In this case, the button displayed on the screen will not execute an action, but instead display a menu when clicked. The contents of the menu are other button definitions for the same screen that will execute actions when selected. These other buttons must meet the criteria of, first, being positioned after the menu button, and second, the Popup Menu attribute must be set to true.

All button types except for the separator are defined to execute an action when clicked. The action definition to execute must exist before creating the button definition. Buttons also include a target attribute where the object instance targeted by the action being executed is specified. The selected target object type must be the same as the object type selected for the action being executed, with the exception of those actions defined with a For Object attribute setting of None.

Button Attributes

Following are the attributes for a button definition. Some of these attributes are not applicable to a button definition based on the selection made in the Button Type attribute. The attribute descriptions in this list specify this information:
  • Button Type: This attribute specifies the type of button to define for the screen. The options are:
    • Action Button: Displays a button control on the screen at the position specified by the platform using the screen at run time.
    • Application Menu: Adds a menu item to the Agentry Client’s Action menu. This menu item will only be a part of the Action menu when the parent screen to the button has the focus.
    • Separator: Places extra space between Action Buttons, or a separator in a popup menu, depending on where the separator button is displayed Separators cannot be added to the Agentry Client’s Action menu.
    • Toolbar Button: Places a button on the Agentry Client’s toolbar. This button type must have an image as it will not have a label.
  • Name: The unique name for the button definition. This value must be unique among all buttons within the same screen.
  • Image: This attribute references an image definition within the application to be used as the icon for the button control displayed on the screen. For action button types the icon is displayed to either the left or right of the button’s label depending on the device’s OS shell. The image icon for toolbar buttons is required. This will be the image used to identify the toolbar button. For both Separator and Application Menu Button Types, or if the Action is set to Popup Menu, the image attribute field is disabled.
  • Label: This attribute specifies the label to identify the button on the screen. This value is the label for Action Button Types, or the text listed as a menu item for both Action Menu Button Types or Action Buttons included on a popup menu. This attribute is disabled for both Toolbar and Separator Button Types.
  • Action: This is the action to execute on the Agentry Client when the button is clicked or tapped by the user. This action must be defined before creating the button definition. At run time if this action is disabled, the button will also be disabled. This attribute may also be set to Popup Menu. In this case the button will not execute an action, but rather will display a popup menu when clicked or tapped. The items in this menu will be other button definitions within the same screen defined to be drawn on the popup menu. Popup menu buttons do not have an image or a target object instance. Also, the Popup Menu attribute is not available, as a popup menu button cannot be placed within another popup menu.
  • Target: This attributes specifies the target object instance of the button to be passed to the action the button executes. The object type selected here must match the definition type defined in the For Object attribute in the action the button is defined to execute. At run time if the selected Target object instance is not currently in scope, the button will be disabled. As an example, if the target is the selected object in a list screen, and no object is currently selected, there is not valid target in scope and the button will be disabled. Separator Button Types and buttons with an Action attribute setting of Popup Menu do not have a target as they do not execute an action.
  • Popup Menu: This attribute specifies whether the button should be displayed in a popup menu on the Agentry Client. If this attribute is set to true, and of a button definition positioned before the current definition is defined with Action attribute of Popup Menu, the current button definition will be added as a menu item rather than a button control. This attribute may only be set for Action Button Types.
  • Style: This attribute specifies a style to apply to the button definition. The Style attribute is only available for Action Button Types.
  • Focused Style: This attribute specifies a style to apply to the button when the button has the focus. This attribute is not available for Separator Button Types.
  • Shortcut Key: This attribute specifies whether a shortcut key is associated with the button and the specific key or key combination. This attribute includes the ability to set combinations of the Ctrl, Alt, and Shift keys, as well as any alphanumeric keys, function keys from F1 through F24, or hardware buttons (Button 1 through Button 5) on mobile devices. When setting this attribute, verify the key combination selected is not configured for any other shortcut, either within the current screen of the mobile application or for any system shortcuts configured on the client device.