Basics of Leo¶

Command names¶

Every Leo command has a command name. In this document, keystrokes that invoke a command will be followed by the command name in parentheses. For example, Ctrl-S (save-file) saves a Leo file.

Alt-X (full-command)

Executes any other command by typing its full name. For full details see The minibuffer & completions.

Leo’s main window¶

Here is a slightly reduced screenshot of Leo’s main window:

Leo’s main window consists of an icon area just below the menus, an outline pane at the top left, a log pane at the top right, a body pane at the bottom left, and an optional viewrendered pane at the bottom right. The minibuffer and status line lie at the bottom of the main window.

The log pane contains several tabs. The Log tab shows messages from Leo, the Find Tab shows the status of Leo’s Find/Replace commands. Other tabs may also appear in the log pane: The Spell Tab controls Leo’s spell-checking. The Completion Tab shows available typing completions.

Leo stores all data in nodes. Nodes have headlines, shown in the outline pane, and body text. The body pane shows the body text of the presently selected node, the node whose headline is selected in the outline pane. Headlines have an icon box indicating a nodes status. For example, the icon box has a black border when the node has been changed.

File operations & sessions¶

Here are Leo’s basic file commands:

Ctrl-N (new)

Creates a new outline in a new tab.

Ctrl-O (open-outline)

Opens an existing .leo file.

Ctrl-S (save-file)

Saves the outline.

Ctrl-Q (exit-leo)

Exits Leo. Leo will prompt you to save any unsaved outlines.

A session specifies a list of tabs (.leo files) that Leo opens automatically when Leo first starts. When the --session-save and --session-restore command-line options are in effect, Leo will save session data on exit and will reload outlines when Leo restarts. For full details, see Using sessions in Leo’s Users Guide.

Switching focus¶

Here’s how to switch focus without using the mouse:

Alt-0 (vr-toggle)

Hides or shows the viewrendered pane.

Alt-T (focus-to-tree)

Puts focus in the outline pane, regardless of focus.

Ctrl-T (toggle-active-pane)

Toggles focus between the outline and body panes.

Ctrl-Tab (tab-cycle-next)

Switches between outline tabs. You may open multiple Leo outlines in different tabs within the same main window.

Ctrl-G (keyboard-quit)

Puts focus in the body pane. More effective than hitting Alt-Tab twice.

Operations on nodes¶

Ctrl-I or Insert (insert-node)

Inserts a new node into the outline.

Ctrl-H (edit-headline)

Begins editing the headline of the selected node.

Return

When focus is in the outline pane, <Return> ends editing (end-edit-headline) or switches focus to the body pane.

Ctrl-Shift-C (copy-node)

Copies the outline and all it’s descendants, placing the node on the clipboard.

Ctrl-Shift-X (cut-node)

Cuts the outline and all its descendants, placing the node on the clipboard.

Ctrl-Shift-V (paste-node)

Pastes a node (and its descendants) from the clipboard after the presently selected node.

Ctrl-M (mark)

Toggles the mark on a node. Marked nodes have a vertical red bar in their icon area.

Ctrl-} (demote)

Makes all following siblings of a node children of the node. Use demote to “gather” nodes so they can all be moved with their parent.

