.. @+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.12186: *3* @rst-ignore-node DO NOT SORT THESE HEADLINES
I've ordered these sections in approximate ascending complexity of concepts and descending importance.
.. @+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.

When using the Tk GUI and focus is in the outline Pane, you can move 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 in seconds 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.

This character search navigation is not currently implemented for the Qt interface.
.. @+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 (also when using
the Tk gui), 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.
.. @+node:EKR.20040524104904.36: *4* Creating and destroying nodes
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.
.. @+node:EKR.20040524104904.37: *4* Cutting, pasting and deleting nodes
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.
.. @+node:EKR.20040524104904.44: *4* Moving & Reorganizing nodes
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.
.. @+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 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.
.. @+node:EKR.20040524104904.43: *4* Marking nodes
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.
.. @+node:EKR.20040524104904.38: *4* Dragging nodes
In the Tk GUI, 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.

This is not yet implemented in the (default) Qt GUI.
.. @+node:sps.20100710110337.12188: *3* @rst-no-head Body Related
.. @+node:EKR.20040524104904.39: *4* Editing body text
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. 

-   Tk GUI only: clicking mouse button 1 with the Control key down will reposition the insertion
    cursor without affecting the selection. 

-   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.
  Currently, this works in Qt, but a bug in Tk prevents it from functioning correctly in that GUI.

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
