The Big Red Toolbox

MGCETreeView

A enhanced TreeView Control

September 21, 1999

© NSB Corporation. All rights reserved.
MGCETreeView - TreeView Object for Windows CE
Written by Mark Gamber, September 1999

NS Basic is (c) NS Basic Corporation
Windows CE is (c) Microsoft Corporation

MGCETreeView provides a TreeView control to programs which use controls of this type, such as NS Basic. In addition to "standard" treeview functionality, this control also supports a "context menu", displayed when the control is tapped while pressing the Alt key.Note that this object is NOT plug-in compatible with Microsoft's TreeView ActiveX object for Windows CE.

A word about the mysterious "item":

The word "item" is used quite a bit when describing the following properties, methods and events provided by this control. In reality, an "item" is simply a 32 bit numeric value, but it is NOT something you can add or subtract to or from another item, nor is it something that will be of any use to anything but the treeview control since it's a treeview node identifier. When adding a new item to the tree, there is no reference already there, so use zero as the parent or insertion point of the first item. The item returned will be a valid item which may then be used to add more items after or within that initial item. As a reference, the Microsoft Treeview control maintains items in the treeview using the "node" object. MGCETreeView maintains the items in the same manner, but reduces the complexity by removing the "node" item.

Object Creation

AddObject "MGCETreeView.TreeView", "Tree", 10, 10, 400, 160

Samples

Properties

AllowEdit Set AllowEdit to TRUE (non-zero) to allow the user to edit items in the treeview directly by tapping a selected item. FALSE (zero) prevents the user from directly changing an item. The default value is FALSE.

Tree.AllowEdit = TRUE
iCanEdit = Tree.AllowEdit
AllowEvent The treeview control supports several events, many of which may be allowed or denied at the time they occur through this write-only property. When set to TRUE (non-zero), an event is allowed to occur. For example, a user may expand a tree or edit an item. When set to FALSE, the event is denied and the action does not occur. The default value for this property is set using the AllowEventAsDefault property.

sub Tree_Expanding( item )
  if Tree.ItemText( item ) = "Can't Open" then
    Tree.AllowEvent = FALSE
  end if
end sub
AllowEventAsDefault This property value is used by the treeview control for events that you do not specifically handle. As an example, if you do not want the user to do anything unless you specifically allow them to do so, you would set this property to FALSE (zero). The default value is TRUE (non-zero) which allows all events unless specifically told otherwise via the AllowEvent property within an event handler.

i = Tree.AllEventAsDefault
Tree.AllowEventAsDefault = FALSE

AutoExpand When set to TRUE (non-zero), a tree item automatically expands when selected. In addition, any other expanded tree items are closed when the new item is opened. The default value is FALSE.

Tree.AutoExpand = TRUE
iAutoExpand = Tree.AutoExpand
Border TRUE displays a border around the control, FALSE removes the border. The default value is TRUE.

Tree.Border = FALSE
hasBorder = Tree.Border
Child The read-only Child property retrieves the first child of a tree item specified.

child = Tree.Child( item )
Count This read-only property retrieves the number of items in a tree.

iCount = Tree.Count
FirstItem The FirstItem property retrieves the first item in the tree. This is a read-only property.

firstItem = Tree.FirstItem

FirstVisible This retrieves the first visible item in the tree and, if possible, scrolls a specified item so it is the first visible item.

fVisible = Tree.FirstVisible
Tree.FirstVisible = thisItem
FontBold Set this property to TRUE to display text using a bold font, or FALSE to display text using a normal font. The default is FALSE.

Tree.FontBold = TRUE
iIsBold = Tree.FontBold
FontName Set and retrieve the name of the font to use with the control. The default is "Arial".

Tree.FontName = "Courier New"
sFont = Tree.FontName
FontSize Set and retrieve the height of the font to use with the control. The default is 12.

Tree.FontSize = 18
iSize = Tree.FontSize
HasButtons "Buttons" are the "+" and "-" boxes to the left of a tree item that has child items. You may enable these by setting this property to TRUE or remove them by setting the property to FALSE. The default value is TRUE.

Tree.HasButtons = TRUE
iHasButtons = Tree.HasButtons
HasLines The connecting lines between items may be enabled and disabled using this property. TRUE enables the lines, FALSE removes the lines and the default value is TRUE.

Tree.HasLines = FALSE
iLines = Tree.HasLines
Indent Indent specifies the number of pixels tree items are indented per level. The default value is 19.
ItemImage You may specify what image is displayed by a tree item using the ItemImage property. Images must be enabled and loaded.

