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.
Leo has many commands that select nodes in the outline. These commands can be
found in the Outline:Go To menu.
As described in the tutorial, you can move about the outline by clicking on the
headlines or using Alt+arrow keys.
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.
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.
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.
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.
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.
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.
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.
- 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.
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.
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.
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.
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.
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.
Double-clicking the icon box of a node whose headline has the form:
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.
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.
