Class Fox::FXTreeList
In: rdoc-sources/FXTreeList.rb
Parent: FXScrollArea

A Tree List Widget organizes items in a hierarchical, tree-like fashion. Subtrees can be collapsed or expanded by double-clicking on an item or by clicking on the optional plus button in front of the item. Each item may have a text and optional open-icon as well as a closed-icon. The items may be connected by optional lines to show the hierarchical relationship. When an item‘s selected state changes, the treelist emits a SEL_SELECTED or SEL_DESELECTED message. If an item is opened or closed, a message of type SEL_OPENED or SEL_CLOSED is sent. When the subtree under an item is expanded, a SEL_EXPANDED or SEL_COLLAPSED message is issued. A change of the current item is signified by the SEL_CHANGED message. In addition, the tree list sends SEL_COMMAND messages when the user clicks on an item, and SEL_CLICKED, SEL_DOUBLECLICKED, and SEL_TRIPLECLICKED when the user clicks once, twice, or thrice, respectively. When items are added or removed, the tree list sends messages of the type SEL_INSERTED or SEL_DELETED. In each of these cases, a pointer to the item, if any, is passed in the 3rd argument of the message.

Events

The following messages are sent by FXTreeList to its target:

SEL_KEYPRESS:sent when a key goes down; the message data is an FXEvent instance.
SEL_KEYRELEASE:sent when a key goes up; the message data is an FXEvent instance.
SEL_LEFTBUTTONPRESS:sent when the left mouse button goes down; the message data is an FXEvent instance.
SEL_LEFTBUTTONRELEASE:sent when the left mouse button goes up; the message data is an FXEvent instance.
SEL_RIGHTBUTTONPRESS:sent when the right mouse button goes down; the message data is an FXEvent instance.
SEL_RIGHTBUTTONRELEASE:sent when the right mouse button goes up; the message data is an FXEvent instance.
SEL_COMMAND:sent when a list item is clicked on; the message data is a reference to the item (an FXTreeItem instance).
SEL_CLICKED:sent when the left mouse button is single-clicked in the list; the message data is a reference to the item clicked (an FXTreeItem instance) or nil if no item was clicked.
SEL_DOUBLECLICKED:sent when the left mouse button is double-clicked in the list; the message data is a reference to the item clicked (an FXTreeItem instance) or nil if no item was clicked.
SEL_TRIPLECLICKED:sent when the left mouse button is triple-clicked in the list; the message data is a reference to the item clicked (an FXTreeItem instance) or nil if no item was clicked.
SEL_OPENED:sent when an item is opened; the message data is a reference to the item (an FXTreeItem instance).
SEL_CLOSED:sent when an item is closed; the message data is a reference to the item (an FXTreeItem instance).
SEL_EXPANDED:sent when a sub-tree is expanded; the message data is a reference to the root item for the sub-tree (an FXTreeItem instance).
SEL_COLLAPSED:sent when a sub-tree is collapsed; the message data is a reference to the root item for the sub-tree (an FXTreeItem instance).
SEL_SELECTED:sent when an item is selected; the message data is a reference to the item (an FXTreeItem instance).
SEL_DESELECTED:sent when an item is deselected; the message data is a reference to the item (an FXTreeItem instance).
SEL_CHANGED:sent when the current item changes; the message data is a reference to the current item (an FXTreeItem instance).
SEL_INSERTED:sent after an item is added to the list; the message data is a reference to the item (an FXTreeItem instance).
SEL_DELETED:sent before an item is removed from the list; the message data is a reference to the item (an FXTreeItem instance).

Tree list styles

TREELIST_EXTENDEDSELECT:Extended selection mode allows for drag-selection of ranges of items
TREELIST_SINGLESELECT:Single selection mode allows up to one item to be selected
TREELIST_BROWSESELECT:Browse selection mode enforces one single item to be selected at all times
TREELIST_MULTIPLESELECT:Multiple selection mode is used for selection of individual items
TREELIST_AUTOSELECT:Automatically select under cursor
TREELIST_SHOWS_LINES:Lines shown
TREELIST_SHOWS_BOXES:Boxes to expand shown
TREELIST_ROOT_BOXES:Display root boxes also
TREELIST_NORMAL:same as TREELIST_EXTENDEDLIST

Methods

Attributes

anchorItem  [RW]  Anchor item, if any [FXTreeItem]
currentItem  [RW]  Current item, if any [FXTreeItem]
cursorItem  [R]  Item under the cursor, if any [FXTreeItem]
firstItem  [R]  First root-level item [FXTreeItem]
font  [RW]  Text font [FXFont]
helpText  [RW]  Status line help text for this list [String]
indent  [RW]  Parent-child indent amount, in pixels [Integer]
lastItem  [R]  Last root-level item [FXTreeItem]
lineColor  [RW]  Line color [FXColor]
listStyle  [RW]  List style [Integer]
numItems  [R]  Number of items [Integer]
numVisible  [RW]  Number of visible items [Integer]
selBackColor  [RW]  Selected text background color [FXColor]
selTextColor  [RW]  Selected text color [FXColor]
textColor  [RW]  Normal text color [FXColor]

Public Class methods

Construct a new, initially empty tree list.

Parameters:

p:the parent window for this tree list [FXComposite]
target:the message target, if any, for this tree list [FXObject]
selector:the message identifier for this tree list [Integer]
opts:tree list options [Integer]
x:initial x-position [Integer]
y:initial y-position [Integer]
width:initial width [Integer]
height:initial height [Integer]

