HATS 7.5.1 Web API Reference

Publicly accessible methods not documented here are for IBM internal use only and may change in a future release of the product.

com.ibm.hats.transform.components
Class SelectionListComponent

java.lang.Object
  extended by com.ibm.hats.transform.components.Component
      extended by com.ibm.hats.transform.components.SelectionListComponent
All Implemented Interfaces:
IContextDependent, ICustomPropertySupplier

public class SelectionListComponent
extends Component
implements IContextDependent

The Selection List component is responsible for recognizing selection lists (aka menus) in a specified region of a host screen.

A recognized selection list can be rendered by the following widgets:

The recognize() methods of this component return ComponentElement objects of type: The following settings can be configured for this component:

PropertyDescriptionTypeDefault Value
reqValueBeforeLeadingTokenThe string which precedes the leading token of each list item.String(two spaces)
leadingTokenTypeSpecifies whether each list item starts with letters, digits, or both letters and digits.enumEITHER
maxLeadingTokenLengthSpecifies the maximum length of the leading token (used to help restrict what gets recognized as a list item).int4
delimiterThe string of characters between the leading token and the description. You can specify more than one value, separated by the "|" (vertical bar) character.String". |- " (period space OR dash space)
stringAfterCaptionThe string of characters which must follow each list itemString(two spaces)
minimumReqOptionsThe minimum number of list items that must be found in order for the selected region to be recognized as a selection list.int2
targetSpecifies which input field receives the selection. Options: FIRST, LAST, PREVIOUS, NEXT, SPECIFIED, CURSOR.enumNEXT
targetFieldRowSpecifies the row of the input field which should receive the selection. Note: This setting only applies if "SPECIFIED" is selected as the selection target.int-1
targetFieldColSpecifies the column of the input field which should receive the selection. Note: This setting only applies if "SPECIFIED" is selected as the selection target.int-1
actionKeySpecifies the host aid key that should be pressed after the target input field has been updated with the end user's selection. The default value is "[enter]" meaning that the enter key will be pressed once the user makes a selection.String[enter]
sortSelectionsIf true, list items are sorted according to either their leading token or description (see below for more information on other settings).booleanfalse
sortBySpecifies whether to sort the set of list options by their leading token or description. Valid values: ITEM or DESCRIPTIONenumITEM
sortOrderSpecifies whether to sort the set of list options in ascending or descending order. Note: The locale-sensitive sorting methods, built into Java, are used to perform this operation. Valid values: ASCENDING or DESCENDINGenumASCENDING
convertActionNumberIf your host displays full-width characters for the list items' leading token, but it expects the item to be entered into the target input field as single-byte characters, then this parameter must be enabled. This will convert the DBCS item into a SBCS item before it is sent to the host. This setting does not apply for items which are displayed as single-byte characters on the host.booleantrue
placeholdersSpecifies whether to embed placeholder list items when gaps (i.e. empty space) exist between list items. Valid values: NONE, SINGLE, or ACTUAL.enumACTUAL
maxSpaceAfterDelimiterSpecifies the maximum number of space characters between the end of the delimiter and the start of the captionint5

Example
In the following example, "1" is the leading token, ". " is the delimiter, "User tasks" is the caption, and " " (two spaces) is the end delimiter:

1. User tasks

See Also:
SelectionComponentElement

Nested Class Summary
static class SelectionListComponent.GroupingHint
          Internal class used to help group related list items together.
 
Field Summary
static String CLASS_NAME
           
static Properties defaults
           
static int INT_TARGET_CLOSEST
           
static int INT_TARGET_CURSOR_POSITION
           
static int INT_TARGET_FIELD
           
static int INT_TARGET_FIRST_ON_SCREEN
           
static int INT_TARGET_LAST_ON_SCREEN
           
static int INT_TARGET_NEXT
           
static int INT_TARGET_PREVIOUS
           
static String LEADINGTOKEN_DIGIT
           
static String LEADINGTOKEN_EITHER
           
static String LEADINGTOKEN_LETTER
           
static String PLACEHOLDER_ACTUAL
           
static String PLACEHOLDER_NONE
           
static String PLACEHOLDER_SINGLE
           
