| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |