back leo next

Chapter 3: Using Outlines

This chapter tells how to use Leo's outlines.

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.

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.

back leo next