static String PROPERTY_ACTION_KEY
           
static String PROPERTY_CONVERT_ACTION_NUMBER
           
static String PROPERTY_DELIMITER
           
static String PROPERTY_END_DELIMITER
           
static String PROPERTY_GROUP_INDIVIDUALLY
           
static String PROPERTY_IGNORE_TARGET_INPUT_FIELD
           
static String PROPERTY_LEADING_TOKEN_TYPE
           
static String PROPERTY_MAX_LEADING_TOKEN_LENGTH
           
static String PROPERTY_MAX_SPACE_AFTER_DELIMITER
           
static String PROPERTY_MINIMUM_REQ_OPTIONS
           
static String PROPERTY_OPTIONS_TO_EXCLUDE
           
static String PROPERTY_PLACEHOLDERS
           
static String PROPERTY_SORT_BY
           
static String PROPERTY_SORT_ORDER
           
static String PROPERTY_SORT_SELECTIONS
           
static String PROPERTY_TARGET
           
static String PROPERTY_TARGET_COL
           
static String PROPERTY_TARGET_ROW
           
static String PROPERTY_USE_ACTION
           
static String PROPERTY_VALUE_BEFORE_LEADING_TOKEN
           
static String SORT_BY_DESCRIPTION
           
static String SORT_BY_ITEM
           
static String SORT_ORDER_ASCENDING
           
static String SORT_ORDER_DESCENDING
           
static String TARGET_CLOSEST
           
static String TARGET_CURSOR_POSITION
           
static String TARGET_FIELD
           
static String TARGET_FIRST_ON_SCREEN
           
static String TARGET_LAST_ON_SCREEN
           
static String TARGET_NEXT
           
static String TARGET_PREVIOUS
           
 
Fields inherited from class com.ibm.hats.transform.components.Component
contextAttributes, flag, hostScreen
 
Fields inherited from interface com.ibm.hats.common.ICustomPropertySupplier
CLASSNAME
 
Constructor Summary
SelectionListComponent(HsrScreen hostScreen)
          Constructs a new SelectionListComponent object.
 
Method Summary
protected  SelectionComponentElement addPlaceholders(SelectionComponentElement sce, Hashtable groupingHints, String type)
          Method which adds empty placeholder list items to the selection list set.
protected  int calculateTargetField(int target, int listItemStartPos, int targetRow, int targetCol)
           
 Vector getCustomProperties(int iPageNumber, Properties properties, ResourceBundle bundle)
          Returns a list of this object's custom properties.
 Properties getDefaultValues(int iPageNumber)
          Returns this object's default property values.
 boolean getIsSubfileWidget()
           
 int getPropertyPageCount()
          Returns the number of property pages associated with this object.
 String[] getValueBefore(Properties settings)
          Deprecated. Internal use only.
protected  SelectionComponentElement[] groupListItems(ComponentElementList cel, Hashtable groupingHints, int minReqOptions, boolean inDefaultRendering)
          This method takes a ComponentElementList (of ListItemComponentElement objects) and groups them into separate, logical selection lists (used for Default Rendering).
protected  SelectionComponentElement[] groupListItems(ComponentElementList cel, Hashtable groupingHints, int minReqOptions, boolean inDefaultRendering, boolean groupIndividually, boolean isRecognizedOpposite)
          This method takes a ComponentElementList (of ListItemComponentElement objects) and groups them into separate, logical selection lists (used for Default Rendering).
 boolean isAllowed(ContextAttributes contextAttributes)
          Gets whether or not this object should be visible in the studio given some context attributes.
 boolean isPropertyAllowed(String name, ContextAttributes contextAttributes)
          Gets whether or not the specified property should be visible in the component or widget settings.
 ComponentElement[] recognize(BlockScreenRegion region, Properties settings)
          Returns an array of SelectionComponentElement objects representing each selection list found in the specified region of the screen.
 ComponentElement[] recognize(com.ibm.hats.transform.regions.LinearScreenRegion region, Properties settings)
          Currently not implemented.
 void setIsSubfileWidget(boolean isSubfile)
           
 
