Generic Function | Package: cg | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version

## add-outline-item

Arguments: outline new-item parent-item-or-value &key no-redisplay position no-error-p

Adds the outline-item new-item to outline either as a top-level item or as a subitem of the item whose value is parent-item-or-value, at position among its siblings. new-item must be an instance of the `outline-item` class. outline must be an instance of the `outline` class.

parent-item-or-value may be either the parent `outline-item` under which to add the new item, or the parent item's value, or else `nil` to add the new item as a top-level item. Specifying the parent item by its value is typically convenient, but is less efficient since the item must first be looked up from its value. And if multiple items have this same value, then the wrong parent may be found unless the actual parent outline-item is specified. (If parent-item-or-value is non-`nil` and no outline-item can be found in outline that matches the specified value, then an error is signaled if no-error-p is `nil`, and nothing is done if no-error-p is true.)

This function searches only through the currently visible outline-items for parent-item-or-value. If parent-item-or-value specifies an item that is currently hidden (due to an ancestor item being closed), then an error is signaled unless no-error-p is true. As an alternative, (setf range) works regardless of whether the parent item is currently visible.

The value of position should be a non-negative integer, `:end` or `nil`. 0 means above all siblings. `:end` means below all siblings. `nil` means position according to the on-sort-predicate (if on-sort-predicate is `nil` or the function true (which always returns true) new-item is positioned at the top among its siblings.)

If no-redisplay is true, the outline will not be redisplayed by this function to reflect the change. You may wish to delay redisplay when there is more than one modification until all modifications are made.

If no-error-p is true, no error will be signaled if the requested action cannot be performed for any reason. Instead, nothing will be done. (Specifying this argument true does not protect against malformed calls to this function, such as specifying a value for new-item which is not an instance of `outline-item`.)

To change the whole set of child outline-items of a parent outline-item (or all of the top-level items of an outline control), an alternative is to call (setf range) on the parent outline-item or the outline control, passing a list of outline-items as the new value.

If no item was successfully added, then `nil` is returned. Otherwise two values are returned: (1) the `outline-item` that was added, and (2) the index of the new item within all currently visible items. (The index will be `nil` if the new item is not visible because the parent item is closed.)

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version