WkHierarchicalListBoxView

WkHierarchicalListBoxView provides a vertical, hierarchical, single-column list of items with an icon and a label for each item. The items in the list are typically actual application objects, not strings or arrays. The application should only set the root level items in the tree as the items in the widget.

Unlike a normal list box, the objects passed in do not need to be strings. Instead, you supply the widget at initialization time with a message to send to each object in the list box to retrieve its displayable string. This is accomplished by sending the message #attributeName: to the WkHierarchicalListBoxView, with a symbol matching the message you want sent. By default, this message is #printString, so any object will display as it would in an inspector.

Setting up the children for each object is done similarly: at initialization time, you supply the list box with a message to send to each object in the list box to retrieve a collection of its children. This is accomplished by sending the message # itemChildrenAttributeName: to the WkHierarchicalListBoxView, with a symbol matching the message you want sent. If no children method is provided, the list box will not be hierarchical, and will act as a normal list box.

As mentioned above, each object in the list box can have an icon associated with it. As with # attributeName: and # itemChildrenAttributeName:, this is accomplished by supplying an # itemIconAttributeName: to the list box at initialization time. The associated method will then be sent to each object in the list, giving the object the opportunity to pass back an icon (or any other renderable object including nil if no icon should be displayed). If no # itemIconAttributeName: is specified, the list box will not display an icons. An optional different icon may be displayed when the object is expanded via sending # itemIconExpandAttributeName: to the list box.

The hierarchyPolicy determines how the hierarchy is to be shown. This includes what the indentation level should be as well as whether to draw lines connecting the items and whether to show some kind of button beside items which have children. By default the hierarchyPolicy is an instance of EwHierarchyPolicy with lines set to true. The other hierarchy policy class provided is EwIconHierarchyPolicy. This class shows an icon beside each item to act as an expand/collapse button. The application can specify which icon to use in different situations so that the button can animate properly as it is pressed.

If the application desires a view with only a single icon or label per item, this can be achieved by setting the icon to nil for each item, setting the label to the desired visual for each item, setting the labelOrientation to XmRIGHT.

The objects used for item labels are typically Strings, and those used for item icons are typically CgIcons, but this is not a requirement. It is possible for an application to use any object as the label and icon for an item. Any item which understands #ewHeightUsing:, #ewWidthUsing: and #ewDrawUsing: (called a “renderable object”) can be used for the label and icon. Since String and CgIcon already implement the standard renderable object protocol, they can easily be used. Also, since Object provides default renderable behavior, any object can be rendered, although the default rendering is to render the object’s #printString.

Label editing can take place under program control only. When a label is about to be edited, the widget fires its About To Begin Edit event. The application must hook this event or else editing will never occur. At a minimum, the application must set the callData doit: true to allow editing to begin.

Protocol

addedItems: itemsOrderedCollection at: indicesOrderedCollection
Item(s) were added to the collection of root items at the specified position. The position is specified as an index in the collection of root items only. Refresh the list.

 

attributeName: aSymbol
Specifies a unary selector sent to an item to return its name/label.

 

collapseItem: anItem
Collapse the hierarchy rooted at anItem.

 

deferRefreshWhile: aBlock
Minimize the repainting done while aBlock is being evaluated. This message may be safely nested. This message does not guarantee minimal repainting. Rather, it serves as a hint to the widget so that, where possible and appropriate, repainting can be deferred until the block has finished being evaluated.

 

deselectAllItems
Deselect and remove all elements from the selectedItems list.

 

deselectIndex: anInteger
Deselect and remove an item from the selected list by position.

 

deselectItem: item
Deselect and remove the specified item from the selected list.

 

editItem: anItem
Begin editing the given item.

 

emphasisPolicy: anInteger
Specifies whether to draw the icon and label emphasis as one single rectangle or as two separate rectangles.

Default: XmSEPARATE (Separate)

Valid resource values:

XmTOGETHER (Together) - Draw the icon and label emphasis as one single rectangle.

