| Navigation: Language Reference > 9 - Window and Report Attributes > Window and Report Attributes >====== FORMAT (set LIST or COMBO layout) ====== |    |
FORMAT(format string)
| FORMAT | Specifies the display or print format of the data in the LIST or COMBO control. |
| format string | A string constant specifying the display format. |
The FORMAT attribute (PROP:FORMAT) specifies the display format of the data in the LIST or COMBO control. The format string contains the information for formatting of data. PROP:FORMAT is updated whenever the user dynamically changes the format of the LIST or COMBO at runtime.
The format string contains “field-specifiers” which map to the fields of the QUEUE being displayed. Multiple “field-specifiers” may be grouped together as a “field-group” in square brackets ([ ]) to display as a single unit.
Only the fields in the QUEUE for which there are “field-specifiers” are included in the display. This means that, if there are two fields specified in the format string and three fields in the QUEUE, only the two specified in the format string are displayed in the LIST or COMBO control.
“Field-specifier” format:
Each column in the LIST is formatted with the following components. The format for a particular column is returned or set by PROPLIST:Format.
width justification [ (indent) ] [ modifiers ]
| width | A required integer defining the width of the field (PROPLIST:Width). Specified in dialog units. |
| justification | A single capital letter (L , R , C , or D) that specifies Left (PROPLIST:Left), Right (PROPLIST:Right), Center (ROPLIST:Center), or Decimal (PROPLIST:Decimal) justification. One is required. |
| indent | An optional integer, enclosed in parentheses, that specifies the indent from the justification. This may be negative. With left (L) (PROPLIST:LeftOffset) justification, indent defines a left margin ; with right (R) (PROPLIST:RightOffset) or decimal (D) (PROPLIST:DecimalOffset), it defines a right margin; and with center (C) (PROPLIST:CenterOffset), it defines an offset from the center of the field (negative = left offset). |
| modifiers: | Optional special characters (listed below) to modify the display format of the field or group. Multiple modifiers may be used on one field or group. |
Modifiers:
| * | An asterisk (PROPLIST:Color) indicates color information for the field is contained in four LONG fields that immediately follow the data field in the QUEUE (or FROM attribute string). The four colors are normal foreground, normal background, selected foreground, and selected background (in that order). Not valid in a REPORT. |
 |
