Chapter 3: Using Leo's Outlines

This chapter tells how to create and use Leo's on-screen outlines.  Unless otherwise mentioned, everything in this chapter applies to both leo.py and the Windows version of Leo.

Creating and deleting headlines
Expanding and contracting headlines
Moving, dragging and reorganizing headlines
Marking headlines
Opening URL's automatically
Cloning headlines
Resizing panes

Leo's main window is shown below. As you can see, it contains two panes, an outline pane on top and a body pane on the bottom. You can change the relative sizes of the panes by dragging the separator between the two panes.

The outline pane contains a set of headlines indicating the organization of your program. The outline pane works like Windows Explorer; headlines expand and contract when you click the + or - icon.

Associated with each headline is body text. The body pane always shows the body text of the currently selected headline. Text in the body pane is always word-wrapped. Body text is joined to its headline and moves with it. You can edit the body text as usual and you can copy, cut or paste text between headlines and body text.

The terminology of trees applies to outlines. See the Glossary for complete definitions. The combination of a headline and its headline and body text is called a node, so an outline is made up of nodes.

The indentation of a headline shows its position relative to other headlines. The root headline appears at the left margin of the outline pane. The root's children are indented one unit from the left margin. The grandchildren of the root are indented two units from the left margin, and so on.

Each headline contains a status box icon just to the left of the text of the headline. The status box icon contains a small body text box appears just to the left of a leader character if the node contains body text.

Creating and deleting headlines

The Insert Node command inserts a new headline into the outline. The return key inserts a new headline into the outline if the outline pane is the active pane. Otherwise, the return key inserts a newline into the body pane.

You can delete a headline and all its children with the Delete Node command.

Expanding & contracting headlines

Double-click the + or - icon to the left of a node's headline's text to expand or contract the node. Expanding a node shows its immediate children; contracting a node hides all its children. The Expand All Subheads command expands all a nodes offspring (children, grandchildren, etc.).

Moving, dragging & reorganizing headlines

There are a number of ways to move and reorganize headlines.

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

You can cut and paste any part of a tree. If a headline 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 headline by cutting it, selecting another location in the outline and pasting the headline 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.

New in leo.py 2.4: You may drag an node (including all its descendents) 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 print "not moved" and leave the outline pane as it is. This can result in the dragged node not being visible on the screen, but it seems less alarming not to force the current node to become visible as that would undo any scrolling that has just been done.

New in leo.py 3.0: If you drag outside the outline pane, the outline pane will scroll automatically.

Note 1: Leo scrolls the outline pane as the result of mouse-moved events, so to continue scrolling you must keep moving the mouse.

Note 2:  You may not move a node to the first child of another node unless that node is already expanded. I experimented with automatically open nodes when the cursor moves over an unexpanded node with children. However, this was confusing and alarming. It seems best to expand and contract nodes explicitly.

Marking headlines

You can mark headlines in several ways: with the various Outline:Mark commands, with the Find or Change commands, or with the Untangle command. The "Go To Next Marked" command will go to the next marked node, if any.

The Mark command will unmark the selected headline if it is already marked.

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:

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.

Cloning headlines

A cloned node is a copy of a node that changes when the original changes. Changes to the children, grandchildren, etc. of a node are simultaneously made to the corresponding nodes contained in all cloned nodes. Clones are marked by a small arrow by its leader character.

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. When the second-to-last cloned node is deleted the last cloned node becomes a regular node again.

Clones are useful for making alternate views of a program. For example, when I begin to fix a bug I clone all the sections of the code that relate to the bug, and place those cloned sections under a new headline whose name is the name of the bug I am fixing.

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.py supports unlimited undo in both the outline and body panes.

The Widows version of Leo supports one level of undo in the outline pane and unlimited undo in the body pane. However, you can not undo an operation affecting body text after selecting a new headline. You can undo or redo the last operation involving the outline itself. You can not undo operations affecting headline text.