[This is preliminary documentation and subject to change.]
The Name property of an OUTLINEITEM is the string displayed, or the name by which an item would be referred. (Or, we could use Value for this...an open issue.)
In an OUTLINE object, indentation levels are represented by making the indented item's children of the item one level higher. Thus, enumerating the children of an OUTLINE object yields only the first-level OUTLINEITEMs. Enumerating the children of a first-level object reveals the second-level objects grouped underneath it. Note that you cannot determine an item's indent level directly, you must walk up the chain of parents until you reach an OUTLINE object.
In some cases an outline might skip one or more levels. In that case an invisible OUTLINEITEM object must be created to represent each level that has no items.
Alternatively, we could state that the accValue (or accName...to be decided) of an outlineitem object is its indentation level. That would remove the need for invisible placeholder objects when indentation levels are skipped. Note, however, that because levels can be skipped, a client cannot assume that the indentation levels alone convey the parent-child relationships. That is, you cannot assume that a third-level item is actually the child of the second-level item that precedes it.
Also note that an OUTLINEITEM can contain objects that are not additional OUTLINEITEMs. For example, the standard Windows tree view control displays a check box (displaying a plus or minus symbol) to the left of each item that has child items. When this is exposed via OLE Accessibility, the checkbox would be a child of the outline item. Any child of an OUTLINEITEM that is not itself an OUTLINEITEM is assumed to be a component of the item itself. (Alternatively, we could recommend that each compound item be a child of a GROUPING object. In that case, children of OUTLINEITEMs would be limited to other OUTLINEITEMs and GROUPINGs. This arrangement makes icons, check boxes and other decorations peers to the outline item rather its children. There seem to be pros and cons to both approaches.)
If a client wishes to enumerate the contents of an outline in top-to-bottom order, it must recurse through the contents of each child in turn. There is no single list of all the items.
LIST objects are a degenerate case of OUTLINE objects. In essence a LIST is an OUTLINE with only one level, and all LISTITEM objects are children of the LIST object. Clients can be much more efficient when dealing with a LIST, because they can enumerate the contents using accChild or accNavigate with NAVDIR_NEXT.
There is no need for recursive code. However, as with OUTLINEITEMs, LISTITEM objects can have children such as check boxes and icons that are actually a part of a complex item's visual presentation.
Clients should also keep in mind that LIST and OUTLINE objects are not limited to conventional, one-dimensional displays with the root at the top. Applications have complete freedom of visual presentation. In fact, an OUTINE object can be displayed much like a flow chart, with items scattered seemingly without pattern. Therefore clients should always rely on the accLocation property of each item rather than assuming a constant direction or visual style.