| **Navigation:**  »No topics above this level«====== List Box Formatter Dialog ====== | {{btn_prev_d.gif}}[[coming future.htm|{{btn_home_n.gif|Return to chapter overview}}]]{{btn_next_d.gif}} |
|  ||

The List Box Formatter dialog shows how the list box under construction looks. It fills this sample list box with placeholder characters representing the contents of each field. If any field contains a header, a header row appears over the column.

You format the fields one by one in the **Properties **dialog. The sample list box always displays a horizontal scroll bar, whether you specify one in the **[[list control properties.htm|List Properties]] **dialog or not.

Select multilple columns for editing using CTRL + CLICK. You can also just use the keyboard. Hold the CTRL key and press the up or down arrow key. To unselect all items just release the Ctrl key and press the up or down arrow key. or release the CTRL key and mouse click on any column.

The formatter does //not //display a vertical scroll bar. If the queue contains more items than rows in the list, and if you add the VSCROLL attribute by checking the box in the **List Properties **dialog, the vertical scroll bar appears at run time.

The dialog contains the following buttons:

{{formateditorbuts.jpg|FormatEditorButs.jpg}}

| **Add Group**{{addgroup.jpg|AddGroup.jpg}} | To add a new Group, press the **New Group** button (or SHIFT+INS). This adds the currently highlighted column into the new group. Use the **Move Column** butttons to move other columns into (or out of) a group. |
| **Add Field**{{addfield.jpg|AddField.jpg}} | To add a field to the list box, press the **New Column **button (or INS).When opening the **List Box Formatter** from within the Application Generator, using a procedure template which supports it, the **Populate **button displays the **Select Field** dialog. From here, you can indicate any database field or memory variable for use as a list box column. The generated code puts the contents of the database records into the queue for use in the list box. |
| **Remove**{{remove.jpg|Remove.jpg}} | Removes the currently selected field from the list box. |
| **Move Left**{{moveleft.jpg|MoveLeft.jpg}} | (CTRL + LEFT ARROW) Moves the currently selected field one position to its left. If the selected field is the leftmost in a group, the field moves out of the group, without changing position. If the selected field is immediately to the right of a group, the field moves into the group, without changing position. |
| **Move Right**{{moveright.jpg|MoveRight.jpg}} | (CTRL + RIGHT ARROW) Moves the currently selected field one position to its right. If the selected field is the rightmost in a group, the field moves out of the group, without changing position. If the selected field is immediately to the left of a group, the field moves into the group, without changing position. |

See the following topics for more information about adding list box functionality:

[[how to restore user resized list box column widths.htm|How to Restore User Resized List Box Column Widths]]

[[how to trap a double click on a list box.htm|How to Trap a Double Click on a List Box]]

[[how to add drag and drop to a list box.htm|How to add Drag and Drop to a List Box]]

[[how to display the sort field first on a multi key browse.htm|How to Display the Sort Field First on a Multi-Key Browse]]

[[using drop down lists to lookup records.htm|Using drop-down lists to Lookup Records]]

**Color and Style**

Use these prompts to set the default colors for all list rows and columns.

| **Background** | To set the default color for normal (unselected) list background, type a valid color equate in this field, or press the ellipsis (...) button to select a color from the color dialog.Adds an "E(,//color//,,)" to the FORMAT string. |
| **Default Style** | Type the default style number. The style number sets the font typeface, size, style, and color for all list rows and columns.Adds a "Z(//n//)" to the FORMAT string, where //n// is the style number. |
| **Selected Background** | To set the default color for normal (unselected) list background, type a valid color equate in this field, or press the ellipsis (...) button to select a color from the color dialog.Adds an "E(,,,//color//)" to the FORMAT string. |
| **Selected Text** | To set the default color for normal (unselected) list text, type a valid color equate in this field, or press the ellipsis (...) button to select a color from the color dialog.Adds an "E(,,//color//,)" to the FORMAT string. |
| **TextColor** | To set the default color for normal (unselected) list text, type a valid color equate in this field, or press the ellipsis (...) button to select a color from the color dialog.Adds an "E(//color//,,,)" to the FORMAT string. |

**Data**

