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. `mutation` — `Mutation` describing the 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. `mutation` — `Mutation` describing the 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. `changes` — `Array` of `Mutation` s.

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.

Outline

Outline

Examples

Construction

Finding Outlines

Events

Reading Items

Creating Items

Insert & Remove Items

Changes

Undo

Serialization

Debug

results matching ""

No results matching ""