<type>documentation</type>
<domain>edit</domain>
<id>snippets</id>
<title>Code Snippets</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Wing Pro's `Snippets <script:show-panel-snippets>`__ tool makes it easy to write code that
contains commonly reused fragments required by coding standards or commenting and
documentation conventions.

Snippets may contain arguments to collect when they are placed into the editor and they may
be defined for specific file types or even specific contexts within a file, for example
within a ``class`` definition or inside a string.

Snippets are invoked by name from the editor's `auto-completer <ref:edit/auto-completion>`__
or from the key bindings assigned in the ``Snippets`` tool.  If a snippet contains 
arguments, they are collected inline in the editor, in a data entry mode.

Although Wing comes with example snippets, in most cases you will want to define your own,
to match your coding conventions and preferences.

Snippets Tool
-------------

The ``Snippets`` tool in the ``Tools`` menu is used to create, edit, delete, and manage
snippets.

The option drop down in the top right of the ``Snippets`` tool (also accessible by
right-clicking on the tab area) provides items for adding, removing, and renaming file
types into which to organize snippets. The name of the file type is the file extension
that Wing should use by default when creating a new file based on a snippet, for example
``py`` for Python. The file extension is converted to a mime type internally so that its
snippets can also be used in files that use a different valid file extension for the same
mime type. The ``*`` file type, which is always present, allows defining snippets that can
be applied to all file types.

To add, edit, rename, copy, and remove snippets, use the items in the context menu that
appears when you right-click on the ``Snippets`` tool.

When a snippet is created, it is added to the currently selected file type, and the
snippet definition file will be opened into the editor. See `Snippet Syntax 
<ref:edit/snippet-syntax>`__ for details on how to write snippets.

Contexts
........

Variants of snippets may be defined for different contexts. For example, ``def`` may omit
or include ``self`` depending on whether it is defining a function or a method in a
class. The default set of snippets that ship with Wing illustrate this feature with the
``def`` and ``class`` snippet variants for Python.

The set of valid contexts depends on file type. For Python files the valid context names
are ``module``, ``class``, ``method``, ``function``, ``comment``, and ``string``. For HTML
and XML, files are divided into ``content``, ``code`` (within ``<`` and ``>``),
``comment``, and ``string``. Other files only distinguish ``code``, ``comment``, and
``string``. The context ``all`` is used for all file types to indicate any context.

The context for a snippet is changed by right-clicking on the item or clicking on the
``Context`` column to select a different value.

Key Bindings
............

The right-click context menu menu on the ``Snippets`` tool also allows assigning key
bindings to snippets. To enter a key binding, just press the desired binding while focus
is in the ``Key binding`` field. Bindings can consist of multiple parts, such as ``Ctrl-H
B``. Pressing multiple keys will create a key binding sequence, unless too much time
elapses between the key presses. To reset the value to blank (no key binding), select all
text and press ``Backspace`` or ``Delete``.

Key bindings are assigned to the snippet by name and not to a particular snippet file. If
multiple like-named snippets exists for different file types or contexts, the snippet that
matches the current editor context is chosen.

Execution and Data Entry
........................

The easiest way to invoke snippets is from the auto-completer. Alternatively, they can be
invoked by their assigned key bindings (if any), by double clicking on the ``Snippets``
tool, or from the right-click context menu in the ``Snippets`` tool.

When snippets are invoked, Wing chooses the snippet by name and places the correct variant
according to the file type and the context within the current editor.  If no context
is matched, the snippet for context ``all`` is used.  The caret position
on the editor is used to determine the context, so altering the position of the caret
within leading indentation may alter which snippet variant Wing selects.

When placing a snippet into the editor, Wing will insert any default arguments, convert
indentation and line endings to match the target file, and place the editor into inline
data entry mode to collect additional arguments for the snippet.

In data entry mode, Wing moves between the fields in the snippet when ``Tab`` or
``BackTab`` are pressed. The position within the snippet's fields will be displayed in the
status area at the bottom of the editor window.

While in data entry mode, the ``Indent`` and ``Outdent`` commands in the ``Indentation``
sub-group of Wing's ``Source`` menu (and their key equivalents) can be used to increase or
decrease the indentation of the whole snippet within the editor. However, the same snippet
variant that was used initially will be used regardless of whether changes in indentation
also change the context in the editor, for example from ``method`` to ``function``.

To exit data entry mode, press ``Esc`` (or ``Ctrl-G`` in ``Emacs`` mode) or move the caret
outside of the pasted snippet. To undo the snippet insertion, use ``Undo`` in the ``Edit``
menu or its key binding.

Scripting Snippets
------------------

Wing's extension API exposes the editor's data entry mode and snippet processing
capabilities. This can be used to write Python scripts that generate snippets and paste
them into the editor for user data entry. This approach allows for more complex logic
than `Snippet Syntax <ref:edit/snippet-syntax>`__ supports.

For details, see the ``PasteSnippet`` and ``StartDataEntry`` methods in ``wingapi.py`` and
refer to `Scripting and Extending Wing <ref:scripting/index>`__.

