VtDrawnList


Create a DrawnList widget

Syntax

VtDrawnList object_name [options]

Description

Creates a DrawnList widget. Returns the widget name.

Options

-autoSelect Boolean (CS)
In character mode, combining this option with -selection BROWSE (which is the default) will automatically select each item as the user navigates up and down the list.

This option has no effect in graphical mode.

-callback cmd (C)
Specifies that the callback cmd is called when you select items in the list (using <Space>, <Enter>, or a single mouse click).

Additional callback keys

itemPosition
the position of the selected item

-columns integer (CS)
In the graphical environment, this specifies that the width of the DrawnList is integer * AverageWidth pixels wide, where AverageWidth is the average width of a character in the current font set. Use the -columnWidth option with VtSetAppValues if the maximum character width of the font is needed instead. In character mode, this option makes the DrawnList integer columns wide.

-defaultCallback cmd (C)
Specifies that the callback cmd is called when the user double-clicks or presses <Enter> on an item in the DrawnList.

Additional callback keys

itemPosition
the position of the selected item

value
the position of the selected item

-fieldList list (C)
Specifies a row of data for the DrawnList. Default formatting is used unless an alternative format is supplied using the -formatList option.

For example:

VtDrawnList $main.list \
       -iconList {apple.px orange.px banana.px} \
       -formatList {{ICON 2} {STRING 20} {STRING 15}}  \
       -fieldList  [list 1 "Orange" "Fruit"]

There are a number of pre-defined connection icons available for use with the -fieldList option.

-formatList list (CS)
Describes the format of the columns used in the DrawnList. This field contains a list of column descriptions. Each column description in turn is a list containing the column's type, width, and left and right margins. The syntax is:
{ type width [left_margin, right_margin] }

The left_margin and right_margin parameters are optional. The following specifies a column that is of type ICON, with a width of 1 icon width and a left_margin and right_margin of 5 pixels.

{ ICON 1 5 5 }

Valid types are ICON, STRING, and DATA. DATA does not display on the screen; it is used to store item-specific data.

For example:

-formatList { {ICON 3} {STRING 20 5} {DATA} }

The first column is an icon field with a width of 3, the second column contains a string with a width of 20 and a left margin of 5, and the third column contains hidden data.

-horizontalScrollBar boolean (CS)
Specifies whether or not a horizontal scroll bar is drawn. Set boolean to TRUE if you want a horizontal scroll bar, and FALSE otherwise. The default value is FALSE.

-iconList pixmap_filename_list (C)
Specifies a list of pixmap filenames to use in the DrawnList on graphical systems. On character systems, specify characters to display instead of pixmap filenames. Where both systems may be in use, options specific to character displays should be prefixed with CHARM_, while those specific to graphical systems should be prefixed with MOTIF_. For example:
-CHARM_iconList {a b c}
-MOTIF_iconList {a.px b.px c.px}

In this example, graphical systems load the pixmaps a.px, b.px, and c.px. Character systems load no pixmaps, but display instead the letters a, b, and c.

-labelFormatList list (CS)
Similar to -formatList but applies to the label. Note that type ICON may be used as a format identifier but currently icons are not supported in DrawnList labels.

-labelList list (CS)
Specifies the label above the DrawnList. (Similar to -fieldList, except that it applies to the label). The format used in -labelFormatList is used. Note that currently icons are not supported in DrawnList labels.

-recordList list_of_lists (C)
Specifies one or more rows of data for the DrawnList. For example:
{ { 0 1 "Apple" "Fruit"} 
  { 1 1 "Kumquat" "Fruit"} 
  { 1 3 "Leek" "Vegetable"}
}

There are a number of pre-defined connection icons available for use with the -recordList option.

-rows integer (CSG)
Specifies the number of rows visible in the DrawnList.

-selection SINGLE | MULTIPLE (CS) (Graphical mode)
-selection SINGLE | BROWSE | MULTIPLE | EXTENDED (CS) (Character mode)
The selection options are as follows:

For graphical mode:

SINGLE
This method is used by default. A single item is always selected. It is possible to select a different item, but not to deselect every item.

MULTIPLE
An item is always selected. It is possible to select more than one item, but not to deselect every item.

For character mode:

BROWSE
This method is used by default. An item in the list is always selected. It is not possible to deselect every item.

SINGLE
Simple select and deselect is permitted. Only one item can be selected at a time.

MULTIPLE
Any number of items can be selected or deselected by navigating down to the item and pressing <Space>. This is the preferred option to use in character mode for multiple selections.

EXTENDED
Similar to MULTIPLE selection, except that there must be at least one selection.

If -selection BROWSE is specified, then in graphical mode the policy SINGLE will be used. If -selection EXTENDED is specified, then in graphical mode the policy MULTIPLE will be used. This can be overridden by explicitly setting CHARM_selection and MOTIF_selection.

-topItemPosition integer (CSG)
Specifies that the item at position integer should be displayed at the top of the DrawnList.

Connection icons

When specifying an icon index in -fieldList or -recordList the following indexes can be used to reference connection icons or no icons:

For example:

VtDrawnListAddItem $main \
     -formatList {{ICON 4} {STRING 20}} \
     -recordList {{ CONNECT_H  0          NO_ICON   NO_ICON  "Apple"  } \
                  { NO_ICON    CONNECT_T  1         NO_ICON  "Orange" } \
                  { NO_ICON    CONNECT_T  2         NO_ICON  "Kumquat"} \
                  { NO_ICON    CONNECT_T  0         NO_ICON  "Banana" } \
                  { NO_ICON    CONNECT_I  CONNECT_L 0        "Grape"  } \
                  { NO_ICON    CONNECT_L  0         NO_ICON  "Pear"   }} 

This code produces the following:

Example

The following code produces a DrawnList containing 3 labelled icons.

set app [VtOpen "VtDrawnList Demo"]
set form [VtForm $app.form]

set list [VtDrawnList $form.list 
	-rows 3 \
	-columns 25 \
	-formatList {{ICON 1} {STRING 20}} 
	-iconList { \
		orange.px \
		apple.px \
		pear.px} \
        -recordList { \
		{0 " Orange"} \
		{1 " Apple"} \
		{2 " Pear" }}]

VtShowDialog $app.form
VtMainLoop

This code produces the following:

See also: