ViewKit ObjectPak Outline Component

The VkOutline component, derived from VkComponent, displays a textual outline. VkOutline automatically indents items according to their depth in the outline. Figure 61. shows an example of a VkOutline component containing three top-level items, each with several subitems.

Figure 61. Example of a VkOutline Component

If there is not sufficient space to display the entire outline, the VkOutline component automatically displays a scrollbar, as shown in Figure 62..

Figure 62. Example of a VkOutline Component with the Scrollbar Visible

The VkOutline component displays a control icon to the left of each outline item that contains subitems. The control icon denotes whether the sub-tree under the item is displayed (open) or not (closed). The user can click the left mouse button on the control icon to toggle between the open and closed states.

Figure 63. shows the results of closing the item "Subheading 2B," shown in the previous figure.

Figure 63. Example of Closing a Heading in a VkOutline Component

Constructing an Outline Component

The VkOutline constructor accepts the standard ViewKit ObjectPak component constructor arguments: a component name and a parent widget:

VkOutline (const char *name, Widget parent)

Adding Items to an Outline

You can add items to the outline in a simple parent-child relation with VkOutline::add():

void add(char* parentName, char* childName)

Add() actions

The actions performed by add() depend on whether either or both of the items already exist in the outline.

  • If both items already exist in the outline, add() does nothing.
  • If neither exists, add() creates parentName as a top-level item in the outline and then creates childName as a subitem of parentName.
  • If parentName already exists but childName does not, add() creates childName as a subitem of parentName.
  • If childName exists and parentName does not, and childName is a top-level item, add() "reparents" childName by adding parentName as a top-level item and moving childName in the outline so that it is a subitem of parentName.
  • If childName exists and parentName does not, but childName is not a top-level item, add() does nothing.

parentName and childName are used both as item names and the text displayed in the outline. Note that you must use unique names for each item in the outline.

Adding multiple subitems

To add multiple subitems to an existing item, use VkOutline::addChildren():

void addChildren(char** parentPath, char** childNames)
void addChildren(char** parentPath, char** childLabels,
char** childNames, void** childData)

The character string array parentPath specifies the complete path of the parent item through the outline. The first element of the parentPath array is the name of the top-most item of the outline containing the specified item, the second element is the name of the second-highest item, and so on, with the name of the item itself appearing last. You must NULL-terminate the array.

The character string array childNames contains the names of the subitems to add to the specified parent item. Note that you must use unique names for each item in the outline.

In the second form of addChildren(), you can provide childLabels, an array of character strings that provide display labels for the subitem you add. VkOutline displays these labels for the items instead of the item names.

In the second form of addChildren(), you can also provide childData, an array of pointers to arbitrary data. You can retrieve a pointer to the data associated with an item using VkOutline::getHookAt(), described in "Outline Utility and Access Functions" . Usually you need to use this data only if you create a subclass of VkOutline. In a subclass, you can add callbacks so that when the user selects an outline item, you can retrieve the data associated with that item and perform some action.

VkOutline::createPath() creates or extends a path in the outline:

void createPath(char** itemLabels, char** itemNames)

The character string array itemNames specifies a path through the outline. The first element of the itemNames array is the name of the top-most item of the outline containing the specified item, the second element is the name of the second-highest item, and so on, with the name of the item itself appearing last. You must NULL-terminate the array.

If path does not exist, then createPath() creates a new set of items with the first element in the path as the top-level item, the second element a subitem of the first, and so on. If createPath() finds a partial match in the existing outline, where the first element of itemNames matches the name of an existing top-level item and one or more lower-level items match succeeding elements of itemNames, createPath() adds those items needed to fully extend the path.

For those items that createPath() adds, it uses the corresponding elements from the itemLabels character string array as the display labels for those items. VkOutline displays these labels for the items instead of the item names.


Note: createPath() does not alter the labels for any existing items. createPath() uses the labels only when adding new items.


Whenever you add items to the outline, no matter which function you use to add them, you must call VkOutline::displayAll() to update the outline display:

void displayAll()

Setting Display Attributes for Outline Items

VkOutline allows you to designate items as "keywords" and display them in a different foreground color, background color, and/or font. You can also define up to four custom item highlights, each wi7th its own foreground color, background color, and font attributes.

Defining keyword display attributes

Use VkOutline::setKeywordAttributes() to define the keyword display attributes:

void setKeywordAttributes(Pixel fg, Pixel bg, XmFontList font)

