List Screen

A list screen definition displays an object collection property on the Agentry Client. Object instances from the collection are displayed as rows in the list. A list screen contains the child definitions column and button. A column is defined to display the property value for each object instance in the collection. Buttons are defined to execute actions related to the object instances. List screens include definable behaviors related to filtering, scanning, and sorting, as well as other screen enhancements for displaying data stored in the object instances of the target collection property.

The list screen may or may not display a header label above the list control. A header label can contain static or dynamic text about the items displayed in the list. A list screen may also display a detail pane containing static or dynamic text. The detail panes intended usage is to display the property values of the currently selected object in the list control, reducing the need for horizontal scrolling on the Agentry Client.

List screens can be defined to include double-click actions, executed when the user double-clicks an item in the list control, scanning actions and scan filtering, and include rules to determine what items are displayed in the list. A list screen can also be enabled or disabled via a rule definition. Disabled screens are not displayed in the screen set on the Agentry Client.

List Screen Child Definitions

  • Column Definition: A list screen column defines what object property is displayed for each record in a list control and how it is formatted on the screen.
  • Button Definition: A button definition defines a button control to be displayed for the screen that will execute an action or display a menu when selected.

List Screen General Attributes

The General Screen attributes set the basic behavior of the List Screen, including how Styles can be applied to the List Screen.

General Attributes
  • Name: The internal name of the list screen. This value must be unique among all screen definitions, regardless of type, within the same parent screen set.
  • Caption: Labels the tab on the Agentry Client for the list screen. This value may or may not be displayed when there is only one screen displayed within the parent screen set, depending on the client device type.
  • Screen Icon: This is a reference to an image definition within the application. This image is used as the icon displayed for this screen in tabs.
  • Collection: References the object collection property the list screen is to display. This collection is normally a property of the object definition the parent screen set is defined to display.
  • Enable Rule: References a rule definition expected to return a Boolean value and that is evaluated in the context of the object definition for the parent screen set. When false is returned, the screen will be disabled and no tab for it will be displayed within the screen set window. If all screens within a screen set are disabled, that screen set will not be displayed and any actions defined to display it will also be disabled. If the main screen set for a module is disabled, that module cannot be displayed on the Agentry Client.
  • Include Rule: References a Rule definition expected to return a Boolean value and that is evaluated once for and in the context of each object in the collection displayed by the list screen. When an include rule is specified, only those objects for which the rule evaluates to true will be listed in the screen’s list control.
  • Icons Image: References an image definition to be displayed on the tab for the list screen, to the left of the screen’s caption text, within the screen set window on the Agentry Client. The name of this image may be selected from a list, or it may be returned from a rule. When a rule is referenced, it is expected to return a string value and is evaluated in the context of the object displayed by the parent screen set.
List Screen Styles
  • Screen: The style to apply to the list screen as a whole. This will affect all portions of the screen not displaying a list, header label, detail pane, or button.
  • Header Label: The style to apply to the list screen’s header label. If no header label is defined this attribute has no affect on the screen.
  • Column Labels: The style to apply to the column labels on the screen’s list control.
  • Rows: The style to apply to all rows on the list screen. The Hyperlinks optional style will override the Rows style for cells with hyperlinks.
  • Alternate Rows: The style to apply to every other row in the list, beginning with the second row. The Hyperlinks optional style will override the Alternate Rows style for every other row, specifically cells containing hyperlinks within the row.
  • Highlight Rows: The style to apply to a row for the purposes of drawing attention to that row. This style should always be returned via a rule definition that evaluates the object being listed. The optional Hyperlinks style will be applied to the highlighted row’s cells containing a hyperlink.
  • Selected Rows: The style to apply to the row currently selected by the user in the list control. The optional Hyperlink style will be applied to any cells within the selected row containing a hyperlink.
  • Selected No Focus Rows: The style to apply to the selected rows in a list view control or list screen where the list control does not have the input focus. The optional Hyperlinks style will be applied to any cells within the selected row containing a hyperlink.
  • Detail Pane: The style to apply to both the foreground (text) and background of the list screen’s detail pane. If no detail pane is defined this attribute has no affect on the screen.
  • Buttons: The style to apply to all button definitions on the screen.
  • Focused Buttons: The style to apply to the button that currently has the focus.

Actions/Sorting Attributes