Methods inherited from class com.ibm.hats.transform.components.Component
convertPosToCol, convertPosToRow, convertRowColToPos, findFirstDelimiterIndex, findFirstIndexOf, findFirstIndexOf, findFirstIndexOf, findFirstNonWhitespaceIndex, findFirstNonWhitespaceIndex, findFirstNonWhitespaceIndex, getContextAttribute, getContextAttributes, getCustomComposite, getHostScreen, getTrailingSpaceCount, newInstance, recognize, setContextAttribute, setContextAttributes, setHostScreen
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLASS_NAME

public static final String CLASS_NAME
See Also:
Constant Field Values

PROPERTY_VALUE_BEFORE_LEADING_TOKEN

public static final String PROPERTY_VALUE_BEFORE_LEADING_TOKEN
See Also:
Constant Field Values

PROPERTY_LEADING_TOKEN_TYPE

public static final String PROPERTY_LEADING_TOKEN_TYPE
See Also:
Constant Field Values

PROPERTY_MAX_LEADING_TOKEN_LENGTH

public static final String PROPERTY_MAX_LEADING_TOKEN_LENGTH
See Also:
Constant Field Values

PROPERTY_DELIMITER

public static final String PROPERTY_DELIMITER
See Also:
Constant Field Values

PROPERTY_END_DELIMITER

public static final String PROPERTY_END_DELIMITER
See Also:
Constant Field Values

PROPERTY_MINIMUM_REQ_OPTIONS

public static final String PROPERTY_MINIMUM_REQ_OPTIONS
See Also:
Constant Field Values

PROPERTY_SORT_SELECTIONS

public static final String PROPERTY_SORT_SELECTIONS
See Also:
Constant Field Values

PROPERTY_SORT_BY

public static final String PROPERTY_SORT_BY
See Also:
Constant Field Values

PROPERTY_SORT_ORDER

public static final String PROPERTY_SORT_ORDER
See Also:
Constant Field Values

PROPERTY_OPTIONS_TO_EXCLUDE

public static final String PROPERTY_OPTIONS_TO_EXCLUDE
See Also:
Constant Field Values

PROPERTY_CONVERT_ACTION_NUMBER

public static final String PROPERTY_CONVERT_ACTION_NUMBER
See Also:
Constant Field Values

PROPERTY_PLACEHOLDERS

public static final String PROPERTY_PLACEHOLDERS
See Also:
Constant Field Values

PROPERTY_MAX_SPACE_AFTER_DELIMITER

public static final String PROPERTY_MAX_SPACE_AFTER_DELIMITER
See Also:
Constant Field Values

PROPERTY_IGNORE_TARGET_INPUT_FIELD

public static final String PROPERTY_IGNORE_TARGET_INPUT_FIELD
See Also:
Constant Field Values

PROPERTY_TARGET

public static final String PROPERTY_TARGET
See Also:
Constant Field Values

PROPERTY_TARGET_ROW

public static final String PROPERTY_TARGET_ROW
See Also:
Constant Field Values

PROPERTY_TARGET_COL

public static final String PROPERTY_TARGET_COL
See Also:
Constant Field Values

PROPERTY_ACTION_KEY

public static final String PROPERTY_ACTION_KEY
See Also:
Constant Field Values

PROPERTY_USE_ACTION

public static final String PROPERTY_USE_ACTION
See Also:
Constant Field Values

TARGET_FIRST_ON_SCREEN

public static final String TARGET_FIRST_ON_SCREEN
See Also:
Constant Field Values

TARGET_LAST_ON_SCREEN

public static final String TARGET_LAST_ON_SCREEN
See Also:
Constant Field Values

TARGET_PREVIOUS

public static final String TARGET_PREVIOUS
See Also:
Constant Field Values

TARGET_NEXT

public static final String TARGET_NEXT
See Also:
Constant Field Values

TARGET_FIELD

public static final String TARGET_FIELD
See Also:
Constant Field Values

TARGET_CURSOR_POSITION

public static final String TARGET_CURSOR_POSITION
See Also:
Constant Field Values

TARGET_CLOSEST

public static final String TARGET_CLOSEST
See Also:
Constant Field Values

INT_TARGET_FIRST_ON_SCREEN