Ctrl-{ (promote)

Makes all the children of a node siblings of the node. Use demote to “scatter” the nodes after moving their parent.

Selecting outline nodes¶

You may select, expand and contract outline nodes with the mouse as usual, but using arrow keys is highly recommended. When focus is in the outline pane, plain arrows keys change the selected node:

Right-arrow (expand-and-go-right)

Expands a node or selects its first child.

Left-arrow (contract-or-go-left)

Contracts a node if its children are visible, and selects the node’s parent otherwise.

Up-arrow (goto-prev-visible)

Selects the previous visible outline node.

Down-arrow (goto-next-visible)

Selects the next visible outline node.

Regardless of focus, Alt-arrow select outline nodes:

Alt-Home (goto-first-visible-node)

Selects the first outline node and collapses all nodes.

Alt-End (goto-last-visible-node)

Selects the last visible outline node and collapses all nodes except the node and its ancestors.

Alt-arrow keys

Select the outline pane, and then act just like the plain arrow keys when the outline pane has focus.

Moving the cursor in text panes¶

When focus is in any of Leo’s text panes (body pane, log pane, headlines), Leo works like most text editors:

• Plain arrow keys move the cursor up, down, left or right.
• Ctrl-LeftArrow and Ctrl-RightArrow move the cursor by words.
• Home and End move the cursor to the beginning or end of a line.
• Ctrl-Home moves the cursor to the beginning of the body text.
• Ctrl-End moves the cursor to the end of the body text.
• PageDown and PageUp move the cursor up or down one page.

Note: As usual, adding the Shift key modifier to any of the keys above moves the cursor and extends the selected text.

The minibuffer & completions¶

Leo’s minibuffer appears at the bottom of Leo’s main window. You use the minibuffer to execute commands by name, and also to accumulate arguments to commands.

Alt-X (full-command) puts the cursor in the minibuffer.

You could type the full command name in the minibuffer, followed by the <Return> key to invoke the command, but that would be way too much work. Instead, you can avoid most typing using tab completion. With tab completion, there is no need to remember the exact names of Leo’s commands.

For example, suppose you want to print out the list of Leo’s commands. You might remember only that there are several related commands and that they all start with “print”. Just type <Alt-X>pri<Tab>

You will see print- in the minibuffer. This is the longest common prefix of all the command names that start with pri. The Completion tab in the log pane shows all the commands that start with print-.

Now just type c<Tab> You will see the print-commands command in the minibuffer.

Finally, <Return> executes the print-commands command. The output of the print-commands command appears in the commands tab, and focus returns to the body pane.

Very Important: Leo has hundreds of commands, but because of tab completion you do not have to remember, or even know about any of them. Feel free to ignore commands that you don’t use.

Opening files using filename completion

file-open-by-name

Prompts for a filename. This command completes the name of files and directories as in command completion. As a result, this command can be very fast. You may want to bind this command to Ctrl-O instead of the default open-outline command.

Command history:

Ctrl-P (repeat-complex-command

Repeats the last command entered by name in the minibuffer.

UpArrow (in the minibuffer)

Moves backward through command history. The first UpArrow is the same as Ctrl-P.

DownArrow (in the minibuffer)

Moves forward through command history.

Summary:

• <Return> executes the command.
• <Tab> shows all valid completions.
• <BackSpace> shows more alternatives.
• Ctrl-G exits the minibuffer and puts focus in the body pane.
• UpArrow and DownArrow in the minibuffer cycle through command history.

Finding & replacing text¶

This section explains how to use Leo’s standard search/replace commands. Note: you can also use the Nav Tab (in the Log pane) to search for text.

Ctrl-F (start-search) shows the Find Tab and puts the focus in the text box labeled Find:.

Aside: You can select radio buttons and toggle check boxes in the Find Tab with Ctrl-Alt keys. The capitalized words of the radio buttons or check boxes indicate which key to use. For example, Ctrl-Alt-X (toggle-find-regex-option) toggles the regeXp checkbox.

After typing Ctrl-F, type the search string, say def, in the text box.

Start the find command by typing <Return>.

But suppose you want to replace def with foo, instead of just finding def.

Just type <Tab> before typing <Return>. Focus shifts to the text box labeled Replace:.

Finally, type <Return> to start the find-next command. When Leo finds the next instance of def, it will select it.

You may now type any command. The following are most useful:

• Ctrl-minus (replace-then-find) replaces the selected text.
• F3 (find-next) continues searching without making a replacement.
• F2 (find-previous) continues the search in reverse.
• Ctrl-G (keyboard-quit) ends the search.

Undoing and redoing changes¶

Leo has unlimited undo–Leo remembers all changes you make to outline structure or the contents of any node since you restarted Leo.

Ctrl-Z (undo)

Undoes the last change. Another Ctrl-Z undoes the previous change, etc.

Ctrl-Shift-Z (redo)

Undoes the effect of the last undo, etc.

The first two entries of the Edit menu show what the next undo or redo operation will be.

Getting help¶

F1 (help)

Shows a help message appears in the viewrendered pane. Alt-0 (vr-toggle) hides or shows this pane.

F11 (help-for-command)

Shows the documentation for any Leo command. F11 prompts for the name of a Leo command in the minibuffer. Use tab completion to see the list of all commands that start with a given prefix.

F12 (help-for-python)

Shows the documentation from Python’s help system. Typing completion is not available: type the full name of any Python module, class, function or statement.

These commands clarify which settings are in effect, and where they came from:

print-bindings
print-settings

These commands discuss special topics:

help-for-abbreviations
help-for-autocompletion
help-for-bindings
help-for-creating-external-files
help-for-debugging-commands
help-for-drag-and-drop
help-for-dynamic-abbreviations
help-for-find-commands
help-for-minibuffer
help-for-regular-expressions
help-for-scripting
help-for-sessions

Using Leo, especially for programming, requires some learning initially. Please feel free to ask for help at any time.

Leo directives¶

Directives control Leo’s operations. Directives start with @ in the leftmost column.

Directives may appear either in headlines or body text.

When people speak of an @x node, they are implying that the headline starts with @x. If a node contains an @x directive (in the body pane), they will usually say something like, “a node containing an @x directive”.

Directives apply until overridden by the same (or related) directive in a descendant node.

Some commonly used general-purpose directives:

@color
@killcolor
@nocolor

These control whether to syntax color text.

Nodes may contain multiple color directives.

Nodes containing multiple color directives do not affect coloring of descendant nodes.

@language python
@language c
@language rest # restructured text
@language plain # plain text: no syntax coloring.

These control which language to use when syntax coloring text.

@pagewidth 100

Sets the page width used when formatting paragraphs.

@tabwidth -4
@tabwidth 8

Sets the width of tabs.

Negative tab widths cause Leo to convert tabs to spaces and are highly recommended for Python programming.

@nowrap
@wrap

These enable or disable line wrapping in the body pane.

Configuring Leo¶

Leo has a flexible (perhaps too flexible) configuration system. It’s best to use this flexibility in a restricted way as follows:

1. The file leo/config/leoSettings.leo contains Leo’s default global settings. Don’t change this file unless you are one of Leo’s developers.
2. The file ~/myLeoSettings.leo contains your personal settings. Leo will not create this file automatically: you should create it yourself. Settings in myLeoSettings.leo override (or add to) the default settings in leoSettings.leo.
3. Any other .leo file may also contain local settings. Local settings apply only to that file and override all other settings. It’s best to use local settings sparingly.

As a result, settings may vary from one Leo file to another. This can be confusing. These two commands can help:

• print-settings shows each setting and where it came from.
• print-bindings shows each key binding and where it came from.

Important: within any file, settings take effect only if they are contained in an @settings tree, that is, are descendants of a node whose headline is @settings. Nodes outside @settings trees do not affect settings in any way.

Within @settings trees, you specify boolean settings with @bool nodes, string settings with @string nodes, menus with @menus and @menu nodes, etc. For exact details, please do study leoSettings.leo. You can open either leoSettings.leo or myLeoSettings.leo from the Help menu. Within leoSettings.leo:

• The node About this file explains about settings.
• The node Candidates for settings in myLeoSettings.leo highlights the settings you are most likely to want to customize.

Plugins¶

Leo plugins are Python programs that extend what Leo can do.

Plugins reside in the leo/plugins folder.

Enable plugins by adding their file names in @enabled-plugins nodes in an @settings tree. The @enabled-plugins node in leoSettings.leo enables the recommended plugins.

Programmers have contributed dozens of plugins, including:

• bookmarks.py manages and shows bookmarks.
• contextmenu.py shows a context menu when you right-click a headline.
• mod_scripting.py supports @button and @command nodes.
• quicksearch.py Adds Nav tab for searching.
• todo.py provides to-do list and simple project-management capabilities.
• valuespace.py adds outline-oriented spreadsheet capabilities.
• viewrendered.py creates the rendering pane and renders content in it.

Creating external files with @file and @all¶

Leo stores outline data on your file system in .leo files.

Rather than storing all your data in the .leo file, you may store parts of your outline data in external files, files on your file system.

@file nodes create external files. @file nodes have headlines starting with @file followed by a file name:

@file leoNodes.py
@file ../../notes.text

Leo reads external files automatically when you open Leo outline, and writes all dirty (changed) external files when you save any Leo outline.

The @all directive tells Leo to write the @file tree (the @file node and all its descendants) to the external file in outline order, the order in which the nodes appear in the outline pane when all nodes are expanded. Non-programmers will typically use the @all directive; programmers typically use the @others directive, as discussed in the programming tutorial. The @all directive may appear anywhere in the body text of the root @file node.

The @all directivive is designed for “catch-all” files, like todo.txt or notes.txt or whatever. Such files are assumed to contain a random collection of nodes, so there is no language in effect and no real comment delimiters.

When writing @file nodes, Leo adds sentinel comments to external files. Sentinels embed Leo’s outline structure into external files. If you don’t want sentinels in your sources, skip head to the Using @clean nodes, part of Leo’s programming tutorial.

Summary¶

• Every command has a name.

• You may execute any command by name from the minibuffer.

• Many commands are bound to keystrokes.

• You may bind multiple keystrokes to a single command and change bindings to your taste.

  Note: All Ctrl-<number> keys and most Ctrl-Shift-<number> keys are
  unbound by default. You may bind them to whatever commands you like.

• Leo has commands to create, change and reorganize outlines.

• Within the body pane, Leo uses standard key bindings to move the cursor.

• Ctrl-F starts the find command. Use the minibuffer to complete the command.

• Leo’s configuration files specify all settings, including key bindings.

• Leo directives control how Leo works.

• @all creates an external file from all the nodes of an outline.

• Enable plugins using @enabled-plugins nodes in an @settings tree.