Tree.ItemImage( item ) = 1
iImage = Tree.ItemImage( item )
ItemSelectedImage Use this property to set and retrieve the image (if any) displayed when a tree item is selected.

Tree.ItemSelectedImage( item ) = firstImage
iSelImage = Tree.ItemSelectedImage( item )
ItemText Set and retrieve text associated with a tree item.

Tree.ItemText( item ) = "Yeeee ha!"
itemTxt =Tree.ItemText( item )
ItemValue Set and retrieve a user defined 32 bit value associated with a tree item. This value is not used by the control itself.

Tree.ItemValue( item ) = 100
iValue = Tree.ItemValue( item )

NextSibling This read-only property retrieves the next item in a tree that is on the same level as a specified item.

nextItem = Tree.NextSibling( item )
NextVisible Read-only property used to retrieve the next visible item in a tree given a specified item.

nextVisible = Tree.NextVisible( item )
Parent Read-only property used to retrieve the parent item of a specified item.

parentItem = Tree.Parent( item )
PreviousSibling Read-only property used to retrieve a previous item on the same level as a specified item.

p = Tree.PreviousSibling( item )
PreviousVisible Use this read-only property to retrieve the previous visible item of a specified item.

pv = Tree.PreviousVisible( item )
RootLines In addition to connecting lines between items, connecting lines between top level (root) items may be enabled and disabled using this property. FALSE removes the connecting lines and TRUE, the default, displays the connecting lines.

Tree.RootLines = FALSE
iRootLines = Tree.RootLines

Select Retrieve or set an item selection state.

Tree.Select = item
iSelectedItem = Tree.Select

SelectionDisplay This property determines how a selected item is displayed when focus is moved away from the treeview control. Set to TRUE (non-zero) to retain selection display when focus is lost or FALSE to lose the selection display. The default value is TRUE.

Tree.SelectionDisplay = FALSE
i = Tree.SelectionDisplay

Style Set and retrieve what style is used when drawing an edge around the control. This is separate from the border which is enabled and disabled using the Border property. Style values are:
  • 0: No edge.
  • 1: "Sunken" edge.
  • 2: "Raised" edge.
Tree.Style = 2
iStyle = Tree.Style
Tabstop When set to TRUE (non-zero), the control is included in a window's tab order. Set to FALSE (zero), the control may not be reached via Tab. The default value is TRUE.

Tree.Tabstop = TRUE
iCanTab = Tree.Tabstop

TreePath This read-only property retrieves the full "path" from a specified item back to the top level item.

sPath = Tree.TreePath( item )
UseImages Set this property to TRUE if you want the treeview control to display images. FALSE removes the images. The default value is TRUE.

iUsesImages = Tree.UseImages
Tree.UseImages = TRUE
UseSelectedImages When set to TRUE, the treeview displays images with selected items. Set to FALSE to disable image display along selected items. The default value is TRUE.

i = Tree.UseSelectedImages
Tree.UseSelectedImages = TRUE

Version Returns the current version number of the control as an integer.

Methods

AddContextItem Add an item to the treeview context menu. The menu will not appear unless there is at least one item. If the string begins with a dash (-), the menu item added is a separator.

Tree.AddContextItem "First Item"

AddImage The treeview control uses images stored in an "image list" which is automatically created along with the control. You may add images to this image list using this method. The first image added to the list is referred to as one (1) and each image afterwards is referred to as 2, 3, 4 and so on. Images should be 16 colors and 16x16 in size.

Tree.AddImage "\smimage.bmp"
AddItem Use the AddItem method to add items to a treeview control. The first optional parameter, Parent, may be omitted if there is no parent (a top level item) and the second optional parameter, InsertAfter, may be zero if nothing is to come before the new item on it's given level within the tree. The return value is the number of the item added. Parameter three is text to display in the item followed by a 32 bit user defined value. The last two parameters determine the image numbers to use with the control and are also optional.

The return value may be used to add new items that appear after the new item or within it as an expandable tree.

newItem = Tree.AddItem( ,, "Top level item" )
Tree.AddItem , newItem, "Comes After first one"
Tree.Additem newItem, 0, "Branches off of the first item"
Clear Remove all items from a treeview by calling this method.

Tree.Clear
ClearContext Remove all items from the treeview context menu.

