back to gui 

wxTreeCtrl

generated from ../src/mod_gui/control/treectrl.cpp

A tree control presents information as a hierarchy, with items that may be expanded to show further items. Items in a tree control are referenced by wxTreeItemId handles.

Constants

Styles

Name Description
NO_BUTTONS
HAS_BUTTONS
TWIST_BUTTONS
NO_LINES
LINES_AT_ROOT
MAC_BUTTONS
AQUA_BUTTONS
SINGLE
MULTIPLE
EXTENDED
FULL_ROW_HIGHLIGHT
EDIT_LABELS
ROW_LINES
HIDE_ROOT
HAS_VARIABLE_ROW_HEIGHT
DEFAULT_STYLE

wxTreeItemIcon

Name Description
Normal Not selected, Not expanded
Selected Selected, Not expanded
Expanded Not selected, Expanded
SelectedExpanded Selected, Expanded

wxTreeItemIcon is used to associated different kind of images to a treectrl item. wxTreeItemIcon contains the following constants: See wxTreeCtrl and wxTreeItem.

Constructor

wxTreeCtrl

wxTreeCtrl()
 
wxTreeCtrl(Parent, 
           Id, 
           Position = wxDefaultPosition, 
           Size = wxDefaultSize, 
           Style = wxTreeCtrl.ICON, 
           Validator)
Name Type Default Description
Parent wxWindow The parent of wxTreeCtrl.
Id Integer An window identifier. Use -1 when you don't need it.
Position wxPoint wxDefaultPosition The position of the TreeCtrl control on the given parent.
Size wxSize wxDefaultSize The size of the TreeCtrl control.
Style Integer wxTreeCtrl.ICON The wxTreeCtrl style.
Validator wxValidator Validator.

Constructs a new wxTreeCtrl object.

Properties

Name Type Description
count read only Integer Get the total number of items in the control.
firstVisibleItem wxTreeItemId Gets the first visible item.
imageList wxImageList Get/Set the normal image list.
indent Integer Get/Set the indent. Indent is the number of pixels the children are indented relative to the parents position. Setting indent also redraws the control immediately.
onCompareItems Function Set this to a function when you want to change the sort order of the items in the tree control. The function should return a negative, zero or positive value if the first item is less than, equal to or greater than the second one. The function gets two wxTreeItemId objects as arguments. When not set, the items are sorted alphabetically.
rootItem read only wxTreeItemId Gets the root item.
selection read only wxTreeItemId Gets the selection. Use selections when the tree can have more then one selected item (MULTIPLE style).
selections read only Array Gets all selected items (An array with wxTreeItemId objects).
stateImageList wxImageList Get/Set the state image list.

Methods

addRoot

addRoot(Text, 
        Image = -1, 
        SelectedImage = -1, 
        Data = null) : wxTreeItemId
Name Type Default Description
Text String The text for the root item.
Image Integer -1 Index of the image for normal items. The default is -1 which means don't use.
SelectedImage Integer -1 Index of the image for selected items. The default is -1 which means don't use.
Data Any null

Adds the root node to the tree, returning the id of the new item. The Image and SelectedImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. If Image > -1 and SelectedImage is -1, the same image is used for both selected and unselected items.

The following example adds a root item and 3 childs to the root. 


     var dlg = new wxDialog(null, -1, "Tree example");
     dlg.tree = new wxTreeCtrl(dlg, 1);

     var root = dlg.tree.addRoot("Root");
     dlg.tree.appendItem(root, "Child 1");
     dlg.tree.appendItem(root, "Child 2");
     dlg.tree.appendItem(root, "Child 3");

appendItem

appendItem(Parent, 
           Text, 
           Image = -1, 
           SelectedImage = -1, 
           Data = null) : wxTreeItemId
Name Type Default Description
Parent wxTreeItemId The id of the parent item.
Text String The text for the root item.
Image Integer -1 Index of the image for normal items. The default is -1 which means don't use.
SelectedImage Integer -1 Index of the image for selected items. The default is -1 which means don't use.
Data Any null

Appends an item to the end of the branch identified by parent, return a new item id. The Image and SelectedImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. If Image > -1 and SelectedImage is -1, the same image is used for both selected and unselected items.

collapse