The Action/View/Selection attributes control how the user interacts with the List Screen, including double-clicking on or off an item in the list and behaviors related to sorting and reordering the columns.

  • Double-Click On Item - Action: Specifies the action to execute when the user double-clicks a list control record.
  • Double-Click On Item - Target: Specifies the target of the Double-Click On Item Action. A target must always be specified for the action and is typically the selected object in the list.
  • Double-Click Off Item - Action: Specifies an action to be executed when the user double-clicks the list without clicking on an item. This is most commonly used to execute an action that instantiates an add transaction for the object type being listed.
  • Double-Click Off Item - Target: Specifies the target of the Double-Click off Item Action. A target must always be specified for the action. Typically the target is the parent object of the object collection property displayed by the list screen.
  • Fixed Sort Property: Specifies the property definition within the object type being listed used to sort the records in the list. The user will not be allowed to re-sort the list when this attribute is set. The Order option to this attribute is set to specify the sort order, either ascending or descending.
  • Allow Sort: Specifies if the user can resort the list by clicking on a column header. This is enabled by default, and is disabled if a Fixed Sort Property is set.
  • Initial Sort Column: Specifies a column definition by which the list will be sorted upon initial display of the screen. This attribute requires that a column definition exists before it can be set. The Order option to this attribute is set to specify the sort order, either ascending or descending. If the list screen allows the list to be sorted (Allow Sort is true) the list will be displayed sorted to the order of the last sort action. If a Fixed Sort Property is set, this attribute is disabled.
  • Allow Reorder: Specifies whether or not the user can reorder the columns displayed in the list by dragging and dropping the column headers in the list. This is enabled by default.
  • Allow Filter: Specifies whether or not the user can filter the items in the list. A filter icon is displayed at the bottom of the screen when enabled. The user can click this icon to select sorting options. This sets the filter behavior for the entire list screen. This is enabled by default. Individual column definitions may be defined to prohibit filtering on those columns.
  • Allow Multi-Row Select: Specifies if the user can select more than one record in the list at the same time. If multiple items are selected in a list, actions that target the selected object in the list will be executed once for each selected object. The default for selecting multiple objects requires a Ctrl+Click combination or a click and drag operation by the user, depending on the device type. The Enable Single Click option may be set to allow multiple records to be selected with a single click by the user. Deselecting a record requires the user to click it again. This feature is normally most useful on touch screen devices using a stylus, as it allows non-sequential records in the list to be selected.

Header/Detail Pane Attributes

Using these attributes, you can display Header text and a Detail Pane in addition to the main list control of the List Screen.

Header and Detail pane attributes are set to display additional information about the list as a whole or about the currently selected item in the list. The Header Label is a static line of text displayed above the list. This text may be static, set via certain available format strings, or set via a rule. A rule referenced for this purpose is expected to return a string value and is evaluated in the context of the object displayed by the parent screen set.

The Detail Pane is redrawn each time a new object is selected in the list and almost always contains either format strings or is set via a rule’s return value. Rules are evaluated in the context of the selected object in the list and are expected to return a string value.
  • Header Label: Specifies the Header text for the list screen. A common use for this header label is the total number of objects displayed in the list vs. the total number of objects in the collection, which may be different when a filter is enabled. The format strings used for this purpose are %DisplayedCount and %TotalCount.
  • Detail Pane: Displays a text box on the list screen. The detail pane is updated each time the user changes their selection in the list screen.
  • Position: Controls where the detail pane is displayed on the screen in relation to the list control. You can position the detail pane below it or to its right.
  • Size: Sets the pixel size of the detail pane on the screen. The default is 50. If the Position is “Bottom” the detail pane will span the width of the screen and the Size will set its height. If the Position is “Right” the detail pane will span the height of the screen and the Size will set its width.
  • Word Wrap: When enabled, lines of text longer than the width of the detail pane will be wrapped to the next line. When disabled, text will continue off the screen. The user will need to scroll the detail pane to view the text.
  • Format: Sets the values displayed in the Detail Pane. This pane can be set to a combination of static text and format strings, which take the form %propertyName. The propertyName is the name of a property defined within the selected object and will be updated with the value of that property each time a different object is selected. It may also be set to the return value of a rule, which is evaluated in the context of the selected object instance and is expected to return a string.

Scanner Attributes

The scanner attributes for a list screen affect only those list screens used by a scanner platform within the screen set and only when the list screen is displayed on a client device with a barcode scanner. At least one column definition within the list screen must be defined to support scan filtering.

A scanned value will be compared to the column(s) defined for scan filtering and only those matching this value will then be displayed. Actions may be defined when only one record matches the scan filter and when no records match.
  • Single Match Action: Specifies what action is executed when a scanned barcode value matches one of the records displayed in the list screen. The target of the action will always be the record found to match.
  • No Match Action: Specifies what action is executed when the scanner filter criteria does not match any records on the list. This is optional. The target of the action is the object that is the parent to the collection property displayed by the list.
  • Label Type: Specifies what barcode types are accepted by the Agentry Client. If no Label Type is specified, all types supported by the client device will be supported.
  • Minimum Value: The minimum number of characters accepted by the Agentry Client from the device scanner.
  • Maximum Value: The maximum number of characters to be accepted by the Agentry Client from the device scanner. If the value scanned in contains more characters, it will be ignored.
Parent topic: Module-Level User Interface Definitions Overview