%ls - List Box (or Combo Box)


To insert a list box or combo box.


character*n items(num_items)     (input)
integer num_items     (input parameter)
integer cur_item      (input/output)
integer grey_ctrl     (input)


Grave accent (`) - used to provide a drop-down combo box (for editable lists see %el).

Caret (^) - call-back function is called when the user selects an item.

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.


n and m are optional (m cannot be specified without n). n represents the width of the list-box in characters and m the depth. n and m can be replaced by asterisks (*) in which case the values of n and m must be supplied as the first two arguments in the argument list.

num_items is the number of items in the list.

cur_item is the item number that is selected in the range zero to num_items both on input and output. Zero signifies that no item is selected.

items is an array of text entries, one for each item. Blank entries at the end of the list are not displayed. This means that you can use blank entries to create a list that can be changed dynamically.

If the grave accent is used and a call-back is supplied, option can be set to the [extended]. The result is that the call-back is called when the list drops down or closes up. These events must be detected from the call-back by calling CLEARWIN_STRING@('CALLBACK_REASON') which returns 'DROPDOWN' or 'CLOSEUP'.

For a list box (i.e. when a grave accent modifier is not used), the option [hscrollbar] provides a horizontal scroll bar whilst the option [multicolumn] provides a multiple column output (see List box format).

If a grave accent is used (%`ls) and the parent window uses %sy (Dialog Style)[3d_thin] then %ls can be given the option [no_border] to reduce the thickness of the border.

The option [limit_height] takes an additional double precision argument (before any callback function). This argument takes a value that should be less than one. The maximum height of the control will be limited to this proportion of the screen height.

The option [height=n] sets the pixel height of individual items to 'n' pixels. The default value is 16. An asterisk can be used and the value passed in the argument list. For example to set the height to 24 you could write:
winio@('%12.4LS[height=24]',items,7,currentItem) or

An alternative to %ls[height=v] described is [vertical_fill=v]. [height=n] is limited by not being sensitive to the current font. The alternative [vertical_fill=v] uses a double precision value v and makes the depth of an item equal to (1.0+v)*ht where ht is the pixel height of the current font. The same option can also be used with %ms (Multi-select Box) and %el (Editable Combo Box).

The option [no_box] removes the rectangular box that surrounds the control.

The option [hover] highlights items as the mouse cursor moves over them.

If the grave accent modifier is not used, %ls can be preceded by a pivot %pv (Pivot).

grey_ctrl is 1 (enabled) or 0 (disable/greyed). Any call-back function must be placed after this control variable.


The %ls control is limited to a total of 32768 characters. The maximum number of characters for each item is 512.


character*10 names(4)
winio@('%^`ls', names, 4L, sel, cb_func)

See also

%el (Editable Combo Box), %ms (Multi-select Box), %lv (List View), %pb (Parameter Box), %ps (Property Sheet Container)




Copyright © 1999-2024 Silverfrost Limited