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. Note that this object is NOT plug-in
compatible with the Microsoft TreeView object for Windows CE. In addition
to "standard" treeview functionality, this control also supports a
"context menu", displayed when the control is tapped while pressing the
Alt key.


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



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


*** hWnd
	Retrieve the window handle of the displayed object.

	lWindow = Tree.hWnd


*** 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



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 if
	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 if
	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 it's
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