fg is the foreground color for the item's text. bg is the background color for the item. font is the font used to display the item's text.

Displaying items with keyword display attributes

Use VkOutline::displayAsKeyword() to display an item with the keyword display attributes:

void displayAsKeyword(char** path)

You specify the complete path of the item through the outline as an array of character strings. The first element of the path array is the name of the top-most item of the outline containing the specified item, the second element is the name of the second-highest item, and so on, with the name of the item itself appearing last. You must NULL-terminate the array. Note that displayAsKeyword() requires the item names, not their display labels.

Defining display attributes of a custom highlight

Use VkOutline::setHighlightAttributes() to define the display attributes of a custom highlight:

int setHighlightAttributes(Pixel fg, Pixel bg, XmFontList font)

fg is the foreground color for the item's text. bg is the background color for the item. font is the font used to display the item's text. setHighlightAttributes() returns an integer identifier for the highlight. You use this identifier to apply the highlight to outline items with the highlight() function described below. If setHighlightAttributes() could not allocate a custom highlight, it returns 0.

Displaying items with attributes of a custom highlight

Use VkOutline::highlight() to display one or more items with display attributes of a custom highlight:

void highlight(int itemPos, int attribID)
void highlight(char** items, int attribID)

In the first form of highlight(), you specify the position index in the outline of the item you want to highlight. Items are numbered sequentially from the top of the outline starting with zero. attribID is the attribute identifier returned by setHighlightAttributes() of the custom highlight that you want to assign to the items.

In the second form of highlight(), items is an array of strings specifying the names of items to highlight. highlight() requires the item names (not display labels. attribID is the attribute identifier (returned by setHighlightAttributes()) of the custom highlight that you want to assign to the items.

You cannot remove a custom highlight from individual items; you can only remove the highlight from all items to which you have applied it. VkOutline::unhighlight() removes a custom highlight:

void unhighlight(int attribID)

attribID is the attribute identifier (returned by setHighlightAttributes()) of the custom highlight that you want to assign to the items.

Closing and Opening Outline Topics

To programmatically toggle an outline item open or closed, use VkOutline::toggleChildren():

virtual void toggleChildren(int position)

position is the item's position in the SgList widget. Items are numbered sequentially from the top of the outline starting with zero.

Determining effects of last toggle operation

To determine the effects of the last toggle operation, whether a result of user interaction or a call to toggleChildren(), call VkOutline::effectOfLastToggle():

int effectOfLastToggle(int& from, int& count)

If the last toggle operation opened an item (and therefore inserted items into the SgList widget), effectOfLastToggle() returns 1, sets the value of from to the position of the toggled item in the list, and sets the value of count to the number of items displayed by opening the item. If the last toggle operation closed an item (deleting items from the SgList widget), effectOfLastToggle() returns 0, sets the value of from to the position of the toggled item in the list, and sets the value of count to the number of items deleted from the list by closing the item.

Determining whether an item is closed

To determine whether a given item is closed, use VkOutline::isPathClosed():

int isPathClosed(char** path)

The character string array path specifies the complete path of the item through the outline. The first element of the path array is the name of the top-most item of the outline containing the specified item, the second element is the name of the second-highest item, and so on, with the name of the item itself appearing last. You must NULL-terminate the array.

isPathClosed() returns 1 if item is closed, 0 if item is open, and -1 if item has no subitems.

Outline Utility and Access Functions

VkOutline provides the following utility and access functions:

void setIndentationWidth(int width)

VkOutline::setIndentationWidth() sets indentation width for future displays. The indentation width is the number of pixels to the right that the outline offsets a child item from its parent item.

void printTree()

VkOutline::printTree() prints the outline on the application's standard output.

void reset()

VkOutline::reset() re-initializes the outline, deleting all items. reset() retains any display attributes you created.

Widget listWidget()

VkOutline::listWidget() returns the widget ID of the SgList widget that the VkOutline uses to display the outline. Consult the SgList(3) reference page for more information on the SgList widget.

void select(int position)

VkOutline::select() selects the string displayed at the given position of the SgList widget.

void getHookAt(int position)

VkOutline::getHookAt() retrieves the pointer to the data associated with an item given the item's position in the SgList widget. This is the data that you provided as the childData argument to addChildren() (see "Adding Items to an Outline" ).

Usually, you need to use this data only if you create a subclass of VkOutline. In a subclass, you can add callbacks to the SgList widget so that when the user selects an outline item, you can retrieve the data associated with that item and perform some action.