XmSEPARATE (Separate) - Draw the icon and label emphasis as two separate rectangles.

 

endEdit
Call the end edit events and proceed with an end to the edit if approved. Hide the edit widget only if the end was approved. Answer whether the end was approved.

 

expandItem: anItem
Expand the hierarchy rooted at anItem.

 

hierarchyPolicy: hierarchyPolicy
Determines how the hierarchy is to be shown. This includes what the indentation level should be as well as whether to draw lines connecting the items and whether to show some kind of button beside items which have children. By default the hierarchyPolicy is an instance of EwHierarchyPolicy with lines set to true.

 

indexAtPoint: aPoint
Answer the index of the item in the list which lies beneath the point given. If no item lies beneath the point or if the widget has not been drawn yet, then answer nil.

 

indexOfItem: item
Answer the index of the item given in the list or 0 if the item is not present in the list.

 

innerMargin: anInteger
Specifies the margin width to be used between each item’s icon and its label.

 

isItemExpanded: anItem
Answer whether an item in the list is expanded to show its children.

 

itemAtPoint: aPoint
Answer the item in the list which lies beneath the point given. If no item lies beneath the point, then answer nil.

 

itemChildrenAttributeName: aSymbol
Specifies a unary selector sent to an item to return its children.

 

itemChildrenAttributes: aDictionary
Specifies a collection of selectors (indexed by item class) sent to an item to return its children.

 

itemColorAttributeName: aSymbol
Specifies a unary selector sent to an item to return its label color.

 

itemCount
Specifies the total number of items. This number might not match XmNitems, since this number is the size of the expanded hierarchy. Item count is automatically updated whenever an element is added to or deleted from the list.

 

itemHasChildrenAttributeName: aSymbol
Set the unary selector sent to an item to return whether it has children.

 

itemHasChildrenAttributes: aDictionary
Specifies a collection of selectors (indexed by item class) sent to an item to return whether it has children.

 

itemHeight: anInteger
Specifies the height in pixels of items in the list. This includes the margin height on the top and bottom of the item as well as two pixels for emphasis.

 

itemIconAttributeName: aSymbol
Specifies a unary selector sent to an item to return its icon.

 

itemIconExpandAttributeName: aSymbol
Specifies a unary selector sent to an item to return its expanded icon.

 

itemInitialStateAttributeName: aSymbol
Specifies a unary selector sent to an item to return its initial state (expanded or not).

 

itemIsVisible: item
Check if a specified item is in the portion of the list that is currently visible. Answer true if it is even partially visible, false if it is not visible.

 

items: anOrderedCollection
An array of objects that are to be displayed as the list items.

 

itemsDo: aBlock
Evaluate aBlock for each item in the receiver's list.

 

itemWidth: anInteger
Specifies the width in pixels of items in the list. This includes the two pixels for emphasis.

 

labelOrientation: anInteger
Specifies the label position associated with the items.

Default: XmRIGHT (Right)

Valid resource values:

XmRIGHT (Right) - Position the label to the right of the icon.

XmBOTTOM (Bottom) - Position the label beneath the icon.

 

parentOfItem: anItem
Answer the parent of the item given in the hierarchy or false if it is not in the expanded hierarchy. Answer nil if it is a root item.

 

refreshAllItems
Refresh all of the ite,s

 

refreshIndex: position
Refresh an item in the list by position.

 

refreshItem: item
Refresh an item in the list.

 

refreshItemHierarchy: anItem
Refresh an item. Also reobtain the item's children.

 

refreshItems: aCollection
Refresh all of the items in the collection.

 

removedItems: itemsOrderedCollection at: indicesOrderedCollection
Identifies what items were removed from the items attribute ordered collection and at what index. Only the items identified will be refreshed.

 

scrollableDown
Answers false if the list is all the way at the bottom item.

 

scrollableLeft
Answers false if the list is all the way to the left.

 

scrollableRight
Answers false if the list is all the way to the right.

 