public static final int INT_TARGET_FIRST_ON_SCREEN
See Also:
Constant Field Values

INT_TARGET_LAST_ON_SCREEN

public static final int INT_TARGET_LAST_ON_SCREEN
See Also:
Constant Field Values

INT_TARGET_PREVIOUS

public static final int INT_TARGET_PREVIOUS
See Also:
Constant Field Values

INT_TARGET_NEXT

public static final int INT_TARGET_NEXT
See Also:
Constant Field Values

INT_TARGET_FIELD

public static final int INT_TARGET_FIELD
See Also:
Constant Field Values

INT_TARGET_CURSOR_POSITION

public static final int INT_TARGET_CURSOR_POSITION
See Also:
Constant Field Values

INT_TARGET_CLOSEST

public static final int INT_TARGET_CLOSEST
See Also:
Constant Field Values

LEADINGTOKEN_DIGIT

public static final String LEADINGTOKEN_DIGIT
See Also:
Constant Field Values

LEADINGTOKEN_LETTER

public static final String LEADINGTOKEN_LETTER
See Also:
Constant Field Values

LEADINGTOKEN_EITHER

public static final String LEADINGTOKEN_EITHER
See Also:
Constant Field Values

SORT_BY_ITEM

public static final String SORT_BY_ITEM
See Also:
Constant Field Values

SORT_BY_DESCRIPTION

public static final String SORT_BY_DESCRIPTION
See Also:
Constant Field Values

SORT_ORDER_ASCENDING

public static final String SORT_ORDER_ASCENDING
See Also:
Constant Field Values

SORT_ORDER_DESCENDING

public static final String SORT_ORDER_DESCENDING
See Also:
Constant Field Values

PLACEHOLDER_NONE

public static final String PLACEHOLDER_NONE
See Also:
Constant Field Values

PLACEHOLDER_SINGLE

public static final String PLACEHOLDER_SINGLE
See Also:
Constant Field Values

PLACEHOLDER_ACTUAL

public static final String PLACEHOLDER_ACTUAL
See Also:
Constant Field Values

PROPERTY_GROUP_INDIVIDUALLY

public static final String PROPERTY_GROUP_INDIVIDUALLY
See Also:
Constant Field Values

defaults

public static Properties defaults
Constructor Detail

SelectionListComponent

public SelectionListComponent(HsrScreen hostScreen)
Constructs a new SelectionListComponent object.

Method Detail

setIsSubfileWidget

public void setIsSubfileWidget(boolean isSubfile)

getIsSubfileWidget

public boolean getIsSubfileWidget()

getValueBefore

public String[] getValueBefore(Properties settings)
Deprecated. Internal use only.

Parameters:
settings - The Properties settings.

recognize

public ComponentElement[] recognize(BlockScreenRegion region,
                                    Properties settings)
Returns an array of SelectionComponentElement objects representing each selection list found in the specified region of the screen.

Specified by:
recognize in class Component
Parameters:
region - BlockScreenRegion to search in
settings - recognition settings
Returns:
an array of ComponentElement objects.
See Also:
Component.recognize(BlockScreenRegion, Properties), SelectionComponentElement

calculateTargetField

protected int calculateTargetField(int target,
                                   int listItemStartPos,
                                   int targetRow,
                                   int targetCol)
Parameters:
target - (see the list of static fields in this class beginning with "INT_TARGET..." above)
listItemStartPos - linear, 1-based start position of the first item in the list
targetRow - 1-based target row number (only applicable if target == SPECIFIED)
targetCol - 1-based target column number (only applicable if target == SPECIFIED)

groupListItems

protected SelectionComponentElement[] groupListItems(ComponentElementList cel,
                                                     Hashtable groupingHints,
                                                     int minReqOptions,
                                                     boolean inDefaultRendering)
This method takes a ComponentElementList (of ListItemComponentElement objects) and groups them into separate, logical selection lists (used for Default Rendering).

In the groupingHints Hashtable, for each item, the key will be a ListItemComponentElement object and the value will be a GroupingHint object.

