Panel: list

Syntax

{<name>:} list {<strings>}

Description

List sub-panel. A list of text options from which one or more may be selected. The list is made scrollable when necessary.

Membership

• Panel window

• Tab window

Parameters

• <name>
  A name to be given to the sub-panel for reference purposes.

• <strings>
  The text (labels) to appear in the list.

Switches

• -bc=<color>
  The background color for the list box. If omitted, the background color of the parent window is used.

• -c=<num>
  The width of the list box list in characters. If omitted, the pixel width indicated by the -w switch is used, or a suitable default.

• -d=<num>
  The default option to be initially highlighted in the list. If omitted, no options are initially highlighted.

• -dim=<screen_xy>
  Define the dimensions of the list box in pixels. This is usually redundant because list boxes are by default created sized-to-fit, but is useful when the size needs to be overridden. This is a two-element numeric array providing width and height. If only one is required, the other can be set to -1 and will be ignored.

• -eb
  Extend the height of the list box to the bottom of its parent row or column.

• -er
  Extend the width of the list box to the right of its parent row or column.

• -fo=<font>
  The font to be used for text in the list box. This must be a fixed font. If omitted the list box inherits the font of its parent row or column.

• -g=<num>
  The spacing between options in pixels. The default is 0.

• -gh
  The list box should be initially ghosted, i.e. insensitive to user-interaction.

• -inv
  Make the sub-panel invisible on creation.

• -j=<just>
  The justification of the list box within its parent row or column. Within a parent row the value should be one of L, M, R. Within a parent column the value should be one of T, M or B. The default in both cases is M.

• -link=<text>
  The resize linkage for the panel. This ties panel edges to one or more edges of the parent window, with the result that when the parent window gets resized, the panel gets automatically resized as well. <text> is a combination of the characters L, R, T, B and M. A value of "LRTB" means that the left, right, top and bottom edges of a sub-panel are linked to its parent. The default value is "TL", which links the left and top edges to the parent window but does no resizing because its right and bottom edges are not linked. Note that the linkage is to edges of the parent window, not to column/row extremities. More complicated linkage requirements should be done via the window.resize callback on the parent window.

• -mul
  Multiple options may be selected. The default behavior is for one option only to be selected at any time.

• -pj=<just>
  The position justification of the sub-panel within the panel window. This combined with the -x and -y switches can be used to position the sub-panel by one of its corners. The default is ’TL’. It also defines the control point to be used when repositioning the sub-panel after creation.

• -r=<num>
  The visible height of the list in rows. The default is the number of options in <strings>, or 5 if there are no options, or 20 if there are more than 20.

• -t=<strings>
  User-defined strings which can be used as values corresponding to options. There should be as many elements in <strings> as there options. The default values are the list labels.

• -tc=<color>
  The color for text in the list box. If omitted the parent window "other color" is used.

• -w=<num>
  The width of the list box in pixels. If omitted, a suitable default is used.

• -x=<num>
  The x position of the list box relative to the top-left corner of its parent row or column. If omitted, the list box is placed adjacent to the previously defined sub-panel.

• -y=<num>
  The y position of the list box relative to the top-left corner of its parent row or column. If omitted, the list box is placed below the previously defined sub-panel.

Callbacks

Called when an option is selected with a single click of mouse button 1.

<panel>.drag(<window>,<panel>)

panel.drag {
    args w=window, p=panel
}

Called when an option is selected with a double click of mouse button 1.

<panel>.exec(<window>,<panel>)

panel.exec {
    args w=window, p=panel
}

Notes

For multiple selection list boxes, a combination of mouse button and Control key will toggle the selection of an option. A combination of mouse button and Shift key will select a range of options and deselect all others. A mouse button with no keys will just select an option and deselect all others.

Search facilities are available by typing unique sequences corresponding to the beginning of an option label, e.g. "zeb" will select the first option found beginning "zeb". The <Escape> key will reset the search sequence.

Examples

Create a panel window containing an empty list of 10 rows with a white background.

window w = wpanel {
    lst: list -r=10,-bc=white
}

Create a panel window containing a list with several options and an initial value.

window w = wpanel {
   lst: list <'Roads','Drainage','Services'>,-r=4,-d=2
}

Create a panel window containing a multiple selection list. The list is filled after creation.

window w = wpanel {
    lst: list -w=150,-bc=white,-tc=blue,-r=10,-mul
}
# Get all .dat files into the list
dir *.dat,-os=w.lst.label