Using Outlines

This chapter tells how to use Leo’s outlines. Most of the commands can be invoked by clicking with the pointer in the outline pane or by using the pointer to select the command from the Outline menu. The key bindings mentioned here are those of the default EKR bindings.

Expanding & contracting nodes

You can expand or contract a node by clicking in the tree view icon to the left of the headline. The icon in the Qt gui matches the native OS’s tree view icon, i.e. for Mac’s, a triangle pointing right or down; on Windows, a square containing a plus or minus. Expanding a node shows its immediate children; contracting a node hides all its children. The corresponding commands are expand-node and contract-node. For more convenient navigation, there are expand-and-go-right and contract-or-go-up which are bound to Alt-Right and Alt-Left.

The expand-all command expands every node in the outline. contract-all contracts every node in the outline. Both commands are available in the Outline->Expand/Contract... submenu. contract-all is bound to Alt– (Alt modifying a single hyphen). In all but the smallest outlines, expand-all is rarely used, and is does not have a key binding.

Creating and destroying nodes

The insert-node command inserts a new node into the outline; it is bound to Control-I and the Insert key. When invoked, (from any pane), it inserts a new node below the presently selected node, and at the same level as that node, or at the child level if it has a visible child. The delete-node command deletes a node and all its children; it is initially unbound. If you want to retain the children you must promote all the children before you do the delete.

Cutting, pasting and deleting nodes

The cut-node, paste-node, copy-node and delete-node 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 in the menu, use Alt-X to invoke the command in the mini-buffer, or use Control-Shift-X (which cuts the node; delete node is not bound). The cut-node and copy-node 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 Edit->Paste in the menus, Ctrl-V, or Alt-X paste-text.

Warning: If you want to preserve the “cloned” attribute of a node, or want to paste the node as a clone of the node you cut or copied, use the past-retaining-clones command, which in the Outline menu is called “Paste Node as Clone”. The paste-node command instead creates a new, distinct version of the node you previously cut or copied, though if there were descendant nodes which were clones of each other, the new version will have parallel, distinct nodes that are also clones of each other (just not of the originals). You may paste a node between .leo files, but there can be no clone relationship across files.

There are places to which you are prevented from paste-retaining-clones, because it would cause a node to become a parent of itself, and thus cause outline traversals like @file expansion to loop until they consumed all memory and crashed the program. The Leo outline is thus mathematically a directed acyclic graph: clones make it more flexible than a tree, but not a generalized graph.

Moving & Reorganizing nodes

The move-outline-up, move-outline-down, move-outline-left, and move-outline-right commands move the currently selected node. In the Outline->Move... menu, they’re called Move Up, Move Down, Move Left and Move Right; they’re bound to Control-U, Control-D, Control-L and Control R. 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. These are also found in the Outline->Move... menu, and are bound to Control-Shift-[ and Control-Shift-] .

Nodes moved in the above manner retain any clone characteristics. Moves are limited to retain the directed acyclic graph property.

Cloning nodes

A cloned node is a copy of a node that changes when the original changes. One may also think of it as a single node that is hooked into the outline at multiple positions. Because that single node brings along all its descendants, changes are maintained across all the the clones of a node, along with changes to its offspring (children, grandchildren, etc.), i.e., any changes are simultaneously made to the corresponding offspring of all of those clones. A small red arrow in the icon box marks cloned nodes. You can think of the arrow as pointing out that there are other paths to get to this same node. There is no real distinction between the “original” node and any of its clones. Any headline or body update of a clone headed subtree affects all of its clones simultaneously. A cloned node becomes a regular node whenever deletion of its other clones makes it the only one left. Clones are useful for making alternate views of a program. See Clones and views for full details.

The command clone-node, (Clone Node in the Outline menu, bound to Control-`) creates a clone as the immediate sibling of a selected node. You have to place it where you want it by either using move commands, or cutting and paste the clone.

Marking nodes

You can mark nodes in several ways:

  • With the Mark commands: mark, mark-changed-items, mark-subheads. These are found in the Outline->Mark... submenu; mark is bound to Control-M .
  • With the Find or Change commands. The “mark changes” and “mark finds” options are initially cleared; you can change them with the toggle-find-mark-changes-option and toggle-find-mark-finds-option commands. Using those commands will put focus in the Find tab of the log pane. When the Find tab is visible, Alt in combination with the underlined option character will put focus on that option, and then the space bar will toggle the option. You can also change the options by clicking on them in the Find tab.

The goto-next-marked command selects the next marked node, if any; it is available in the Outline->Go to... submenu.

The mark command unmarks the selected headline if it is already marked.

Dragging nodes

You may drag a 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

  • 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.
  • If there is no selection, normal printing characters are inserted at the point of the insertion cursor.
  • If there is a selection, normal printing characters replace the selection.
  • 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 modify 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.
  • 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 clears 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.
  • 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 the character to the left of the cursor if there is no text selection.

Indenting body text automatically

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

Creating and destroying multiple body editors

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

There is a single body editor focus which determines which body editor shows the content of the selected outline node and which allows that node to be edited; other body editors continue to show the node contents they last had when they had the body editor focus.

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:

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

Internally, 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.

Resizing panes

You can change the relative sizes of the outline and body panes by dragging the splitter bar. The equal-sized-panes (Window->Equal Sized Panes) command resizes the panes so that each fills half of the main window.

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}~ (i.e., comma, hyphen and open curly brace may not be the last character)

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.

Using chapters

Chapters are regions of a Leo outline whose root is an @chapter node. They are available in an outline if the @bool usechapters option is True. @chapter nodes may appear anywhere in an outline, but the create-chapter command (see below) creates @chapter nodes as children of the first @chapters (note the s) node in the outline.

One selects a chapter with the select-chapter command, after which Leo shows only the 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 an @chapters node for the use of create-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 chapter-create command creates an @chapter node and populates it with a single node.
  • The chapter-remove command deletes the currently selected chapter.
  • The chapter-select command prompts for a chapter name and makes only the nodes of the selected chapter visible.
  • The chapter-move-node-to, chapter-clone-node-to and chapter-copy-node-to commands prompt for a chapter name and add the currently selected node (and its descendants) to another chapter.