The Professional Edition of Visual FoxPro includes the Microsoft Outlinecontrol (Msoutl32.ocx). The outline control can be used to displayinformation in a graphical hierarchical format, such as in file opendialog boxes. This article describes how to use the outline control in theForms Designer to perform some common tasks.
Adding an Outline to your Form
- Create a new form.
- Add an OLE Container control to your form. In the OLE Container control dialog box, click the Insert Control option, and select the Outline control from the list of available controls. Click OK.
- Change the Name property of the control to oleOutline.
Populating the Outline
To add items to the outline, use the outline's AddItem method. The AddItemmethod takes two parameters -- the text you want to show in the outline andthe list index of the item. The second parameter is optional.
For example, the following line of code adds an item named Apples to thebottom of the outline:
The following line of code adds an item named Bananas to the secondposition in the list:
How the ListIndex Property Affects the Items in Your Outline
As each individual item is added to the outline, it is assigned a listindex. The list index may be assigned manually by you when the item isadded, or it may be automatically assigned by the Msoutl.ocx.
The list index property affects the relative positioning of items withinthe outline. If you add an item and specify a listindex property, any itemsbelow the inserted item are moved down, and their respective listindexproperties are changed. The following table shows initial list indexproperties, and how they are affected by inserting an item prior to thecurrent list index:
Original Insert List Insert ListItem Name List Index Index of 2 Index of 6---------------------------------------------------------Fruit 1 1 1Vegetables 5 6 7Meats 10 11 12
The table indicates that the ListIndex property will change as items areadded to the outline. This means that if you insert items, you may beinserting them at a different place than intended. This causes problems ifyou want to build a list of headings, and then insert items at theappropriate location under each heading.
Because this property is volatile, you may want to build your outline insequential order, and allow the Msoutl32.ocx to assign a list indexautomatically to each item as you add it to the outline. With thistechnique, as you add topics, you need to add all the subitems for thatoutline item before adding an item at the same hierarchical level.
Indenting Items Appropriately in the Outline
Each outline item has an associated Indent property. The Indent propertycan be set to a minimum value of 0. The maximum value will depend on thenumber of hierarchical levels in the current branch of the outline.
- A value of zero (0) indicates that the item should be invisible. This is the default value assigned by the AddItem method. You must set this to a value of 1 or higher to see the outline item. The first item in the outline is considered the "root item" of the outline, and it must have an indentation level of 0.
- A value of 1 indicates that the item is displayed at the highest level of the outline.
- A value of 2 or higher indicates that the item is a subitem of the next higher indentation level. You can use an indent level higher than 2, however, the indent can only be set to a maximum of one higher than the indentation of the item directly preceding it in the outline. If you try to set an indent level greater than one more of the prior item, you will receive an error.
The following line of code illustrates setting the Indent property of thesecond item in the outline to an indent level of 3:
thisform.oleOutline.indent(2) = 3
NOTE: The indent level of an item can be at most 1 greater than the indentlevel of the item preceeding it.
The HASSUBITEMS() function allows you to determine programmatically if aparticular item has subitems associated with it.
Changing the Display of the Pictures in the Outline
You can change the picture associated with the outline by setting one ofthe following properties. These properties determine the picture displayedwhen an outline item is expanded, closed, or is a subitem:
You can also specify a picture to be substituted for a particular item thathas subordinate items by setting the following properties:
The picture can be any small bitmap (.bmp file). You must set the picturefor the entire outline. You can also use the Style property to determinewhich items are displayed with a particular item in the outline. Eachoutline item has an individual style property. You may decide to change thestyle property, for example, depending on whether an individual outlineitem has subitems associated with it:
Setting Description---------------------------------------- 0 Text only. 1 Picture and text. 2 (Default) Plus/minus and text. 3 Plus/minus, picture, and text. 4 Tree lines and text. 5 Tree lines, picture, and text.
Gaining Access to a Particular Outline Item
Because the outline is a container object, it contains a control arrayproperty to allow you to gain access to particular items within theoutline.
The ListCount property of the outline returns the number of items in theoutline.
The List property allows you to gain access to an item in the outline bydisplay order, regardless of the list index property setting for that item.The following line of code sets the text of the third outline item toOranges:
ThisForm.oleOutline.list(3) = "Oranges"
You may also want to use the ItemData property of the outline control. Thisproperty contains an array of all items currently in the outline.
Obtaining the Text Associated with a Particular Outline Item
Occasionally, you may want to determine the text associated with the itemcurrently selected from the outline. You can do this by using the Textproperty as follows:
This property is read-only. You must use the LIST() function to change thetext programmatically.
Expanding and Collapsing Outline Sections
The code to expand and collapse the outline is built into the functionalityof the control. You do not need to write code to handle expansion andcollapsing. However, you can affect a single item by setting its Expandproperty to true (.T.) or false (.F.) appropriately.
Obtaining More Information on the Outline Control
This article is not a comprehensive list of all the methods and propertiesassociated with the Msoutl32.ocx. To obtain more information, query using"outline control" in the Visual FoxPro Help file.
To view a sample form containing an outline control, open theVfp\Samples\Ole\Outline1.scx file supplied with Visual FoxPro.