add-outline-item-value

Arguments: outline item-value parent-item-or-value &key kind (state :closed) range no-redisplay position no-error-p

Creates a new outline-item instance whose value is item-value, and adds the new item to outline as a child item of the item specified by parent-item-or-value. (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.

outline is the outline widget to which the new item is being added.

item-value is an arbitrary value for the new outline-item. See also add-outline-item, which takes an outline-item object instead.

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.

position indicates the index of the new item among its siblings. Zero (or nil) puts the item above all its siblings, 1 places it below the first sibling, and so on. The special value :end will put the item below all of 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.

range may be a list of outline-item instances that will become the child items of the newly-created item, or (typically) nil to not add any child items at this time.

kind simply sets the kind property of the new item.

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.)

See also add-sibling-outline-item, add-child-outline-item, remove-outline-item-value and outline-item-added.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had minimal revisions compared to the 8.2 page.
Created 2019.8.20.