| **AutoFieldNumber** | This property provides support for the Field Number of a column, and the ability to override it. Set this proprty to True to designate that the field numbering of the selected column will be "standard", based on the order that it appears in the list box. Setting this property to False allows the field numbering to be modified. This feature is important for some list box properties that require field number information, and gives you the ability to control it. |
| **DataIndent** | Optionally specify an indent, in dialog units, for the listbox data. Indent moves the data by the number of dialog units specified, in the opposite direction to the justification. An indent of two (2) on left justified data improves listbox readability. The indent appears within the FORMAT string surrounded by parentheses and preceded by a letter indicating the justification, as in "L(8)." |
| **DataJustification** | Choose from the drop-down list to specify left, right, center or decimal. Decimal justification aligns decimal numbers by their decimal points. The justification appears in the FORMAT string following the data width, as in "40R." |
| **FieldNumber** | If the **AutoFieldNumber** property is set to False, enter a custom Field Number here. If the **AutoFieldNumber** property is set to False, this property is Read Only. |
| **Picture** | Specify the picture token for the data. The **List box Formatter** displays the data according to the picture token. For example, the picture token @P(###) ###-####P displays a phone number as (555) 555-5555.The picture token you specify appears in the FORMAT string. |

**Flags**

| **Fixed** | Set to True to specify that the column always remains visible in the listbox, even if other columns scroll.The FORMAT string includes the "F" character, immediately preceding the header text as in "F~MyHeader~." |
| **HasColor** | Set to True to allow conditional runtime colors for individual list items--that is, to conditionally override the default colors for individual list rows. The color information for each row is contained in four LONG fields that immediately follow the data field in the QUEUE. Assign the color value to the appropriate QUEUE field at runtime, and Clarion's runtime library does the rest.See //Control Templates--[[tplcontrolbrowsebox.htm|BrowseBox Control]] //for information on specifying conditional BrowseBox colors, and see [[format  set list or combo layout .htm|FORMAT]] in the //Language Reference//.Adds an asterisk "*" to the FORMAT string. |
| **LastOnLine** | Set to True to specify that the next field in the group will appear immediately below the current field (if there are multiple fields in the first line of the group, the field will actually appear below the first field in the first line group). In effect, it stacks two or more fields below the group header.{{notebox.jpg|NoteBox.jpg}}The field must be part of a group.{{tipbox.jpg|TipBox.jpg}}For the best display, make sure that your window is not resizable when using multi-line groups.The FORMAT string includes the "/" character, immediately preceding the header text as in "/~MyHeader~." |
| **Locator** | By default, the first field in a multi-column COMBO displays in the entry portion of the COMBO. Set **Locator** to True to specify that this field (instead of the first field) displays in the entry box portion of a multi-column COMBO control.The FORMAT string includes the "?" character, immediately preceding the header text as in "?~MyHeader~." |
| **Resizeable** | Set to True to specify that the user can resize the width of the columns at run time.The FORMAT string includes the "M" character, immediately preceding the header text as in "M~MyHeader~."See [[how to restore user resized list box column widths.htm|How to Restore User Resized List Box Column Widths.]].. |
| **RightBorder** | Set to True to specify column separators between fields in the listbox at run time.The [[format  set list or combo layout .htm|FORMAT]] string includes the pipe symbol ( | ), immediately preceding the header text, as in "|~MyHeader~." |
| **Style** | Set to True to allow conditional runtime fonts for individual list items--that is, to conditionally override the default fonts for individual list rows. The font (style) information for each row is contained in a LONG field that immediately follows the data field in the QUEUE. Assign the style value to the appropriate QUEUE field at runtime, and Clarion's runtime library does the rest.See Control Templates--BrowseBox Control in the Template Guide for information on specifying conditional BrowseBox colors, and see FORMAT in the Language Reference.Adds a "Y" to the FORMAT string. |
| **Tooltip** | Set to True to activate a specific tool tip for the selected column. The tool tip content is specified on the Appearance tab. Adds a "P" to the FORMAT string. {{tipbox.jpg|TipBox.jpg}} Before you can activate individual column tool tips, make sure that you have a tool tip defined for the list box control. This is found on the Help tab of the selected list box control. |
| **Underline** | Set to True to add the underline style to the listbox text. In effect, this creates a bottom border for each row in the column, giving your listbox a spreadsheet or cell-like appearance.The FORMAT string includes the underscore character, immediately preceding the header text, as in "_~My Header~." |

**General**

| **DefaultColumnTip** | Used to designate default text to be used for the selected column's tool tip.Adds a "Q" to the FORMAT string. |
| **Icon** | Select an icon setting from the available drop list: |
| //None// | Select this to display no icons in the column. |
| //Normal// | Select this to create an area to the left of the data in the column for displaying a normal image (.ICO) that you supply. See //Control Templates--BrowseBox Control //in the //Template Guide// for information on specifying BrowseBox icons, and see //Prop:IconList// in the //Language Reference//.Adds an "I" to the FORMAT string. |
| //Transparent// | Select this to create an area to the left of the data in the column for displaying a transparent image (.ICO) that you supply. See //Control Templates--BrowseBox Control //in the //Template Guide// for information on specifying BrowseBox icons, and see //Prop:IconList// in the //Language Reference//.Adds a "J" to the FORMAT string. |

**Header**

| **Indent** | Optionally specify an indent, in dialog units, for the heading text. Indent moves the data by the number of dialog units specified, in the opposite direction to the justification. An indent of two (2) on left justification improves listbox readability.This appears within the FORMAT string following the header, as in "~My Header~L(8)." |
| **Justification** | Choose from the drop-down list to specify left, right, center or decimal header justification.This appears within the FORMAT string following the header, as in "~My Header~L." |
| **ScrollBar** | Type a non-zero value to specify a horizontal scroll bar for this column only. If the overall listbox already has a scroll bar, the column scroll bar appears above the listbox scroll bar. The value specifies, in dialog units, how far the column scrolls.For example, if your //data// is fifty (50) characters, and your listbox //column// width is about forty (40) characters (one hundred sixty (160) //dialog units//), you should specify a value** **of fifty (50). Fifty (50) additional dialog units are enough to display the ten characters that extend beyond the width of the listbox column.The scroll bar and size appear in the FORMAT string together, as in "S(4)." |
| **Text** | Optionally specify header text for the column. The header appears as a gray row above the listbox data items. To specify no header, leave this field blank. If any field included in the listbox has a header, a header appears across the entire listbox; fields with no header text have a blank header.The heading appears within the FORMAT string enclosed in tilde (~) characters, as in "~My Header~." |
| **Width** | Specify the width in dialog units for the column data. By default, the Formatter sets the value to four times the number of characters specified in the field picture in the data dictionary. For variables, the default is four times the number of characters in the picture token defined for it.{{tipbox.jpg|TipBox.jpg}}As a rough guide, allow four dialog units for an average character. For example, if you want a column 10 characters wide, type 40 in the Width field.After you've placed a field, you can drag the column separators in the Sample Listbox to resize the column width. The cursor changes when you place it on top of the separator, to indicate you can resize it.The data width you set appears within the FORMAT string for the field, preceding the Justification code, as in "40L." |

**Tree**

| **OneBasedTree** | Set to True to allow the root level to collapse, that is, all the items in the tree can collapse to a single line. |
| **ShowBoxes** | Set to True to add expand (+) and contract (-) boxes to the tree diagram.Set to Falser to append "(B)" to the "T" in the FORMAT string, resulting in "T(B)" to suppress boxes.Adds a "(1)" to the "T" in the FORMAT string, resulting in "T(1)." |
| **ShowLevel** | Set to True to cause each descending level of the Tree hierarchy to be indented.Set to False to append "(I)" to the "T" in the FORMAT string, resulting in "T(I)." |
| **ShowLines** | Set to True to add connecting lines between related items in the tree diagram.Set to False to append "(L)" to the "T" in the FORMAT string, resulting in "T(L)" to suppress lines. |
| **ShowRoot** | Set to True to display a root item for the tree diagram.Set to False to append "(R)" to the "T" in the FORMAT string, resulting in "T(R)" to suppress display of a root item. |
| **Tree** | Set to True to display this column in a hierarchical tree diagram. See [[tplcontrolrelationtree.htm|Relation Tree control template]].Adds a "T" to the FORMAT string. |

{{tipbox.jpg|TipBox.jpg}}

It is not necessary to be concerned with the precise syntax of the List Box Format String. Always use the List Box Formatter to build the string for you. If you are using PROP:FORMAT in your embedded source, you can always cut and paste your format string from the Formatter as needed.