# Chapter 3: Using Outlines

This chapter tells how to use Leo's outlines.

Contents

- Chapter 3: Using Outlines
  - Autocompletion and calltips
  - Cloning nodes
  - Creating and destroying nodes
  - Creating and destroying multiple body editors
  - Cutting, pasting and deleting nodes
  - Dragging nodes
  - Editing body text
  - Expanding & contracting nodes
  - Indenting body text automatically
  - Marking nodes
  - Moving & Reorganizing nodes
  - Navigating through the outline
  - Opening URL's automatically
  - Resizing panes
  - Undoing operations
  - Using chapters

## Autocompletion and calltips

Typing a period when @language python is in effect starts autocompletion. Typing '(' during autocompletion shows the calltip. Typing Return or Control-g (keyboard-quit) exits autocompletion or calltips.

Autocompletion

Autocompletion shows what may follow a period in code. (Actually you can specify any character using the auto-complete shortcut setting.) For example, after typing g. Leo will show a list of all the global functions in leoGlobals.py. Autocompletion works much like tab completion in the minibuffer. Unlike the minibuffer, the presently selected completion appears directly in the body pane.

A leading period brings up 'Autocomplete Modules'. (The period goes away.) You can also get any module by typing its name. If more than 25 items would appear in the Autocompleter tab, Leo shows only the valid starting characters. At this point, typing an exclamation mark shows the complete list. Thereafter, typing further exclamation marks toggles between full and abbreviated modes.

If x is a list 'x.!' shows all its elements, and if x is a Python dictionary, 'x.!' shows x.keys(). For example, 'sys.modules.!' Again, further exclamation marks toggles between full and abbreviated modes.

During autocompletion, typing a question mark shows the docstring for the object. For example: 'g.app?' shows the docstring for g.app. This doesn't work (yet) directly for Python globals, but '__builtin__.f?' does. Example: '__builtin__.pow?' shows the docstring for pow.

Autocompletion works in the Find tab; you can use <Tab> to cycle through the choices. The 'Completion' tab appears while you are doing this; the Find tab reappears once the completion is finished.

Calltips

Calltips appear after you type an open parenthesis in code. Calltips shows the expected arguments to a function or method. Calltips work for any Python function or method, including Python's global function. Examples:

1. 'g.toUnicode(' gives 'g.toUnicode(s, encoding, reportErrors=False'
2. 'c.widgetWantsFocusNow' gives 'c.widgetWantsFocusNow(w'
3. 'reduce(' gives 'reduce(function, sequence[, initial]) -> value'

The calltips appear directly in the text and the argument list is highlighted so you can just type to replace it. The calltips appear also in the status line for reference after you have started to replace the args.

Options

Both autocompletion and calltips are initially enabled or disabled by the enable_autocompleter and enable_calltips settings in leoSettings.leo. You may enable or disable these features at any time with these commands: enable-auto-completer-command, enable-calltips-command, disable-auto-completer-command and disable-calltips-command.

## Cloning nodes

A cloned node is a copy of a node that changes when the original changes. Not only are changes maintained across all the the clones of a node, changes to its offspring (children, grandchildren, etc). are simultaneously made to the corresponding offspring of all of those clones. A small red arrow in the icon box marks cloned nodes. There is no real distinction between the "original" node and any of its clones. This makes it possible to update any of the clones and the original node will change as well. A cloned nodes becomes a regular node again when its penultimate clone is deleted. Clones are useful for making alternate views of a program. See Clones and views for full details.

## Creating and destroying nodes

The `Insert Node` command inserts a new node into the outline. The `Delete Node` command deletes a node and all its children.

## Creating and destroying multiple body editors

Three commands in the Cmds:Body Editors menu allow to create and destroy separate editors in the body pane. The Add Body Editor (add-editor) command adds a new editor in the body pane. The Delete Body Editor (delete-editor) command deletes the presently selected editor, The Change Body Editor (cycle-editor-focus) command cycles focus between editors in the body text.

## Cutting, pasting and deleting nodes

The `Cut Outline`, `Paste Outline`, `Copy Outline` and `Delete Outline` commands work on nodes rather than text. For example, to delete a node, select the node and choose the `Cut Outline` or `Delete Outline` command. The `Cut Outline` and `Copy Outline` commands copy a text representation of the outline to the clipboard. This representation is the same as Leo's .leo file format with some information deleted. You may copy this text representation into a body pane (or into any other text editor) using the `Edit:Paste` command.

Warning: In practice, it is almost always wiser to move clones rather than cutting or pasting them. Cutting and pasting outlines preserves clones, but the links between clones only exist within the part of the outline that was pasted. Therefore, if you are cutting and pasting an outline containing clones it is best to cut and paste the entire outline. Alternatively, you can paste part of an outline, then delete all clones.

