%bv - Branch View

Purpose

Syntax

winio@('%bv[options]',width,height,items,num_items,sel )
winio@('%`bv[options]',width,height,items,num_items,sel,bmp_str )
character(*) items(num_items ) (input/output)
integer num_items          (input parameter)
integer sel           (input/output)
integer width,height        (input)
CHARACTER(*) bmp_str        (input)

Modifiers

Grave accent (`) - used to provide a list of bitmaps.

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

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

Description

%bv (branch view) provides a tree view that is similar in some respects to %tv (Tree Control) but the %bv control has a different appearance and %bv has more options. It also shares common features with %lv (List View).

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

num_items is an integer constant giving the number of nodes in the tree. Nodes with blank data are not displayed in the control. This means that the number of nodes that are displayed can be changed under program control.

items is an array of num_items character strings, each string describing a node in turn (see the example below).

sel is an integer that provides the index of the node that is currently selected.

If a grave accent is provided, bmp_str is a character string giving a list of 16x16 bitmap resources in the form 'bmp1,bmp2'. If a bitmap has a one-pixel border of a certain colour, then this colour is used as a mask for the bitmap. Pixels with the mask colour are replaced by the background colour. The default mask is white.

%bv 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. The background colour for %bv is white and at the moment this cannot be changed.

Example

CHARACTER*80 items(4)
INTEGER sel
items(1)='AEBBook'
items(2)='BCAChapter 1'
items(3)='CCASection 1.1'
items(4)='CCASection 1.2'
sel=1
i=winio@('%`bv',200,200,items,4,sel,'bmp1,bmp2')

As for %tv, the first character in each string provides the index for the level of the node. The second character marks the node as either expanded (E) or collapsed (C). The third character is only required if a list of bitmaps is provided and gives the index to select a bitmap from the list.

Options

edit_labels	Allows the text for a node to be edited.
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.
has_lines	The tree is displayed with nodes joined by lines.
lines_at_root	The root node also has a line to its left. Use this with has_buttons if you need buttons at the first level.
has_buttons	+/- expansion buttons are displayed.
paired_bitmaps	'Expanded'/'collapsed' bitmaps are paired in the list.
sort	Sorts all levels of the tree into dictionary order.
use_icons	Forces the use of icons rather than bitmaps.
4bits	Icons have 16 colours. The default is 256 colours (8-bit colour).
24bits	24-bit colour icons.
mouse_click	Adds the CALLBACK_REASON callled "MOUSE_CLICK" for a single mouse click.

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 node by the call clearwin_info@('ROW_NUMBER'). If the call-back function returns the value 4 then editing of this node 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'). If the call-back function returns the value 4 then the new label is rejected the original label is restored. Otherwise, unlike %lv (List View), the edit is accepted and your data is automatically updated. You cannot delete a node by accepting a blank entry.

Expanding a node

When a node is expanded or collapsed, the call-back function is called with the reason 'ITEM_EXPANDED'. You can respond to this (as for %tv (Tree Control)) by changing the bitmap index and calling window_update@(items). However, it is simpler and much faster if you use the option paired_bitmaps. If you provide this option, each 'expanded' bitmap must follow immediately after the corresponding 'collapsed' bitmap in the list. Also the bitmap change is automatically done for you and your data is automatically modified to reflect the change. You can save and restore the data if you want to reload the control with the same expanded state.

Call-back reasons

ITEM_EXPANDED	A node has been expanded or collapsed (see above).
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 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 node has been selected. clearwin_info@('ROW_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@('KEYBOARD_KEY') provides the key code.
MOUSE_CLICK	The user has single-clicked using the left mouse button (requires the option [mouse_click]).

Example

See Branch-view.

%bv - Branch View

Fortran Links

News