.. @+leo-ver=5-thin
.. @+node:ekr.20100805165051.7153: * @file outlines.txt
.. @@language rest
.. @@tabwidth -4

.. @+at @rst-options
..  call_docutils=False
..  code_mode=False
..  generate_rst=True
..  http_server_support = False
..  show_organizer_nodes=True
..  show_headlines=True
..  show_leo_directives=True
..  stylesheet_path=..\doc
..  write_intermediate_file = True
..  verbose=True
.. @@c

.. @+all
.. @+node:ekr.20050901101608: ** @rst html\outlines.html
##############
Using Outlines
##############

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.

.. contents::
    :depth: 2

.. @+node:ekr.20050901101608.1: *3* @rst-no-head links
.. _`A Tutorial Introduction to Leo`:   intro.html
.. _`Writing Programs in Leo`:          directives.html
.. _`Clones and views`:                 intro.html#clones-views
.. @+node:sps.20100710110337.12187: *3* @rst-no-head Outline Related
.. @+node:ekr.20060929040750: *4* Navigating through the outline
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.
.. @+node:EKR.20040524104904.40: *4* Expanding & contracting nodes
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`` (Alt-Right) and
``contract-or-go-up`` (Alt-Left) commands.

The ``expand-all`` command expands every node in the outline.
``contract-all`` (Alt-hypen) contracts every node in the outline. Both
commands are available in the Outline->Expand/Contract... submenu.
``contract-all`` In all but the smallest outlines, ``expand-all`` is rarely
used, and is does not have a key binding.
.. @+node:EKR.20040524104904.36: *4* Creating and destroying nodes
The ``insert-node`` (Ctrl-I or Insert) command inserts a new node into the
outline. 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.
.. @+node:EKR.20040524104904.37: *4* Cutting, pasting and deleting nodes
The ``cut-node`` (Ctrl-Shift-X) ``paste-node`` (Ctrl-Shift-V),
``copy-node`` (Ctrl-Shift-C) and ``delete-node`` commands work on nodes
rather than text. 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.

The ``paste-retaining-clones`` command is disabled if it would cause a node
to become a parent of itself. The Leo outline is thus mathematically a
*directed acyclic graph*: clones make it more flexible than a tree, but not
a generalized graph.
.. @+node:EKR.20040524104904.44: *4* Moving & Reorganizing nodes
The ``move-outline-up`` (Ctrl-U or Alt-Shift-Up), ``move-outline-down``
(Ctrl-D or Alt-Shift-Down), ``move-outline-left`` (Ctrl-L or
Alt-Shift-Left), and ``move-outline-right`` (Ctrl-R or Alt-Shift-Right)
commands move the currently selected node. **Important**: When focus is in
the outline pane, you can move nodes whithout adding the Alt modifier.
Shift-Up moves the select node up, etc.

The ``promote`` (Ctrl-[) command makes all the children of
a node siblings of the node. The ``demote`` (Ctrl-]) command makes all following
siblings of a node children of the node.
.. @+node:EKR.20040524104904.27: *4* Cloning nodes
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 ``clone-node`` (Ctrl-\`) command 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.
.. @+node:EKR.20040524104904.43: *4* Marking nodes
You can mark nodes in several ways:

- With the ``mark`` (Ctrl-M), ``mark-changed-items``, or ``mark-subheads``
  commands. The ``mark`` command unmarks the selected node if it is already
  marked.

- 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.
.. @+node:EKR.20040524104904.38: *4* Dragging nodes
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.
.. @+node:sps.20100710110337.12188: *3* @rst-no-head Body Related
.. @+node:EKR.20040524104904.39: *4* Editing body text
-   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.
.. @+node:EKR.20040524104904.41: *4* Indenting body text automatically
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.
.. @+node:ekr.20060920145745: *4* Creating and destroying multiple body editors
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.
.. @+node:sps.20100710110337.12189: *3* @rst-no-head Miscellaneous
.. @+node:EKR.20040524104904.48: *4* 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.

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.
.. @+node:EKR.20040524104904.47: *4* Resizing panes
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.
.. @+node:EKR.20040524104904.45: *4* 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}~`` (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.
.. @+node:ekr.20070623145346.2: *4* Using chapters
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.
.. @-all
.. @-leo
