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.