Public Instance methods

Append a new (possibly subclassed) item as last child of father. Returns a reference to the newly added item (an FXTreeItem instance). If notify is true, a SEL_INSERTED message is sent to the list‘s message target after the item is added.

Append item with given text and optional icons, and user-data pointer as last child of father. Returns a reference to the newly added item (an FXTreeItem instance). If notify is true, a SEL_INSERTED message is sent to the list‘s message target after the item is added.

Remove all items from the list. If notify is true, a SEL_DELETED message is sent to the list‘s message target before each item is removed.

Set this item‘s state to closed. The primary result of this change is that the item‘s icon will change to its "closed" icon. This is different from the collapseTree method, which actually collapses part of the tree list, making some items invisible. If notify is true, a SEL_CLOSED message is sent to the list‘s message target after the item is closed.

Collapse sub-tree rooted at tree. If notify is true, a SEL_COLLAPSED message is sent to the list‘s message target after the sub-tree is collapsed.

Deselect item. If notify is true, a SEL_DESELECTED message is sent to the list‘s message target after the item is deselected.

Disable item

Enable item

Expand sub-tree rooted at tree. If notify is true, a SEL_EXPANDED message is sent to the list‘s message target after the sub-tree is expanded.

Extend selection from anchor item to item. If notify is true, a series of SEL_SELECTED and SEL_DESELECTED messages may be sent to the list‘s message target, indicating the changes.

Extract item from list and return a reference to the item. If notify is true and the extraction causes the list‘s current item to change, a SEL_CHANGED message is sent to the list‘s message target before the item is extracted from the list.

Fill tree list by appending items from array of strings and return the number of items added. If notify is true, a SEL_INSERTED message is sent to the list‘s message target after each item is added.

Search items by text, beginning from item start (an FXTreeItem instance). If the start item is nil, the search will start at the first, top-most item in the list. Flags may be SEARCH_FORWARD or SEARCH_BACKWARD to control the search direction; this can be combined with SEARCH_NOWRAP or SEARCH_WRAP to control whether the search wraps at the start or end of the list. The option SEARCH_IGNORECASE causes a case-insensitive match. Finally, passing SEARCH_PREFIX causes searching for a prefix of the item name. Return nil if no matching item is found.

Search items by associated user data, beginning from item start (an FXTreeItem instance). If the start item is nil the search will start at the first, top-most item in the list. Flags may be SEARCH_FORWARD or SEARCH_BACKWARD to control the search direction; this can be combined with SEARCH_NOWRAP or SEARCH_WRAP to control whether the search wraps at the start or end of the list. Return nil if no matching item is found.

Return a reference to the tree item at (x, y), if any.

Return item‘s closed icon

Return item‘s user data

Return item height

Return item‘s open icon

Return item‘s text

Return item width

Return item hit code: 0 outside, 1 icon, 2 text, 3 box

Insert item with given text and optional icons, and user-data pointer under father before other item. Returns a reference to the newly added item (an FXTreeItem instance). If notify is true, a SEL_INSERTED message is sent to the list‘s message target after the item is added.

Insert a new (possibly subclassed) item under father before other item Returns a reference to the newly added item (an FXTreeItem instance). If notify is true, a SEL_INSERTED message is sent to the list‘s message target after the item is added.

Return true if item is current

Return true if item is enabled

Return true if item expanded

Return true if item is a leaf-item, i.e. has no children

Return true if item opened

Return true if item is selected

Return true if item is visible

Deselect all items. If notify is true, SEL_DESELECTED messages will be sent to the list‘s message target indicating the affected items.

Scroll the list to make item visible

Move item under father before other item and return a reference to item.

Set this item‘s state to opened. The primary result of this change is that the item‘s icon will change to its "open" icon. This is different from the expandTree method, which actually collapses part of the tree list, making some items invisible. If notify is true, a SEL_OPENED message is sent to the list‘s message target after the item is opened.

Prepend a new (possibly subclassed) item as first child of father. Returns a reference to the newly added item (an FXTreeItem instance). If notify is true, a SEL_INSERTED message is sent to the list‘s message target after the item is added.

Prepend item with given text and optional icons, and user-data pointer as first child of father. Returns a reference to the newly added item (an FXTreeItem instance). If notify is true, a SEL_INSERTED message is sent to the list‘s message target after the item is added.

Remove item. If notify is true, a SEL_DELETED message is sent to the list‘s message target before the item is removed.

Remove items in range [fromItem, toItem] inclusively. If notify is true, a SEL_DELETED message is sent to the list‘s message target before each item is removed.

Select item. If notify is true, a SEL_SELECTED message is sent to the list‘s message target after the item is selected.

Change current item. If there is already a current item, that item is first closed. After item is set as the tree list‘s current item, it is opened and selected. If notify is true, a SEL_CHANGED message is sent to the list‘s message target after the current item changes.

Change item‘s closed icon, deleting the old icon if it‘s owned

Change item‘s user data

Change item‘s open icon, deleting the old icon if it‘s owned

Change item‘s text

Sort children of item

Sort all items recursively.

Sort root items.

Toggle item selection. If notify is true, a SEL_SELECTED or SEL_DESELECTED message is sent to the list‘s message target to indicate the change.

Repaint item

[Validate]