Outline

A mutable outline of Item s.

Use outlines to create new items, find existing items, watch for changes in items, and add/remove items.

When you add/remove items using the outline’s methods the items children are left in place. For example if you remove an item, it’s chilren stay in the outline and are reasigned to a new parent item.

Examples

Group multiple changes:

outline.groupUndoAndChanges(function() {
  root = outline.root;
  root.appendChildren(outline.createItem());
  root.appendChildren(outline.createItem());
  root.firstChild.bodyString = 'first';
  root.lastChild.bodyString = 'last';
});

Watch for outline changes:

disposable = outline.onDidChange(function(mutation) {
  switch(mutation.type) {
    case Mutation.ATTRIBUTE_CHANGED:
      console.log(mutation.attributeName);
      break;
    case Mutation.BODY_CHANGED:
      console.log(mutation.target.bodyString);
      break;
    case Mutation.CHILDREN_CHANGED:
      console.log(mutation.addedItems);
      console.log(mutation.removedItems);
      break;
  }
});
...
disposable.dispose()

Construction

.createTaskPaperOutline(content)

The outline is configured to handle TaskPaper content at runtime. For example when you set attributes through the Item API they are encoded in the item body text as @tags. And when you modify the body text @tags are parsed out and stored as attributes.

Argument Description
content String (optional) outline content in TaskPaper format.
Return Values
Returns a TaskPaper Outline .
::constructor(type?, serialization?)

Create a new outline.

Argument Description
type? String outline type. Default to ItemSerializer.TEXTType .
serialization? String Serialized outline content of type to load.

Finding Outlines

::id

Read-only unique (not persistent) String outline ID.

.getOutlines()

Retrieves all open Outline s.

Return Values
Returns an Array of Outline s.
.getOutlineForID(id)
Argument Description
id String outline id.
Return Values
Returns existing Outline with the given outline id.

Events

::onDidBeginChanges(callback)

Invoke the given callback when the outline begins a series of changes.

Argument Description
callback Function to be called when the outline begins updating.
Return Values
Returns a Disposable on which .dispose() can be called to unsubscribe.
::onWillChange(callback)

Invoke the given callback before the outline changes.

Argument Description
callback Function to be called when the outline will change.
Return Values
Returns a Disposable on which .dispose() can be called to unsubscribe.
::onDidChange(callback)

Invoke the given callback when the outline changes.

See Outline Examples for an example of subscribing to this event.

Argument Description
callback Function to be called when the outline changes.
Return Values
Returns a Disposable on which .dispose() can be called to unsubscribe.
::onDidEndChanges(callback)

Invoke the given callback when the outline ends a series of changes.

Argument Description
callback Function to be called when the outline ends updating.
Return Values
Returns a Disposable on which .dispose() can be called to unsubscribe.
::onDidUpdateChangeCount(callback)

Invoke the given callback when the outline’s change count is updated.

Argument Description
callback Function to be called when change count is updated.
  • changeType — The type of change made to the document.
Return Values
Returns a Disposable on which .dispose() can be called to unsubscribe.
::onDidDestroy(callback)

Invoke the given callback when the outline is destroyed.

Argument Description
callback Function to be called when the outline is destroyed.
Return Values
Returns a Disposable on which .dispose() can be called to unsubscribe.

Reading Items

::root

Read-only root Item in the outline.

::items

Read-only Array Item s in the outline (except the root).

::getItemForID(id)
Argument Description
id String id.
Return Values
Returns Item for given id.
::evaluateItemPath(itemPath, contextItem?)

Evaluate the item path search starting from this outline’s Outline.root item or from the passed in contextItem if present.

Argument Description
itemPath String itempath expression.
contextItem? defaults to Outline.root .
Return Values
Returns an Array of matching Item s.

Creating Items

::createItem(text?)

Create a new item. The new item is owned by this outline, but is not yet inserted into it so it won’t be visible until you insert it.

Argument Description
text? String or AttributedString .
::cloneItem(item, deep?)

The cloned item is owned by this outline, but is not yet inserted into it so it won’t be visible until you insert it.

Argument Description
item Item to clone.
deep? defaults to true.
Return Values
Returns Clone of the given Item .
::importItem(item, deep?)

Creates a clone of the given Item from an external outline that can be inserted into the current outline.

Argument Description
item Item to import.
deep? defaults to true.
Return Values
Returns Item clone.

Insert & Remove Items

::insertItemsBefore(items, referenceItem)

Insert the items before the given referenceItem. If the reference item isn’t defined insert at the end of this outline.

Unlike Item::insertChildrenBefore this method uses Item::indent to determine where in the outline structure to insert the items. Depending on the indent value these items may become referenceItem’s parent, previous sibling, or unrelated.

Argument Description
items Item or Array of Item s to insert.
referenceItem Reference Item to insert before.
::removeItems(items)

Remove the items but leave their child items in the outline and give them new parents.

Argument Description
items Item or Item Array to remove.

Changes

::isChanging

Read-only Boolean true if outline is changing.

::isChanged()

Determine if the outline is changed.

Return Values
Returns a Boolean .
::updateChangeCount()

Updates the receiver’s change count according to the given change type.

::groupChanges(callback)

Group changes to the outline for better performance.

Argument Description
callback Callback that contains code to change Item s in this Outline .

Undo

::groupUndo(callback)

Group multiple changes into a single undo group.

Argument Description
callback Callback that contains code to change Item s in this Outline .
::groupUndoAndChanges(callback)

Group multiple changes into a single undo and change group. This is a shortcut for:

outline.groupUndo(function() {
  outline.groupChanges(function() {
    console.log('all grouped up!');
  });
});
Argument Description
callback Callback that contains code to change Item s in this Outline .
::undo()

Undo the last undo group.

::redo()

Redo the last undo group.

Serialization

::serialize(options?)

Return a serialized String version of this Outline’s content.

Argument Description
options? Serialization options as defined in . type key defaults to .
::reloadSerialization(serialization, options?)

Reload the content of this outline using the given string serilaization.

Argument Description
serialization String outline serialization.
options? Deserialization options as defined in . type key defaults to .

Debug

::toString()
Return Values
Returns debug string for this item.

results matching ""

    No results matching ""