## Dragging nodes

You may drag an node (including all its descendants) from one place to another in an outline. To start a drag, press the main (left) mouse button while the cursor is over the icon for a node. The cursor will change to a hand icon. If you release the mouse button while the hand cursor is above the icon for another node, Leo will move the dragged node after that node. If you release the mouse button when the hand cursor is not over an icon, Leo will leave the outline pane as it is. Leo scrolls the outline pane as the result of mouse-moved events, so to continue scrolling you must keep moving the mouse.

## Editing body text

Leo auto indents unless `@nocolor` is in effect. Typing a newline automatically inserts the same leading whitespace present on the previous line. If Python is the present language, Leo inserts an additional tab if the previous line ends with a colon.

The default features of Leo's body text derive from the Tk.Text widget, described at: http://www.tcl.tk/man/tcl8.3/TkCmd/text.htm Not all these features are found on all platforms. The following features are derived from the Tk Text widget. Some default behaviors have been changed because they conflict with other Leo features.

- Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.
- Double-clicking mouse button 1 selects the word under the mouse and positions the insertion cursor at the end of the word.
- The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed.
- Clicking mouse button 1 with the `Control` key down will reposition the insertion cursor without affecting the selection.
- Normal printing characters are inserted at the point of the insertion cursor.
- If the mouse is dragged out of the body pane while button 1 is pressed, the entry will automatically scroll to make more text visible.
- `Left Arrow` and `Right Arrow` move the cursor one character to the left or right and clear any selection in the text.
- `Shift Left` or `Shift Right` move the cursor and extend the selection.
- `Control-Left` and `Control-Right` move the insertion cursor by words, and `Control-Shift-Left` and `Control-Shift-Right` move the insertion cursor by words and also extend the selection.
- `Up Arrow` and `Down Arrow` move the insertion cursor one line up or down and clear any selection in the text.
- `Shift Up` and `Shift Right` move the cursor and extend the selection.
- `Control-Up` and `Control-Down` move the insertion cursor by paragraphs.
- `Control-Shift-Up and ``Control-Shift-Down` move the insertion cursor by paragraphs and extend the selection. `Control-p` and `Control-n` behave the same as `Up` and `Down`, respectively. Note: by default, Leo binds `Control-p` and `control-n` to commands.
- `Next` (`Page Down`) and `Prior` (`Page Up`) keys move the insertion cursor one screen and clear any text selection.
- `Shift Next` and `Shift Prior` move the cursor one screen and extend the selection.
- Line movement is by text lines terminated by hard returns (newlines), not by displayed lines; if a text line is long and wraps across more than one display line, then the `Up` and `Down` movement will skip the extra wrapped display lines.
- `Home` moves the insertion cursor to the beginning of its line and clears any selection in the widget.
- `Shift-Home` moves the insertion cursor to the beginning of the line and extends the selection.
- `End` moves the insertion cursor to the end of the line and clear any selection in the widget.
- `Shift-End moves` the cursor to the end of the line and extends the selection.
- `Control-Home` moves the insertion cursor to the beginning of the text and clears any selection in the widget.
- `Control-Shift-Home` moves the insertion cursor to the beginning of the text and extends the selection.
- `Control-End` moves the insertion cursor to the end of the text and clears any selection.
- `Control-Shift-End` moves the cursor to the end of the text and extends the selection.
- `Select` and `Control-Space` set the selection anchor to the position of the insertion cursor. They don't affect the current selection.
- `Shift-Select` and `Control-Shift-Space` adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was no previous selection.
- `Control-/` selects the entire contents of the widget.
- `Control-\` clears any selection in the widget.
- `F16` (`Copy` on many Sun workstations) or `Control-c` copies the selection in the widget to the clipboard, if there is a selection.
- `F20` (`Cut` on many Sun workstations) or `Control-x` copies the selection in the widget to the clipboard and deletes the selection. These keys have no effect if no text is selected.
- `F18` (`Paste` on many Sun workstations) or `Control-v` inserts the contents of the clipboard at the position of the insertion cursor.
- `Delete` deletes the text selection, or the character to the right of the cursor if there is no text selection.
- `Backspace` deletes the selection, or character to the left of the cursor if there is no text selection.

## Expanding & contracting nodes

You can expand or contract a node by clicking in the standard Windows Tree View icon to the left of the status icon. Expanding a node shows its immediate children; contracting a node hides all its children. The `Expand All Subheads` command expands all of a nodes offspring (children, grandchildren, etc.)

## Indenting body text automatically

Leo auto indents body text following colons when `@language Python` is in effect. When the `smart_auto_indent` setting is True, Leo uses Emacs-style auto-indentation instead. This style of auto-indent aligns newly created lines with unmatched `(` `[` or `{` brackets in the previous line.

## Marking nodes

You can mark nodes in several ways:

- With the `Mark` commands.
- With the `Find` or `Change` commands.
- With the `Untangle` command.

The `Go To Next Marked` command selects the next marked node, if any. The `Mark` command unmarks the selected headline if it is already marked.

## Moving & Reorganizing nodes

The `Move Up`, `Move Down`, `Move Left` and `Move Right` commands move the currently selected node. The `Promote` command makes all the children of a node siblings of the node. The `Demote` command makes all following siblings of a node children of the node.

You can cut and paste any part of a tree. If a node contains selected text, the cut, copy, clear or paste operation affects only the selected text. Otherwise, the cut, copy, clear or paste operations acts on the node and all nodes contained by it. For example, you can move a node by cutting it, selecting another location in the outline and pasting the node in the new location.

Warning: In practice, it is almost always wiser to move clones rather than cutting or pasting them. Cutting and pasting outlines preserves clones, but the links between clones only exist within the part of the outline that was pasted. Therefore, if you are cutting and pasting an outline containing clones it is best to cut and paste the _entire_ outline. Alternatively, you can paste part of an outline, then delete all clones.

## Navigating through the outline

Leo has many commands that select nodes in the outline. These commands can be found in the Outline:Go To menu.

When focus is in the outline Pane, you can move to from node to node by typing the first letter of a headline. For example, typing 'a' will go to the next visible headline that starts with either 'a' or 'A', wrapping around to the start of the outline if needed. Typing an uppercase 'A' will go to the next headline that starts with 'a' or 'A', making the node visible (expanding its ancestors) if the node was not visible.

When keystrokes (in the outline pane) are typed 'close' together in time Leo first looks for prefix + ch, where ch is the character just typed and prefix is the previous match. The term 'close together' is defined by the setting:

@float outline_nav_extend_delay = 2.0

The outline nav search reverts to a single-character search if the extended search fails, so in fact the delay is not too significant. In practice everything works well without thinking about what is happening.

## Opening URL's automatically

Double-clicking the icon box of a node whose headline has the form:

    @url <any url>

executes the url in your default web browser.

Leo checks that the url is valid before doing so. A valid url is:

- 3 or more lowercase alphas
- followed by one `:`
- followed by one or more of:
- `$%&'()*+,-./0-9:=?@A-Z_a-z{}~`
- followed by one of: `$%&'()*+/0-9:=?@A-Z_a-z}~`

Url's should contain no spaces: use `%20` to indicate spaces. You may use any type of url that your browser supports: http, mailto, ftp, file, etc.

## Resizing panes

You can change the relative sizes of the outline and body panes by dragging the splitter bar. The `Equal Sized Panes` command resizes the panes so that each fills half of the main window.

## Undoing operations

Leo supports unlimited undo for all typing and all commands. The 'undo_granularity' setting controls the granularity of undo. There are four possible values:

`node`
  Starts a new undo unit when typing moves to a new node.
`line` (default)
  Starts a new undo unit when typing moves to new line.
`word`
  Starts a new undo unit when typing starts a new word.
`char` (not recommended)
  Starts a new undo unit for each character typed. This wastes lots of computer memory.

`setUndoTypingParams` calls `recognizeStartOfTypingWord` to recognize the start of words. Plugins can modify `recognizeStartOfTypingWord`. It should return `True` if the typing indicated by the params starts a new 'word' for the purposes of undo with 'word' granularity. `setUndoTypingParams` calls this method only when the typing could possibly continue a previous word. In other words, undo will work safely regardless of the value returned. See the actual code for `recognizeStartOfTypingWord` for more details.

## Using chapters

Chapters are regions of a Leo outline whose root is an @chapter node. @chapter nodes may appear anywhere in an outline, but the create-chapter command (see below) creates @chapter nodes as children of the first @chapters node in the outline.

Selecting a chapter shows only then nodes in the selected chapter; in this respect, chapters are like hoists. The main chapter represents the entire outline and can not be deleted by name. When chapters are in effect, Leo creates a hidden @chapters node containing one @chapter node for every chapter except the 'main' chapter.

Associated settings:

- The @bool use_chapters setting determines whether chapters are enabled.
- The @bool use_chapter_tabs setting determines whether the chapters pop-up menu appears in the icon area. Choosing a chapter name from this list selects a chapter.

When chapters are enabled, the Cmds:Chapters menu shows all available chapter commands:

- The create-chapter command creates an @chapter node and with a single node.
- The delete-chapter command deletes the presently selected chapter.
- The select-chapter command makes only the nodes of the selected chapter visible.
- The move-node-to-chapter, clone-node-to-chapter and copy-node-to-chapter commands add a node (and its descendants) to another chapter.