Tree.ClearContext
CollapseItem You may collapse an expanded tree item by calling this method.

Tree.CollapseItem item
DeleteItem Delete an item from the tree control.

Tree.DeleteItem item
EndEdit When the treeview is in "edit mode" by either a user tapping a selected item or programmatically, the edit mode may be ended by calling this method. A parameter determines if the changes made at that point are denied or allowed. TRUE discards any changes and FALSE allows changes to be made to the control.

Tree.EndEdit TRUE ' Dump any changes
ExpandItem A tree item may be expanded to show items within it by calling this method.

Tree.ExpandItem item
Hide Hide the treeview control.

Tree.Hide
MakeVisible MakeVisible ensures that a specified item is visible by expanding any trees and scrolling the item into view.

Tree.MakeVisible item
RemoveContextItem This removes an item from the treeview context menu and the item identifier passed is the position, starting with one, of the item to remove.

Tree.RemoveContextItem 2
RemoveImage RemoveImage removes an image from the control's image list.

Tree.RemoveImage 2
SetFocus This method gives the control input focus.

Tree.SetFocus
Show Display the tree control.

Tree.Show
StartEdit StartItem programmatically begins the treeview "edit mode" using a specified item. The return value is the window handle of the edit control.

hedit = Tree.StartEdit( item )
ToggleItem If a specified item is collapsed, it is expanded. If it is expanded, then it is collapsed.

Tree.ToggleItem item

Events

Changed When selection is changed from one treeview item to another, this event is fired and passes the item losing selection and the item getting selection. If the AllowEvent property is set to FALSE within the event's handler, the change is denied.

sub Tree_Changed( olditem, newitem )
  if Tree.ItemText( newitem ) = "Don't Select" then Tree.AllowEvents = FALSE
end sub
Changing This event is fired when selection is changing but before it has actually changed. Set the AllowEvent property in this event's handler to prevent the selection change from happening.

sub Tree_Changing( olditem, newitem )
  if Tree.ItemText( newitem ) = "Don't Select" then Tree.AllowEvents = FALSE
end sub
Collapsed When an expanded tree item is collapsed, this event is called and passes the item that was collapsed. Set the AllowEvent property in the event handler to prevent the item from collapsing.

sub Tree_Collapse( item )
  DispLabel.Caption = "Item " & Tree.ItemText( item ) & " collapsed"
end sub
Collapsing This is the same as the Collapsed event except that Collapsing occurs before the item is actually collapsed.

sub Tree_Collapsing( item )
  if Tree.ItemValue( item ) = -1 then
        Tree.AllowEvent = FALSE
  end if
end sub
ContextMenu This event is fired when a context menu selection is made. If the menu is closed without selecting an item, the event does not occur. The first parameter passed is the treeview item identifier where the control was tapped or zero if it was not tapped over an item. The second parameter is the text of the selected menu item.

sub Tree_ContextMenu( item, text )
    if item then
        MsgBox text & " was tapped over " & Tree.ItemText( item )
    else
        MsgBox text & " was tapped over nothing"
    end if
end sub

EndEdit When AllowEdit is enabled, a user may edit a tree item by tapping a selected item. When the user presses Enter, this event is fired, passing the item and new text entered by the user. If AllowEvent is set to FALSE from within the event handler, the change is not allowed and the item reverts back to its original text. If the user cancels the edit, the event is not fired.

sub Tree_EndEdit( item, text )
    if text = "Nope" then Tree.AllowEvent = FALSE
end sub

Expanded This event is fired after a tree item has been expanded. You may prevent the item from staying expanded by setting AllowEvent to FALSE from within this event's handler.

sub Tree_Expanded( item )
    Tree.AllowEvent = FALSE ' Don't let anything expand!
end sub
Expanding Same as the Expanded event except that this event is fired before the item is actually expanded.

sub Tree_Expanding( item )
    Disp.Caption = "Item " & Tree.ItemText( item ) & " expanding"
end sub
Keypress When a key is pressed while the control has input focus, this event is fired and passes the key value. AllowEvent has no effect on this event.

sub Tree_Keypress( key )
    Disp.Caption = "Key " & Chr( key ) & " was pressed"
end sub
StartEdit When the user initiates the changing of an item by tapping a selected item, this event is fired, passing the item about to be placed into edit mode. Set AllowEvent within this event's handler to deny edit mode.

sub Tree_StartEdit( item )
    Tree.AllowEvent = FALSE ' Don't edit anything yet
end sub