| **Navigation:**  [[introduction.htm|Language Reference]] > 8 - Controls > Control Declarations >====== LIST (declare a window list control) ====== | [[line  declare a line control .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[menu  declare a menu box .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

| **   LIST **,**AT( ) [,FROM(** **)]** [,**CURSOR( )**] [,**USE( )**] [,**DISABLE**] [,**KEY( )**] [,**MSG( )**] [,**HLP( )**] [,**SKIP**] |

|  | [,**FONT( )**] [,**FORMAT( )**] [,**DROP**] [,**COLUMN**] [,**VCR**] [,**FULL**] [,**SCROLL**] [,**NOBAR**] [,**FLAT**] |||
|  | [,**ALRT( )**] [,**HIDE**] [,**DRAGID( )**] [,**DROPID( )**] [,**TIP( )**] [,**GRID( )**] [,**TRN**] [,**COLOR( )**] [,**LAYOUT( )**] |||
|  | [,| **MARK( )**| ] | [,| **HSCROLL**| ] | [,| **LEFT**| ] |
|  | | **IMM**| | | **VSCROLL**| | | **RIGHT**| |
|  |  | | **HVSCROLL**| | | **CENTER**| |
|  |  |  | | **DECIMAL**| |

{{blk2blue.jpg|blk2blue.jpg}}

| **LIST** | Places a scrolling list of data items on the WINDOW, TOOLBAR, or REPORT. |
| **AT** | Specifies the initial size and location of the control (PROP:AT). If omitted, the runtime library chooses a value. |
| **FROM** | Specifies the origin of the data displayed in the list (PROP:FROM). |
| **CURSOR** | Specifies a mouse cursor to display when the mouse is positioned over the control (PROP:CURSOR). If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used. Not valid in a REPORT. |
| **USE** | A field equate label to reference the control in executable code, or the label of the variable that receives the value selected by the user (PROP:USE). |
| **DISABLE** | Specifies the control appears dimmed when the WINDOW or APPLICATION opens (PROP:DISABLE). |
| **KEY** | Specifies an integer constant or keycode equate that immediately gives focus to the control (PROP:KEY). Not valid in a REPORT. |
| **MSG** | Specifies a string constant containing the text to display in the status bar when the control has focus (PROP:MSG). Not valid in a REPORT. |
| **HLP** | Specifies a string constant containing the help system identifier for the control (PROP:HLP). Not valid in a REPORT. |
| **SKIP** | Specifies the control does not receive input focus and may only be accessed with the mouse or accelerator key (PROP:SKIP). Not valid in a REPORT. |
| **FONT** | Specifies the display font for the control (PROP:FONT). |
| **FORMAT** | Specifies the display format of the data in the list (PROP:FORMAT). This can include icons, colors, and tree controls. |
| **DROP** | Specifies a drop-down list box and the number of elements the drop-down portion contains (PROP:DROP). Not valid in a REPORT. |
| **COLUMN** | Specifies cell-by-cell highlighting on multi-column lists (PROP:COLUMN). Not valid in a REPORT. |
| **VCR** | Specifies a VCR-type control to the left of any horizontal scroll bar (PROP:VCR). Not valid in a REPORT. |
| **FULL** | Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter (PROP:FULL). Not valid in a REPORT. |
| **SCROLL** | Specifies the control scrolls with the window (PROP:SCROLL). Not valid in a REPORT. |
| **NOBAR** | Specifies the highlight bar is displayed only when the LIST has focus (PROP:NOBAR). Not valid in a REPORT. |
| **FLAT** | Specifies that the control does not have a 3D border drawn around it (PROP:FLAT). |
| **ALRT** | Specifies "hot" keys active for the control (PROP:ALRT). Not valid in a REPORT. |
| **HIDE** | Specifies the control does not appear when the WINDOW or APPLICATION opens (PROP:HIDE). UNHIDE must be used to display it. |
| **DRAGID** | Specifies the control may serve as a drag host for drag-and-drop actions (PROP:DRAGID). Not valid in a REPORT. |
| **DROPID** | Specifies the control may serve as a drop target for drag-and-drop actions (PROP:DROPID). Not valid in a REPORT. |
| **TIP** | Specifies the text that displays as "balloon help" when the mouse cursor pauses over the control (PROP:ToolTip). Not valid in a REPORT. |
| **GRID** | Specifies the color of the grid lines between columns in the list (PROP:GRID). |
| **TRN** | Specifies the control transparently displays over the background (PROP:TRN). |
| **COLOR** | Specifies background and selected colors for the control (PROP:COLOR). |
| **LAYOUT** | Specifies the control's left-to-right or right-to-left display orientation (PROP:LAYOUT) |
| **MARK** | Specifies multiple items selection mode (PROP:MARK). Not valid in a REPORT. |
| **IMM** | Specifies generation of an event whenever the user presses any key (PROP:IMM). Not valid in a REPORT. |
| **HSCROLL** | Specifies that a horizontal scroll bar is automatically added to the list box when any portion of the data item lies horizontally outside the visible area (PROP:HSCROLL). Not valid in a REPORT. |
| **VSCROLL** | Specifies that a vertical scroll bar is automatically added to the list box when any data items lie vertically outside the visible area (PROP:VSCROLL). Not valid in a REPORT. |
| **HVSCROLL** | Specifies that both vertical and horizontal scroll bars are automatically added to the list box when any portion of the data items lies outside the visible area. Not valid in a REPORT. |
| **LEFT** | Specifies that the data is left justified within the LIST (PROP:LEFT). |
| **RIGHT** | Specifies that the data is right justified within the LIST (PROP:RIGHT). |
| **CENTER** | Specifies that the data is centered within the LIST (PROP:CENTER). |
| **DECIMAL** | Specifies that the data is aligned on the decimal point within the LIST (PROP:DECIMAL). |

The **LIST** control places a scrolling list of data items on the WINDOW, TOOLBAR, or REPORT at the position and size specified by its AT attribute. It is valid in Clarion Win32 Windows, and also for REPORT structures in both Clarion Win32 and Clarion#. The data items displayed in the LIST come from a QUEUE or STRING specified by the FROM attribute and are formatted by the parameters specified in the FORMAT attribute (which can include colors, icons, and tree control parameters).

The CHOICE procedure returns the QUEUE entry number (the value returned by POINTER(queue)) of the selected item when the EVENT:Accepted event has been generated by the LIST. The data displayed in the LIST is automatically refreshed every time through the ACCEPT loop, whether the AUTO attribute is present or not.

A LIST with the DROP attribute displays only the currently selected data item on screen until the control has focus and the user presses the down arrow key, or CLICKS ON the the icon to the right of the displayed data item. When either of these occurs, the selection list appears ("drops down") to allow the user to select an item.

A LIST with the IMM attribute generates an event every time the user moves the highlight bar to another selection, or presses any key (all keys are implicitly ALRTed). This allows an opportunity for the source code to re-fill the display QUEUE, or get the currently highlighted record to display other fields from the record. If VSCROLL is also present, the vertical scroll bar is always displayed and when the end-user CLICKS on the scroll bar, events are generated but the list does not move (executable code should perform this action). You can interrogate the [[prop vscrollpos.htm|PROP:VscrollPos]] property to determine the scroll thumb's position from 0 (top) to 255 (bottom).

A LIST with the VCR attribute has scroll control buttons like a **V**ideo **C**assette **R**ecorder to the left of the horizontal scroll bar (if there is one). These buttons allow the user to use the mouse to scroll through the list.

A LIST with the DRAGID attribute can serve as a drag-and-drop host, providing information to be moved or copied to another control. A LIST with the DROPID attribute can serve as a drag-and-drop target, receiving information from another control. These attributes work together to specify drag-and-drop "signatures" that define a valid target for the operation. The DRAGID() and DROPID() procedures, along with the SETDROPID procedure, are used to perform the data exchange.

**REPORT Usage**

{{black.jpg|black.jpg}}

LIST is valid only in a DETAIL structure. Its purpose is to allow the report format to duplicate the screen appearance of the LIST's FORMAT setting. When the first instance of the DETAIL structure containing the LIST prints, any headers in the FORMAT attribute print along with the current FROM attribute entry. When the last DETAIL structure containing the LIST prints, the LIST footers print along with the current FROM attribute entry.

**Events Generated:**

| EVENT:Selected | The control has received input focus. |
| EVENT:Accepted | The user has selected an entry from the control. |
| EVENT:NewSelection | The current selection in the list has changed (the highlight bar has moved up or down). |
| EVENT:ScrollUp | The user pressed the up arrow (only with the IMM attribute). |
| EVENT:ScrollDown | The user pressed the down arrow (only with the IMM attribute). |
| EVENT:PageUp | The user pressed PGUP (only with the IMM attribute). |
| EVENT:PageDown | The user pressed PGDN (only with the IMM attribute). |
| EVENT:ScrollTop | The user pressed CTRL+PGUP (only with IMM attribute). |
| EVENT:ScrollBottom | The user pressed CTRL+PGDN (only with IMM attribute). |
| EVENT:Locate | The user pressed the locator VCR button (only with the IMM attribute). |
| EVENT:ScrollDrag | The user moved the scroll bar's "thumb" and its new position is in PROP:VScrollPos (only with the IMM attribute). |
| EVENT:ScrollTrack | The user is moving the scroll bar's "thumb" and its new position is in PROP:VScrollPos (only with the IMM attribute). |
| EVENT:PreAlertKey | The user pressed a printable character (only with the IMM attribute) or an ALRT attribute hot key. |
| EVENT:AlertKey | The user pressed a printable character (only with the IMM attribute) or an ALRT attribute hot key. |
| EVENT:Dragging | The mouse cursor is over a potential drag target (only with the DRAGID attribute). |
| EVENT:Drag | The mouse cursor has been released over a drag target (only with the DRAGID attribute). |
| EVENT:Drop | The mouse cursor has been released over a drag target (only with the DROPID attribute). |
| EVENT:DroppingDown | The user has requested the droplist drop down (only with the DROP attribute). CYCLE aborts the dropdown. |
| EVENT:DroppedDown | The user has dropped the droplist (only with the DROP attribute). |
| EVENT:Expanding | The user has clicked on a tree expansion box (only with the T in the FORMAT attribute string). CYCLE aborts the expansion. |
| EVENT:Expanded | The user has clicked on a tree expansion box (only with the T in the FORMAT attribute string). |
| EVENT:Contracting | The user has clicked on a tree contraction box (only with the T in the FORMAT attribute string). CYCLE aborts the contraction. |
| EVENT:Contracted | The user has clicked on a tree contraction box (only with the T in the FORMAT attribute string). |
| EVENT:ColumnResize | A column in the list has been resized. |

**Example:**

<code>
Q    QUEUE
F1    STRING(1)
F2    STRING(4)
    END 
 
MDIChild WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL
         LIST,AT(0,0,20,20),USE(?L1),FROM(Que),IMM
         LIST,AT(20,0,20,20),USE(?L2),FROM(Que),KEY(F10Key)
         LIST,AT(40,0,20,20),USE(?L3),FROM(Que),MSG('Button 3')
         LIST,AT(60,0,20,20),USE(?L4),FROM(Que),HLP('Check4Help')
         LIST,AT(80,0,20,20),USE(?L5),FROM(Q),FORMAT('5C~List~15L~Box~'),COLUMN
         LIST,AT(100,0,20,20),USE(?L6),FROM(Que),FONT('Arial',12)
         LIST,AT(120,0,20,20),USE(?L7),FROM(Que),DROP(6)
         LIST,AT(140,0,20,20),USE(?L8),FROM(Que),HVSCROLL,VCR
         LIST,AT(180,0,20,20),USE(?L10),FROM(Que),CURSOR(CURSOR:Wait)
         LIST,AT(200,0,20,20),USE(?L11),FROM(Que),ALRT(F10Key)
         LIST,AT(220,0,20,20),USE(?L12),FROM(Que),LEFT
         LIST,AT(240,0,20,20),USE(?L13),FROM(Que),RIGHT
         LIST,AT(260,0,20,20),USE(?L14),FROM(Que),CENTER
         LIST,AT(280,0,20,20),USE(?L15),FROM(Que),VSCROLL,VCR
         LIST,AT(300,0,20,20),USE(?L16),FROM('Apples|Peaches|Pumpkin|Pie')
         LIST,AT(320,0,20,20),USE(?L17),FROM('TBA')
        END
 
 
CustRpt   REPORT,AT(1000,1000,6500,9000),THOUS
CustDetail DETAIL,AT(0,0,6500,1000)
           LIST,AT(80,0,20,20),USE(?L1),FROM(Q),FORMAT('5C~List~15L~Box~') 
          END
         END
   CODE
   OPEN(MDIChild)
    ?L1{PROP:From} = 'Live|Long|And|Prosper'   !Runtime FROM attribute assignment
</code>

**See Also:**

[[combo  declare an entry list control .htm|COMBO]]

[[dragid  set drag and drop host signatures .htm|DRAGID]]

[[dropid  set drag and drop target signatures .htm|DROPID]]

[[setdropid  set dropid return string .htm|SETDROPID]]

[[format   runtime properties.htm|FORMAT]] (Runtime Properties)

[[format   style properties.htm|FORMAT]] (Style Properties)

[[format   other list box properties.htm|FORMAT]] (Other Properties)

[[format   list box mouse click properties.htm|FORMAT]] (Mouse Click Properties)

[[from  set listbox data source .htm|FROM]] (LIST data sources)

[[proplist properties index.htm|PROPLIST]] (list of all properties available to be set at runtime)