Parameters:
cel - list of ListItemComponentElement objects
groupingHints - table of "grouping hint" objects.
minReqOptions - minimum number of options that must be bound to the same target input field.
Returns:
an array of SelectionComponentElement objects, each representing a set of related list items.

groupListItems

protected SelectionComponentElement[] groupListItems(ComponentElementList cel,
                                                     Hashtable groupingHints,
                                                     int minReqOptions,
                                                     boolean inDefaultRendering,
                                                     boolean groupIndividually,
                                                     boolean isRecognizedOpposite)
This method takes a ComponentElementList (of ListItemComponentElement objects) and groups them into separate, logical selection lists (used for Default Rendering).

In the groupingHints Hashtable, for each item, the key will be a ListItemComponentElement object and the value will be a GroupingHint object.

Parameters:
cel - list of ListItemComponentElement objects
groupingHints - table of "grouping hint" objects.
minReqOptions - minimum number of options that must be bound to the same target input field.
groupIndividually - group list items in their own group (after confirming they belong to a group)
Returns:
an array of SelectionComponentElement objects, each representing a set of related list items.

addPlaceholders

protected SelectionComponentElement addPlaceholders(SelectionComponentElement sce,
                                                    Hashtable groupingHints,
                                                    String type)
Method which adds empty placeholder list items to the selection list set.

Parameters:
sce - list to add placeholders to
groupingHints - table of grouping hints (used to determine space between list items)
type - PLACEHOLDERS setting ("NONE", "SINGLE", or "ACTUAL")
Returns:
modified (if placeholders were added) version of sce parameter
See Also:
PlaceholderListItemComponentElement, SelectionListComponent.GroupingHint

recognize

public ComponentElement[] recognize(com.ibm.hats.transform.regions.LinearScreenRegion region,
                                    Properties settings)
Currently not implemented.

Specified by:
recognize in class Component

getPropertyPageCount

public int getPropertyPageCount()
Description copied from interface: ICustomPropertySupplier
Returns the number of property pages associated with this object.

Note: Currently only 0 or 1 pages are supported.

Specified by:
getPropertyPageCount in interface ICustomPropertySupplier
Overrides:
getPropertyPageCount in class Component
Returns:
the number of defined property pages used to configure this object, or 0 if there are none

getCustomProperties

public Vector getCustomProperties(int iPageNumber,
                                  Properties properties,
                                  ResourceBundle bundle)
Description copied from interface: ICustomPropertySupplier
Returns a list of this object's custom properties. Items must be of type com.ibm.hats.common.HCustomProperty.

Specified by:
getCustomProperties in interface ICustomPropertySupplier
Overrides:
getCustomProperties in class Component
Parameters:
iPageNumber - page number containing desired properties
properties - existing values for properties defined here
bundle - ResourceBundle containing NLS descriptions for the properties
Returns:
Vector containing all the custom properties for this object, or null if there are none
See Also:
HCustomProperty

getDefaultValues

public Properties getDefaultValues(int iPageNumber)
Description copied from interface: ICustomPropertySupplier
Returns this object's default property values.

Specified by:
getDefaultValues in interface ICustomPropertySupplier
Overrides:
getDefaultValues in class Component
Parameters:
iPageNumber - page for which to retrieve default properties
Returns:
object's default properties

isAllowed

public boolean isAllowed(ContextAttributes contextAttributes)
Description copied from interface: IContextDependent
Gets whether or not this object should be visible in the studio given some context attributes. The context attributes may contain the Component name when this is called on a Widget, or whether or not we are presenting this Component/Widget choice while configuring Default Rendering.

Specified by:
isAllowed in interface IContextDependent
Returns:
whether or not this Component or Widget is allowed in the specified context

isPropertyAllowed

public boolean isPropertyAllowed(String name,
                                 ContextAttributes contextAttributes)
Description copied from interface: IContextDependent
Gets whether or not the specified property should be visible in the component or widget settings. The context attributes may contain the Component name when this is called on a Widget, or whether or not we are presenting this Component/Widget choice while configuring Default Rendering.

Specified by:
isPropertyAllowed in interface IContextDependent
Parameters:
name - property name
Returns:
whether or not this property is allowed in the specified context

HATS 7.5.1 (201005110649)