MORE INFORMATION
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 AddItem
method takes two parameters -- the text you want to show in the outline and
the list index of the item. The second parameter is optional.
For example, the following line of code adds an item named Apples to the
bottom of the outline:
Thisform.oleOutline.AddItem("Apples")
The following line of code adds an item named Bananas to the second
position in the list:
Thisform.oleOutline.AddItem("Bananas",2)
How the ListIndex Property Affects the Items in Your Outline
As each individual item is added to the outline, it is assigned a list
index. The list index may be assigned manually by you when the item is
added, or it may be automatically assigned by the Msoutl.ocx.
The list index property affects the relative positioning of items within
the outline. If you add an item and specify a listindex property, any items
below the inserted item are moved down, and their respective listindex
properties are changed. The following table shows initial list index
properties, and how they are affected by inserting an item prior to the
current list index:
Original Insert List Insert List
Item Name List Index Index of 2 Index of 6
---------------------------------------------------------
Fruit 1 1 1
Vegetables 5 6 7
Meats 10 11 12
The table indicates that the ListIndex property will change as items are
added to the outline. This means that if you insert items, you may be
inserting them at a different place than intended. This causes problems if
you want to build a list of headings, and then insert items at the
appropriate location under each heading.
Because this property is volatile, you may want to build your outline in
sequential order, and allow the Msoutl32.ocx to assign a list index
automatically to each item as you add it to the outline. With this
technique, as you add topics, you need to add all the subitems for that
outline 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 property
can be set to a minimum value of 0. The maximum value will depend on the
number 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 the
second 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 indent
level of the item preceeding it.
The HASSUBITEMS() function allows you to determine programmatically if a
particular 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 of
the following properties. These properties determine the picture displayed
when an outline item is expanded, closed, or is a subitem:
PictureOpen
PictureClosed
PictureLeaf
You can also specify a picture to be substituted for a particular item that
has subordinate items by setting the following properties:
The picture can be any small bitmap (.bmp file). You must set the picture
for the entire outline. You can also use the Style property to determine
which items are displayed with a particular item in the outline. Each
outline item has an individual style property. You may decide to change the
style property, for example, depending on whether an individual outline
item 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 array
property to allow you to gain access to particular items within the
outline.
The ListCount property of the outline returns the number of items in the
outline.
The List property allows you to gain access to an item in the outline by
display order, regardless of the list index property setting for that item.
The following line of code sets the text of the third outline item to
Oranges:
ThisForm.oleOutline.list(3) = "Oranges"
You may also want to use the ItemData property of the outline control. This
property 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 item
currently selected from the outline. You can do this by using the Text
property as follows:
ThisForm.oleOutline.Text
This property is read-only. You must use the LIST() function to change the
text programmatically.
Expanding and Collapsing Outline Sections
The code to expand and collapse the outline is built into the functionality
of the control. You do not need to write code to handle expansion and
collapsing. However, you can affect a single item by setting its Expand
property 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 properties
associated 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 the
Vfp\Samples\Ole\Outline1.scx file supplied with Visual FoxPro.