%lv - List View

Purpose

To include a list view control.

Syntax

winio@('%lv[options]',width,height,items,num_items,sel,view)
winio@('%`lv[options]',width,height,items,num_items,sel,
view,icon_str)
character(*) items(num_items)   (input/output)
integer num_items               (input parameter)
integer sel(num_items-1)        (input/output)
integer width,height,view       (input)
character(*) icon_str           (input)

Modifiers

Grave accent (`) - used to provide a list of icons or an integer array of check box states.

Caret (^) - call-back function is provided.

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

Description

A list view control is a window that displays a collection of items, each item consisting of an optional icon and a label. List view controls provide several ways of arranging items and displaying individual items. For example, additional information about each item can be displayed in columns to the right of the icon and label. This arrangement is called a report view. Microsoft Explorer uses a list view control in order to display directory information.

width and height provide the dimensions of the control in pixels.

num_items is an integer constant giving the number of rows in the report view + 1 (for the header). Blank rows are not displayed in the control. This means that the number of rows that are displayed can be changed under program control. The first blank row terminates the input.

items is an array of num_items character strings the first describing the column headers and widths, then one string describing each row in turn (see the example below).

sel is an integer array whose elements are set to 1 if the item is selected otherwise to zero.

view is an integer variable in the range 0..3 that represents the type of view. 0=Icon view; 1=Report view; 2=Small icon view; 3=List view. These are available even when no icons are provided.

If a grave accent is provided, icon_str is a character string giving a list of icon resources in the form 'icon1,icon2'.

%lv can take a pivot (%pv (Pivot)). Also the right mouse button can be used to trigger a popup menu (%pm (Popup Menu)) defined in the parent window.

Example

Here we have 3 rows with 2 columns. items(1) provides data for the column headings and widths. The first character defines the separator between the data for each column. In this example, the first column has the caption "Header". A trailing underscore followed by an integer provides the pixel width of the column. If this is omitted then the length of the text defines the width (a plus sign placed before the integer makes the heading centred whilst a minus sign makes it right justified). In this example the second column header is blank and the second column width is 50 pixels. The number of characters (80 in this case) must be sufficient to allow ClearWin+ to add the column width to each heading (4 characters per column).

items(2) provides data for the first row of a report. Again the first character defines the separator. The second character defines the icon as an index (A,B,C...) into the list of icons 'icon1,icon2' (when a grave accent is used). Next comes the label and then the data for column two etc..

Options

	single_selection	Allows only one item at a time to be selected. By default Shift and Control keys can generate multiple selections.
	edit_labels	Allows item text to be edited (first column in report view).
	no_column_headers	Column headers are not displayed in report view (items(1) is still needed for column widths)
	show_selection_always	Always show the selection, if any, even if the control does not have the focus.
	no_border	Displays the control without a border.
	no_label_wrap	Displays the item label on a single line in an icon view.
	align_top	Items are top-aligned in icon and small icon view.
	align_left	Items are left-aligned in icon and small icon view.
	edit_cells	Allows all columns in the report view to be edited (see below).
	user_font	Use the current (%fn (Font)) font rather than the default.
	grid_lines	Displays grid lines when edit_cells is not used.
	full_row_select	Selects a full row in a report view rather than just the item in the first column.
	check_boxes	Replaces icons in a report view with check boxes. Use a grave accent and an integer array of state values instead of an icon string.
	go_down_on_return	Used with edit_cells in a report view with the result that pressing the return key (when editing a cell) moves down the column.
	4bit	Icons have 16 colours. The default is 256 colours (8-bit colour).
	24bit	24-bit colour icons.

Label editing
edit_labels enables label editing and requires a call-back function that can test for the call-back reasons 'BEGIN_EDIT','END_EDIT' and 'EDIT_KEY_DOWN'.

With BEGIN_EDIT you can get the index of the selected item by the call CLEARWIN_INFO@('ROW_NUMBER'). If your call-back function returns the value 4 then editing of this item is prevented.

With EDIT_KEY_DOWN you can validate each character as it is typed. Use CLEARWIN_INFO@('KEYBOARD_KEY') to get the key and/or CLEARWIN_STRING@('EDITED_TEXT') to get the resulting string with the character inserted. If the call-back function returns the value 4 then the character is not accepted. If you want to translate the input key to another key then the call-back function must return the ASCII character code (31<code<256) of the translated key.

With END_EDIT you can get the result of the edit by the call CLEARWIN_STRING@('EDITED_TEXT'). Having validated the label, you should then get the index using CLEARWIN_INFO@('ROW_NUMBER') and reconstruct the relevant row of the items array by adding an icon identifier and extra column data as required (otherwise the original data will be restored). Creating a blank row in response to a label edit is not recommended.

Selecting a view
It is possible to create a menu item or a toolbar button that changes the view state (Icon view, Report view, Small icon view, List view). Here is some sample code for the associated call-back function.

INTEGER FUNCTION change_view()
INTEGER view
COMMON view
view=view-1
IF(view < 0) view=3
CALL window_update@(view)
change_view=2
END

Column widths
If the last column does not extend to the right of the control then ClearWin+ will adjust the width of this column so that it fills the area.

If a column width is changed at run time then ClearWin+ stores the new width in row 1 of the data. This means that the adjusted widths will be used when the control is redrawn. If you want to use the same widths when the program is re-used then you will need to save and restore the modified data.

Cell editing
The option edit_cells is effective in a report view where it over-rides edit_labels. By using edit_cells you can edit the data in any column. A grid is displayed resulting in a spreadsheet appearance. The call-back function can be used to prevent the editing of any given cell and to validate each input character and as well as the final result. For this purpose edit_cells uses the call-back reasons BEGIN_EDIT, EDIT_KEY_DOWN and END_EDIT etc. as in edit_labels. The only difference is that unlike edit_lables, edit_cells initially responds to a single mouse click.

CLEARWIN_INFO@('ROW_NUMBER') and CLEARWIN_INFO@('COLUMN_NUMBER') identify the cell that is being edited.

When editing cells, use the arrow keys to move vertically and CTRL with arrow keys to move horizontally. This movement will step over any cells that are disabled. The selection array (with one element for each row) contains the row number of the current selection. However, when validating input it is simpler to use CLEARWIN_INFO@('COLUMN_NUMBER').

Call-back reasons

	BEGIN_DRAG	An item is being dragged.
	BEGIN_EDIT	A label is about to be edited (see above).
	DROP_TARGET	As an item is dragged across the control different items become the target of the drag. CLEARWIN_INFO@('ROW_NUMBER') identifies the new target. This will change as the mouse moves.
	EDIT_KEY_DOWN	The user has pressed a keyboard key during a label or cell edit. CLEARWIN_INFO@('KEYBOARD_KEY') provides the key code (see above).
	END_DRAG	An item has been dragged.
	END_EDIT	A label has been edited (see above).
	SET_SELECTION	A item has been selected. CLEARWIN_INFO@('ROW_NUMBER') provides the index.
	COLUMN_CLICK	The user has clicked on a column header. CLEARWIN_INFO@('COLUMN_NUMBER') provides the index.
	MOUSE_DOUBLE_CLICK	The user has double-clicked using the left mouse button. CLEARWIN_INFO@('ROW_NUMBER') provides the index.
	KEY_DOWN	The user has pressed a keyboard key. CLEARWIN_INFO@('KEYBORAD_KEY') provides the key code.
	CHECKBOX_CHANGE	The user has clicked on a check box. CLEARWIN_INFO@('ROW_NUMBER') provides the index and CLEARWIN_INFO@('LISTBOX_ITEM_SELECTED') provides the state.

In response to a column click you might choose to sort the items using the given column index. Having reconstructed the data, you should then make a call to WINDOW_UPDATE@(items) in order to view the new order.

%lv - List View

Fortran Links

News