This chapter tells how to use Leo's outlines.
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:
- 'g.toUnicode(' gives 'g.toUnicode(s, encoding, reportErrors=False'
- 'c.widgetWantsFocusNow' gives 'c.widgetWantsFocusNow(w'
- '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.
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.
The Insert Node command inserts a new node into the outline. The
Delete Node command deletes a node and all its children.
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.
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.
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.
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.
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.)
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.
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.
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.
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.
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.
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.
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.
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.
