%bv - Branch View


To insert a hierarchical tree.


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)


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

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

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


%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.


CHARACTER*80 items(4)
items(2)='BCAChapter 1'
items(3)='CCASection 1.1'
items(4)='CCASection 1.2'

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.



Allows the text for a node to be edited.


Always show the selection, if any, even if the control does not have the focus.


Displays the control without a border.


The tree is displayed with nodes joined by lines.


The root node also has a line to its left. Use this with has_buttons if you need buttons at the first level.


+/- expansion buttons are displayed.


'Expanded'/'collapsed' bitmaps are paired in the list.


Sorts all levels of the tree into dictionary order.


Forces the use of icons rather than bitmaps.


Icons have 16 colours. The default is 256 colours (8-bit colour).


24-bit colour icons.


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


A node has been expanded or collapsed (see above).


An item is being dragged.


A label is about to be edited (see above).


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.


The user has pressed a keyboard key during a label edit. clearwin_info@('KEYBOARD_KEY') provides the key code (see above).


An item has been dragged.


A label has been edited (see above).


A node has been selected. clearwin_info@('ROW_NUMBER') provides the index.


The user has double-clicked using the left mouse button. clearwin_info@('ROW_NUMBER') provides the index.


The user has pressed a keyboard key. clearwin_info@('KEYBOARD_KEY') provides the key code.


The user has single-clicked using the left mouse button (requires the option [mouse_click]).



See Branch-view.

See also

%tv (Tree Control), %ls (List Box (or Combo Box)), %ms (Multi-select Box), %pb (Parameter Box), %ps (Property Sheet Container).




Copyright © 1999-2024 Silverfrost Limited