collapse(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Collapses the item. See wxTreeItem expanded property

collapseAndReset

collapseAndReset(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Collapses the item and removes the children.

deleteAllItems

deleteAllItems()

Deletes all items. You don't get an onDeleteItem event for the deleted items.

deleteChildren

deleteChildren(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Deletes all the children of the item. You don't get an event as onDeleteItem event for the deleted items.

deleteItem

deleteItem(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Deletes the item. You receive an event as onDeleteItem.

editLabel

editLabel(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Start editing the label of the item. The item will be selected when it hadn't been before.

endEditLabel

endEditLabel(Id, 
             Discard = false)
Name Type Default Description
Id wxTreeItemId The id of the item
Discard Boolean false Accept (false) or discard(true) the changes to the item label. Default is false.

Ends editing the label of the item. Only on Windows

ensureVisible

ensureVisible(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Make sure the item is visible (expanding the parent item and/or scrolling to this item if necessary) See wxTreeItem visible property

expand

expand(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Expands the item. See wxTreeItem expanded property

getChildrenCount

getChildrenCount(Id, 
                 Recurse = true) : Integer
Name Type Default Description
Id wxTreeItemId The id of the item
Recurse Boolean true If Recurse is true (the default), returns the total number of descendants, otherwise only one level of children is counted

Returns the number of childrens of the item. See wxTreeItem bold property

getFirstChild

getFirstChild(Id, 
              Cookie) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item
Cookie Integer For this enumeration function you must pass in a 'cookie' parameter which is opaque for the application but is necessary for the library to make these functions reentrant (i.e. allow more than one enumeration on one and the same object simultaneously). The cookie passed to getFirstChild and getNextChild should be the same variable.

Returns the first child item. An invalid item is returned when there is no child item. See wxTreeItem getFirstChild method

getItem

getItem(Id) : wxTreeItem
Name Type Default Description
Id wxTreeItemId The id of the item

Creates a wxTreeItem from the given wxTreeItemId. wxTreeItem can be used to alter the item without always passing the id to the tree control. null is returned when the id is not valid.

This method does not exist in wxWidgets.

getItemBackgroundColour

getItemBackgroundColour(Id) : wxColour
Name Type Default Description
Id wxTreeItemId The id of the item

Gets the background colour of the item. See wxTreeItem backgroundColour property

getItemData

getItemData(Id) : Any
Name Type Default Description
Id wxTreeItemId The id of the item

Gets the associated object or value of the item. The item data can be any possible JavaScript type. See wxTreeItem data property, setItemData

getItemFont

getItemFont(Id) : wxFont
Name Type Default Description
Id wxTreeItemId The id of the item

Gets the font of the item. See wxTreeItem font property

getItemImage

getItemImage(Id, 
             Which) : Integer
Name Type Default Description
Id wxTreeItemId The id of the item
Which Integer A wxTreeItemIcon constant.

Gets the specified item image. See wxTreeItem getImage method

getItemParent

getItemParent(Id) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item

Returns the parent of the item. See wxTreeItem parent property

getItemText

getItemText(Id) : String
Name Type Default Description
Id wxTreeItemId The id of the item

Gets the text of the given item. See also wxTreeItem text property

getItemTextColour

getItemTextColour(Id) : wxColour
Name Type Default Description
Id wxTreeItemId The id of the item

Gets the text colour of the item. See wxTreeItem textColour property

getNextChild

getNextChild(Id, 
             Cookie) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item
Cookie Integer For this enumeration function you must pass in a 'cookie' parameter which is opaque for the application but is necessary for the library to make these functions reentrant (i.e. allow more than one enumeration on one and the same object simultaneously). The cookie passed to getNextChild and getNextChild should be the same variable.

Returns the next child item. An invalid item is returned when there is no child item. See wxTreeItem getNextChild method

getNextSibling

getNextSibling(Id) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item

Returns the next sibling item. An invalid item is returned when there is no child item. See wxTreeItem nextSibling property

getNextVisible

getNextVisible(Id) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item

Returns the next visible item. The item itself must also be visible. See wxTreeItem nextSibling property

getPrevSibling

getPrevSibling(Id) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item

Returns the previous sibling item. An invalid item is returned when there is no child item. See wxTreeItem prevSibling property

getPrevVisible

getPrevVisible(Id) : wxTreeItemId
Name Type Default Description
Id wxTreeItemId The id of the item

Returns the previous visible item.

hitTest

hitTest(Pos) : Array
Name Type Default Description
Pos wxPoint The position to test.

Determines which item (if any) is at the specified point. Returns an array with the wxTreeItemId and flags (or you can use a multi assign).

insertItem

insertItem(Parent, 
           Prev, 
           Text, 
           Image = -1, 
           SelectedImage = -1) : wxTreeItemId
Name Type Default Description
Parent wxTreeItemId The id of the parent item.
Prev wxTreeItemId The id of the item to use as previous sibling.
Text String The text for the root item.
Image Integer -1 Index of the image for normal items. The default is -1 which means don't use.
SelectedImage Integer -1 Index of the image for selected items. The default is -1 which means don't use. 
insertItem(Parent, 
           Pos, 
           Text, 
           Image = -1, 
           SelectedImage = -1) : wxTreeItemId
Name Type Default Description
Parent wxTreeItemId The id of the parent item.
Pos Integer The position of the item to use as previous sibling.
Text String The text for the root item.
Image Integer -1 Index of the image for normal items. The default is -1 which means don't use.
SelectedImage Integer -1 Index of the image for selected items. The default is -1 which means don't use.

Inserts an item after a given one (Prev) or before one identified by its position (Pos). The Image and SelectedImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. If Image > -1 and SelectedImage is -1, the same image is used for both selected and unselected items.

isBold

isBold(Id) : Boolean
Name Type Default Description
Id wxTreeItemId The id of the item

Returns true when the item text is in bold. See wxTreeItem bold property

isExpanded

isExpanded(Id) : Boolean
Name Type Default Description
Id wxTreeItemId The id of the item

Returns true when the item is expanded. See wxTreeItem expanded property

isSelected

isSelected(Id) : Boolean
Name Type Default Description
Id wxTreeItemId The id of the item

Returns true when the item is selected. See wxTreeItem selected property

isVisible

isVisible(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Returns true when the item is visible. See wxTreeItem visible property

prependItem

prependItem(Parent, 
            Text, 
            Image = -1, 
            SelectedImage = -1, 
            Data = null) : wxTreeItemId
Name Type Default Description
Parent wxTreeItemId The id of the parent item.
Text String The text for the root item.
Image Integer -1 Index of the image for normal items. The default is -1 which means don't use.
SelectedImage Integer -1 Index of the image for selected items. The default is -1 which means don't use.
Data Any null

Inserts a new item as the first child of the parent item, returns a new item id. The Image and SelectedImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. If Image > -1 and SelectedImage is -1, the same image is used for both selected and unselected items.

scrollTo

scrollTo(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Scroll to the item (but don't expand its parent)

selectItem

selectItem(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Selects the given item. See wxTreeItem selected property

setItemBackgroundColour

setItemBackgroundColour(Id, 
                        Colour)
Name Type Default Description
Id wxTreeItemId The id of the item
Colour wxColour The new colour.

Sets a new background colour for this item. The example sets the backgroundcolour of the root item to red. tree.setItemBackgroundColour(tree.rootItem, wxRED); See wxTreeItem backgroundColour property

setItemBold

setItemBold(Id, 
            Bold = true)
Name Type Default Description
Id wxTreeItemId The id of the item
Bold Boolean true

Makes item appear in bold font if bold parameter is true or resets it to the normal state. See wxTreeItem bold property

setItemData

setItemData(Id, 
            Data)
Name Type Default Description
Id wxTreeItemId The id of the item
Data Any The data to associate with this item.

Sets the associated data for the given item. You can use any type: Integer, Object, Boolean, ...

The following example shows that you can use an object as item data. 


    dlg = new wxDialog(null, -1, "Tree example");
    dlg.tree = new wxTreeCtrl(dlg, 1);

    var root = dlg.tree.addRoot("Root");
    var id = dlg.tree.appendItem(root, "Child 1");

    dlg.tree.setItemData(id, new Date());
    id = dlg.tree.appendItem(root, "Child 2");
    dlg.tree.setItemData(id, new Date());
    id = dlg.tree.appendItem(root, "Child 3");
    dlg.tree.setItemData(id, new Date());
See wxTreeItem data property, getItemData

setItemDropHighlight

setItemDropHighlight(Id, 
                     Highlight = true)
Name Type Default Description
Id wxTreeItemId The id of the item
Highlight Boolean true

The item will be shown with a drop highlight or not.

setItemFont

setItemFont(Id, 
            Font)
Name Type Default Description
Id wxTreeItemId The id of the item
Font wxFont The new font.

Sets a new font for this item. See wxTreeItem font property.

setItemHasChildren

setItemHasChildren(Id, 
                   Children = true)
Name Type Default Description
Id wxTreeItemId The id of the item
Children Boolean true

Force appearance of the button next to the item. This is useful to allow the user to expand the items which don't have any children now, but instead adding them only when needed, thus minimizing memory usage and loading time. See wxTreeItem hasChildren property

setItemImage

setItemImage(Id, 
             Image, 
             Which)
Name Type Default Description
Id wxTreeItemId The id of the item
Image Integer The new image for the item.
Which Integer A wxTreeItemIcon constant.

Sets the image for the given item. See wxTreeItem setImage method

setItemText

setItemText(Id, 
            Text)
Name Type Default Description
Id wxTreeItemId The id of the item
Text String The new text for the item.

Sets the text of the given item. The example changes the text of the root. tree.setItemText(tree.rootItem, "root"); See wxTreeItem text property

setItemTextColour

setItemTextColour(Id, 
                  Colour)
Name Type Default Description
Id wxTreeItemId The id of the item
Colour wxColour The new colour.

Sets a new text colour for this item. The example sets red as the text colour of the root item. tree.setItemTextColour(tree.rootItem, wxRED); See wxTreeItem textColour property

sortChildren

sortChildren(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Sorts the children of the given item using the function of onCompareItems. When no function is set, the items are sorted alphabetically.

toggle

toggle(Id)
Name Type Default Description
Id wxTreeItemId The id of the item

Toggles the given item between collapsed and expanded states. See wxTreeItem expanded property

unselect

unselect()

Unselects the selected item. See wxTreeItem selected property

unselectAll

unselectAll()

Unselects all selected items.

Events

onBeginDrag This event is triggered when the user starts dragging with the left mouse button. The event can be vetoed using veto or allowed. The function receives a wxTreeEvent as argument.
onBeginRDrag This event is triggered when the user starts dragging with the right mouse button. The event can be vetoed using veto or allowed. The function receives a wxTreeEvent as argument.
onBeginLabelEdit This event is triggered when the user starts editing an item. The event can be vetoed using veto or allowed. The function receives a wxTreeEvent as argument.
onEndLabelEdit This event is triggered when the user ends editing the label. The function receives a wxTreeEvent as argument. The event can be vetoed using veto or allowed.
onDeleteItem This event is triggered when an item is deleted. See deleteItem. The function receives a wxTreeEvent as argument.
onGetInfo This event is triggered when the application needs information. The function receives a wxTreeEvent as argument.
onSetInfo This event is triggered when information is supplied. The function receives a wxTreeEvent as argument.
onItemExpanded This event is triggered when an item is expanded. The function receives a wxTreeEvent as argument.
onItemExpanding This event is triggered when an item is about to expanded. The event can be vetoed using veto or allowed. The function receives a wxTreeEvent as argument.
onItemCollapsed This event is triggered when an item is collapsed. The function receives a wxTreeEvent as argument.
onItemCollapsing This event is triggered when an item is about to collapse. The event can be vetoed using veto or allowed. The function receives a wxTreeEvent as argument.
onSelChanged This event is triggered when the selection is changed. The function receives a wxTreeEvent as argument.
onSelChanging This event is triggered when the selection is about to change. The function receives a wxTreeEvent as argument.
onKeyDown This event is triggered when a key is pressed. The function receives a wxTreeEvent as argument.
onItemActivated This event is triggered when an item is activated. The function receives a wxTreeEvent as argument.
onItemRightClick This event is triggered when an item is clicked with the right mousebutton. The function receives a wxTreeEvent as argument.
onItemMiddleClick This event is triggered when an item is clicked with the middle mousebutton. The function receives a wxTreeEvent as argument.
onEndDrag This event is triggered when the user releases the mouse button. The function receives a wxTreeEvent as argument.



Design downloaded from Zeroweb.org: Free website templates, layouts, and tools.