| **Navigation:**  Window and Report Control Properties >====== List Control Properties ====== | [[line control properties.htm|{{btn_prev_n.gif|Previous page}}]][[coming future.htm|{{btn_home_n.gif|Return to chapter overview}}]][[ole properties.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

The [[list  declare a window list control .htm|Listbox]] control is used to display tabular data. You can create list boxes which look like spreadsheet grids, perform drag-and-drop tasks, and more.

This section only discusses //placing //the listbox. After you place a listbox, you must format it.

See the **[[list  declare a window list control .htm|List Box Formatter]]**// //dialog for more information on formatting and adding additional functionality to your list boxes.

{{notebox.jpg|NoteBox.jpg}}

The Property View presents you with two ways to view a control's properties.

At the top of the Property View, press the categorized button {{categorized.jpg|categorized.jpg}} to view a control's properties by category (the deafult).

Or press the alphabetical button {{alphabetical.jpg|alphabetical.jpg}} to view a control's properties in alphabetical order.

This help documents displays the properties in the categorical view.

**Color**

Enter a valid color equate in the **TextColor**, **Background**, **SelForeGround**, **SelBackground**, or **GridColor** fields, or press the ellipsis (...) button to select a color from the **Color** dialog. The **Window Designer** adds the [[color  set color .htm|COLOR]] attribute to your control declaration.

See ..\LIBSRC\EQUATES.CLW for a list of valid color equates. See //Windows Design Issues// in the //User's Guide// for a discussion on using color to enhance your application.

**Design**

Design settings control visual elements you see in the Window Designer. These settings should not affect the window display at runtime.

| **Locked** | "Freezes" the control so that subsequent data dictionary changes are not applied. You can override the #Freeze attribute for all controls or for individual controls. See **[[application options dialog.htm|Application Options]]**. |
| **Tab Index** | Determines the index in the TAB order that this control will follow. The first tab in the order is index zero (0).To change the **TabIndex** property //immediately// while in the Designer, use the **Show tab order** interface (i.e. on the right-click menu).If you set the **TabIndex** property using the property page, the z-order is not updated until you save and exit the Window Designer. |
| **UseVisualStyles** | Set to TRUE to display this control in a Visual Style appearance (as if the XP manifest was active) |

**Extra**

| **Column** | Set this property to TRUE if you wish to allow the user to highlight a multi-column list box field by field (rather than one row at a time). This provides for spreadsheet grid style movement of the highlight bar. **See Also:** the [[column  set list box highlight bar .htm|COLUMN]] attribute. |
| **DragID** | To specify the type of Drag operations this control will generate, type up to 16 //signatures//, separated by commas. The **[[dragid  set drag and drop host signatures .htm|DRAGID]]** attribute specifies the LIST control can serve as a drag-and-drop host. DRAGID works in conjunction with the **[[dropid  set drag and drop target signatures .htm|DROPID]]** attribute. |
| **DropID** | To specify the type of Drag operations this control will accept, type up to 16 //signatures//, separated by commas. The **Window Designer** adds the **[[dropid  set drag and drop target signatures .htm|DROPID]]** attribute to the control, which indicates the control is a valid target for the drag and drop operations identified by the signatures. |
| **Imm** | To generate a message event each time the end user moves or resizes the selection bar, set **Imm **to TRUE. This adds the [[imm  set immediate event notification .htm|IMM]] attribute to the LIST. You are responsible for the code that executes upon notification of the event. |
| **Mark** | Optionally enables multiple item selection. Type in the label of a QUEUE field in the **[[mark  set multiple selection mode .htm|Mark]] **field if you wish to allow the user to select more than one item from the list. The QUEUE field will flag the selected items. |
| **VCR** | Optionally provide [[vcr  set vcr control .htm|VCR]] controls. Set **VCR **property to TRUE to provide VCR style controls for the list box. Optionally type the field equate label of an entry field to the right of the check box. When the user presses the //Locator //( ? ) button, the focus shifts to that field. The user may type in data, then press TAB to scroll the list box to the closest matching entry. |

**General**

| **Drop** | Specifies whether this should be a regular or drop-down list box. |
| **Count** | Place a zero in the **Count **property for a normal list box. To create a drop-down list box, type the number of drop-down elements you wish to be visible. |
| **Width** | When the Drop field is non-zero, specify an integer constant here that sets the width of the dropped list, in dialog units. |
| **Format** | Specifies the print or display format of the data in the list control. Press the ellipsis button to call the **Format Editor**. |
| **From** | Fill the **From **field with the origin of the list data. Generally, this is the label of a [[queue  declare a memory queue structure .htm|QUEUE]] structure. |
| **Justification** | Specify left, center, right, decimal, or default justification. Default justification matches that specified in the data dictionary, if applicable. If you use decimal justification, you set the Offset to allow display of digits to the right of the decimal point. |
| **Offset** | Specify an indentation value for the list box item text, in dialog units. |
| **Layout** | Indicates the orientation of the LIST control. **Left to Right** maintains the original layout specified in the Window Designer. **Right to Left** essentially "flips" the controls' display as a mirror image of the layout specified in the Window Designer. Default field navigation moves from right to left. The setting in the Application Frame will cascade its setting to all child windows and controls that have the **default** setting active. |
| **NoBar** | Specifies the selection bar appears only when the list box has focus. **See Also:** the [[nobar  set no highlight bar .htm|NOBAR]] attribute. |
| **TextFont** | Calls the **[[select font dialog.htm|Select Font]]** dialog which lets you select the font (typeface), size, style (such as bold or italic), color, and font effects (underline and strikeout) for the selected control or window. As you choose options, the dialog box displays a sample of the selected font. |
| **Use** | This defines the [[use  set field equate label or control update variable .htm|USE]] attribute for the control. Place a variable or field equate label in the **Use **field. You may specify the variable which will receive the value that the user selects. Or, a field equate label to reference the list box in program statements. |

**Help**

| **Alert** | Press the ellipsis to open a dialog that lets you add the [[alrt  set window  hot  keys .htm|ALRT]] attribute to a window or control. When the attribute is set, the window generates an EVENT:AlertKey if the user presses the key(s) you specify in this dialog, while the window has the focus. |
| **Cursor** | The //Cursor// field (the [[cursor  set mouse cursor type .htm|CURSOR]] attribute) lets you specify an alternate shape for the cursor when the user passes the cursor over the control. The drop-down list provides standard cursor choices such as I-Beam and Crosshair. To select an external cursor file (whose extension must be .CUR), choose **Select File **from the drop-down list, then pick the file using the standard file dialog. |
| **Help ID** | The **Help ID **field (the [[hlp  set on line help identifier .htm|HLP]] attribute) takes a string constant specifying the key for accessing a specific topic in the Help document. This may be either a Help keyword or a context string.A Help keyword is a word or phrase indexed so that the user may search for it in the //Help //**Search **dialog. When you fill in the HLP attribute for a button, if the entry box has focus, when the user presses F1, the help file opens to the referenced topic. If more than one topic matches a keyword, the search dialog appears.When referencing a context string in the **Help ID****// //**field, you must identify it with a leading tilde (~). |
| **Key** | Press the desired key or key combination (for example, CTRL+H). The keys you pressed will appear in the **Key** field, and will be supplied as parameters to the KEY or ALRT attribute for this control. The ESC, ENTER, and TAB keys //cannot// be specified by pressing them. For these keys, press the ellipsis (...) button and type "esc," "enter," or "tab." |
| **Message** | The **Message** field (the [[msg  set status bar message .htm|MSG]] attribute) lets you specify text to display in the first zone of the status bar when the control has focus. |
| **Tip** | The **[[tip  set  balloon help  text .htm|TIP]]** attribute on a control specifies the text to display in a "balloon help" box when the mouse cursor pauses over the control. Although there is no specific limit on the number of characters, the //string// should not be longer than can be displayed on the screen. |

**Mode**

| **Disable** | Disables or 'grays-out' the control when your program initially displays it. The **Window Designer** places the [[disable  set control dimmed at open .htm|DISABLE]] attribute on the control. Use the [[enable  re activate dimmed control .htm|ENABLE]] statement to allow the user access to the control. |
| **Hide** | Makes the control invisible at the time Windows would initially display it. Windows actually creates the control--it just doesn't display it on screen. The **Window Designer** places the [[hide  set control hidden .htm|HIDE]] attribute on the control. Use the [[unhide  show hidden control .htm|UNHIDE]] statement to display the control. |
| **Scroll** | Specifies whether the control should move with the window when the user scrolls the window. By default (False) the control does not move with the window. Set the **Scroll **property to False to create a control that stays fixed when the user scrolls the window. The **Window Designer** places the [[scroll  set scrolling control .htm|SCROLL]] attribute on the control when checked. |
| **Skip** | Instructs the **Window Designer** to omit the control from the Tab Order. When the user TABS from field to field in the dialog box, Windows will not give the control focus. This is useful for seldom-used data fields. The **Window Designer** will place the [[skip  set tab key skip or conditional print control .htm|SKIP]] attribute on the control. |
| **Transparent** | Specify whether you wish the control background to be **Transparent**. This instructs Windows to suppress the rectangular region around the text--the background. Normally, Windows will paint this the same uniform color as the window below the control. This adds the [[trn  set transparent control .htm|TRN]] attribute. |

**Options:**

| **Flat** | Set this property to True to give your list box a "flat" appearance (the list box control is on the same level as the window, and not recessed). Due to a built-in attribute to the runtime library, list boxes used in Drop List and Drop Combo controls are always flat and cannot be modified in the Formatter. |

**Position**

Lets you set the location and size of the control.

The **Position **property lets you specify the [[at  set position and size .htm|AT]] attribute. Filling in the attribute manually is optional--you may also set the position and size visually by dragging with the mouse in the **Window Designer**.

To set the location of the control's** Top Left Corner**, set an **X** (horizontal) and **Y** (vertical) coordinate in [[what is a dialog unit.htm|Dialog units]]. The coordinate is relative to the top left corner of the structure containing it, that is, the window or the report band.

To set the control's size, choose from the following options for **Width** and **Height**.

| **Default** | The Clarion runtime library determines the size of the control based on the applicable font and picture token. |
| **Full** | The control is the full height or width of the window or report. |
| **Fixed** | Lets you set a precise width or height in [[what is a dialog unit.htm|Dialog units]] on a window, or in thousandths of inch, points, or millimeters on a report. |

**Scrollbars**

| **Horizontal** | To add a horizontal scroll bar to your list box, set the **Horizontal **property to TRUE. |
| **Vertical** | To add a vertical scroll bar, set the **Vertical **property to TRUE. |

Scroll bars only appear when the list of items in the list is bigger than the window. These options add the [[hscroll  vscroll  hvscroll  set scroll bars .htm|HSCROLL, VSCROLL, and HVSCROLL]] attributes to the control.

**Quick Links**

|  |  |
| **Embeds** | Accesses the **[[gen72.htm|Embedded Source]]** dialog for points surrounding the event handling for this control only. |