|
| Color may also be set by using a list box style. (see “Y” below) | |
| B (color) | Specifies the color to use for the selction bar frame (PROPLIST:BarFrame) |
| E ([color1][,color2][,color3][,color4]) | Parameters of the E modifier are normal foreground, normal background, selected foreground and selected background colors respectively. These colors are used as the default for a list column. If the column also includes the * modifier, these default colors can be overridden by values from the list source (queue, VLB, etc.). Default colors are used if the * modifier is not specified for the column, or color value set in the list source is equal to COLOR:None. In the Listbox Formatter, the default colors can be set on the Appearance tab.The default column colors can be set or changed from the program using the following properties: PROPLIST:TextColor, PROPLIST:BackColor, PROPLIST:TextSelected and PROPLIST:BackSelected. |
| I | An I (PROPLIST:Icon) indicates an icon displays in the column, at the left edge of the column (prepended to the data). An icon number is contained in a LONG field immediately following the data field in the QUEUE (or FROM attribute string). The LONG field contains a number that refers to an entry in a list of icons associated with the LIST control through the PROP:IconList runtime property. If an asterisk is also specified for color, this LONG must follow all the color information. Not valid in a REPORT. To display the icon only, and not the contents of the data field, make the display picture @P_PB. |
| J | A J (PROPLIST:IconTrn) indicates a transparent icon displays in the column. The same information as I applies to J. Not valid in a REPORT. |
| T [ (suppress) ] | A T (PROPLIST:Tree) indicates the LIST is a tree control. The tree level is contained in a LONG field that immediately follows the data field in the QUEUE (or FROM attribute string). If * and I are also specified, this LONG must follow all their LONG fields. The expanded/contracted state of the tree level is determined by the sign of the tree level LONG field's value (positive value=expanded and negative value=contracted). Not valid in a REPORT. |
| The optional suppress parameter can contain a 1 (PROPLIST:TreeOffset) to indicate the root is level number one (1) instead of zero (0), allowing -1 to indicate a contracted root. It can also contain an R (PROPLIST:TreeRoot) to suppress the connecting lines to the root level, an L (PROPLIST:TreeLines) to suppress the connecting lines between all levels, a B (PROPLIST:TreeBoxes) to suppress expansion boxes, and an I (PROPLIST:TreeIndent) to suppress level indentation (which also implicitly suppresses both lines and boxes). | |
| Y | A Y (PROPLIST:CellStyle) indicates a pre-defined style for the field (column) is contained in a LONG field that immediately follows the data field in the QUEUE (or FROM attribute string). The LONG field contains a number that refers to an entry in an array of styles associated with the LIST control through the PROPSTYLE: runtime properties (see below). Not valid in a REPORT. |
| Z(style) | A 'Z' followed by a 'style' (PROPLIST:ColStyle) sets the default style for an entire column. |
The style for an entire column may be set with PROPLIST:ColStyle. Using PROPLIST:ColStyle, the LONG field is not necessary in the QUEUE but without the LONG field you cannot assign different styles to individual cells in the column.
~header~ [ justification [ (indent) ] ]
A header string enclosed in tildes (PROPLIST:Header), followed by optional justification parameter (L = PROPLIST:HeaderLeft, R = PROPLIST:HeaderRight, C = PROPLIST:HeaderCenter, or D = PROPLIST:HeaderDecimal, ) and/or indent value in parentheses (PROPLIST:HeaderLeftOffset, PROPLIST:HeaderRightOffset, PROPLIST:HeaderCenterOffset, or PROPLIST:HeaderDecimalOffset), displays the header at the top of the list. The header uses the same justification and indent as the field, if not specifically overridden.
| @picture@ | The picture (PROPLIST:Picture) formats the field for display. The trailing @ is required to define the end of the picture, so that display pictures such as @N12~Kr~ can be used in the format string without creating ambiguity. |
| ? | A question mark (PROPLIST:Locator) defines the locator field for a COMBO list box with a selector field. For a drop-down multi-column list box, this is the value displayed in the current-selection box. Not valid in a REPORT.Only one column can have the locator (?) modifier in the LIST/COMBO FORMAT string. If no column has the locator modifier, the 1st column is assumed as the locator.The locator column is used for the following purposes:·The value of the locator field of current record is copied to the LIST/COMBO's USE variable.·The runtime library locates a record upon typing when the LIST has focus, or the COMBO's list is dropped down and the USE variable is changed.·The value of the locator column of the current COMBO's record is displayed in the entry sub-control. |
| #number# | The number enclosed in pound signs (#) (PROPLIST:FieldNo) indicates the QUEUE field to display. Following fields in the format string without an explicit #number# are taken in order from the fields following the #number# field. For example, #2# on the first field in the format string indicates starting with the second field in the QUEUE, skipping the first. If the number of fields specified in the format string are >= the number of fields in the QUEUE, the format “wraps around” to the start of the QUEUE. |
| _ | An underscore (PROPLIST:Underline) underlines the field. |
| / | A slash (PROPLIST:LastOnLine) causes the next field to appear on a new line (only used on a field within a group). |
| | | A vertical bar (PROPLIST:RightBorder) places a vertical line to the right of the field. |
| M | An M (PROPLIST:Resize) allows the field or group of fields to be dynamically re-sized at runtime. This allows the user to drag the right vertical bar (if present) or right edge of the data area. Not valid in a REPORT. |
| F | An F (PROPLIST:Fixed) creates a fixed column in the list that stays on screen when the user horizontally pages through the fields (by the HSCROLL attribute). Fixed fields or groups must be at the start of the list. This is ignored if placed on a field within a group. Not valid in a REPORT. |
| S(integer) | An S followed by an integer (PROPLIST:Scroll) in parentheses adds a scroll bar to the group. The integer defines the total number of dialog units to scroll. This allows large fields to be displayed in a small column width. This is ignored if placed on a field within a group. Not valid in a REPORT. |
| P | A P modifier adds a tool tip (ROPLIST:Tip) to the group. The column's tip text by default is derived from the next queue field that follows the queue field used to hold the actual column's data. If the designated queue field is empty, the Q modifier (see below) designates a string value to use as a default tool tip. Also valid with a VLB (Virtual List Box). Not valid in a REPORT. |
| Q (string) | A Q followed by a string (PROPLIST:DefaultTip) designates the default column tip text to be displayed if the value of the designated P modifier is an empty string. Not valid in a REPORT. |
“Field-group” format:
[ multiple field-specifiers ] [ (size) ] [ modifiers ]
| multiple field-specifiers | A list of field-specifiers contained in square brackets ( [ ] ) that cause them to be treated as a single display unit. |
| size | An optional integer, enclosed in parentheses, that specifies the width of the group (PROPLIST:Width). If omitted, the size is calculated from the enclosed fields. |
| modifiers | The “field-group” modifiers act on the entire group of fields. These are the same modifiers listed above for a field (except the *, I, T ,and #number# modifiers which are not appropriate to groups). Add PROPLIST:Group to the appropriate field property to affect the group properties. PROPLIST:GroupNo can be used to return the group number of a target column. |
Example:
?List{PROPLIST:GroupNo,LOC:COL}
returns the group number of the column variable (LOC:COL). A Column not in a group is considered a group by itself.
?List{PROPLIST:GroupNo + PROPLIST:Group,LOC:COL}
returns the number of columns in the target group, 0 if the group is really a column.
Display QUEUE Field Format
The order of fields that appear in the QUEUE to display in the LIST is important. Since there are several modifiers which require separate fields in the QUEUE to hold formatting data, the following is the order in which those fields must appear in the QUEUE:
1.The field containing the data to display (always).
2.The * flag's foreground color field (if the * is present, or PROPLIST:Color is set).
3.The * flag's background color field (if the * is present, or PROPLIST:Color is set).
4.The * flag's selected foreground color field (if the * is present, or PROPLIST:Color is set).
5.The * flag's selected background color field (if the * is present, or PROPLIST:Color is set).
6.The I or J flag's icon field (if the I or J is present, or PROPLIST:Icon or PROPLIST:IconTrn is set).
7.The T flag's tree level field (if the T is present, or PROPLIST:Tree is set).
8.The Y flag's style field (if the Y is present, or PROPLIST:CellStyle is set).
9.The P flag's tool tip field (if the P is present, or PROPLIST:Tip is set)