scrollableUp
Answers false if the list is all the way at the top item.

 

scrollBarDisplayPolicy: anInteger
Save the value of scrollBarDisplayPolicy.

 

scrollDown
Scrolls the list box down one item.

 

scrollingWithHiddenScrollBars: aBoolean
Sets indicator if the scrollbars should be hidden or not.

 

scrollLeft
Scrolls the list box left one.

 

scrollPageDown
Scrolls the list box down one page of items.

 

scrollPageLeft
Scrolls the list box left one page.

 

scrollPageRight
Scrolls the list box right one page.

 

scrollPageUp
Scrolls the list box up one page of items.

 

scrollRight
Scrolls the list box right one.

 

scrollUp
Scrolls the list box up one item.

 

selectedItem
Answer the item selected in the list.

 

selectedItemCount
Answer the number of selected items.

 

selectedItems: anOrderedCollection
An OrderedCollection of Objects that represents the list items that are currently selected, either by the user or the application.

 

selectIndex: anInteger
Select the item a index

 

selectionIndex: anInteger
The index of the selected item

 

selectionIndices: anOrderedCollection
An OrderedCollection of Integers that represents the indices of the list items that are currently selected, either by the user or the application.

 

selectionPolicy: anInteger
Defines the interpretation of the selection action.

Default: XmBROWSESELECT (Browse Select)

Valid resource values:

XmSINGLESELECT (Single Select) - Allows only single selections. Under Windows, this is the same as Browse Select.

XmMULTIPLESELECT (Multiple Select) - Allows multiple items to be selected. The selection of an item is toggled when it is clicked on. Clicking on an item does not deselect previously selected items.

XmEXTENDEDSELECT (Extended Select) - Allows multiple items to be selected, either by dragging the selection or by clicking on items with a modifier key held down. Clicking on an item without a modifier key held down deselects all previously selected items.

XmBROWSESELECT (Browse Select) - Allows only single selection. The selection changes when the mouse is dragged. This is the default Selection Policy. Under Windows, this is the same as Single Select.

XmREADONLYSELECT (Read Only Select) - Allows navigation, but no selection or events.

 

selectItem: anItem
Select an item in the list. This message selects and adds the specified item to the current selected list. The cursor moves to the newly selected item.

 

setBottomIndex: position
Make an item the last visible item in the list by position. This message makes the item at the specified position the last visible item in the list.

 

setBottomItem: item
Make the given item the last visible item in the list. The item can be any valid item in the list.

 

setTopIndex: position
Make an item the first visible item in the list by position. This message makes the item at the given position the first visible position in the list.

 

setTopItem: item
Make the given item the first visible item in the list. The item can be any valid item in the list.

 

showIcons: aBoolean
Set whether icons should be displayed.

 

visibleItemCount
Specifies the number of items that can fit in the visible space of the list. Until the list is realized, this answers 0.

Events

About To Begin Edit
These events are triggered when an item is about to be edited.

 

About To End Edit
These events are triggered when an item is done being edited.

 

Default Action Requested
These events are triggered when an item is double clicked.

 

Getting Focus
These events are triggered the part gets focus.

 

Item Children Requested
These events are triggered when an item’s list of children is needed.

 

Item Collapsed
These events are triggered when an item is collapsed.

 

Item Expand
These events are triggered when an item is expanded.

 

Item PopUp Menu Request
These events are triggered when an item needs its popup menu.

 

Losing Focus
These events are triggered the part loses focus.

 

Resized
These events are triggered when the part is resized.

 

Scrolled
These events are triggered when the part is scrolled.

 

Selected Item Changed
These events are triggered when the selected item is changed.

 

Selected Items Changed
These events are triggered when the selected items are changed.

 

Selection Index Changed
These events are triggered when the selected index is changed.

 

Selection Indices Changed
These events are triggered when the selected indices are changed.

 

Visual Info Requested
These events are triggered when an item’s icon, label and isInUse are needed.