<type>documentation</type>
<domain>edit</domain>
<id>auto-completion</id>
<title>Auto-completion</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

Wing provides context-appropriate code completion in the
~~~if WINGPRO:
editor, `Python Shell <ref:debug/python-shell>`__ and `Debug Console
<ref:debug/debug-console>`__.
~~~
~~~if not WINGPRO:
editor and `Python Shell <ref:debug/python-shell>`__.
~~~
Using the auto-completer decreases the amount of typing needed to write code, and reduces the 
incidence of typos in symbol names.
~~~if WING101 or WEBSITE:
In Wing 101, this feature is disabled by default.
~~~

When enabled with the `Editor > Auto-completion > Auto-show Completer 
<script:show_preferences_gui#prefname="edit.autocomplete-autoshow-option">`__ 
preference, the auto-completer appears and disappears automatically as you type.  
Items can be selected by typing until the correct symbol is highlighted, or
by using the up and down arrow keys.

To cancel out of the auto-completer, press ``Esc`` or ``Ctrl-G``. The auto-completer also
disappears when you exit the source symbol by typing or clicking elsewhere, or if you
press key bindings to invoke other commands.

**Completion Keys**

By default, ``Tab`` enters the completion it into the editor.  Other completion
keys can be added with the `Editor > Auto-completion >
Completion Keys <script:show_preferences_gui#prefname="edit.autocomplete-keys">`__
preference.  For printable keys such as ``'.'``, ``'('``, ``'['``, and ``':'`` the completion
~~~if WINGPRO:
character will be added to the editor after the completed symbol, and any appropriate
`auto-editing <ref:edit/auto-editing>`__ operations will be applied. 
~~~
~~~if not WINGPRO:
character will be added to the editor after the completed symbol.
~~~
If ``'.'`` is used as a
completion key, the auto-completer will reappear immediately with the attributes of the
completed symbol.

~~~if WINGPRO:
In Wing Pro, it is also possible to configure the auto-completer in Python code
to treat any non-symbol key as a completion key.  See `Turbo Completion Mode for Python 
<ref:edit/turbo-completion>`__ for details.
~~~

~~~if not WING101:
**Configuration**

In Wing Pro and Wing Personal, the auto-completer offers a wide range of configuration
options. These are available in the ``Editor > Auto-completion`` preferences group.  The
more commonly used options include:

* `Auto-show completer <script:show_preferences_gui#prefname="edit.autocomplete-autoshow-option">`__ 
  controls whether the completer is shown immediately, only after a specified number of characters,
  or entirely disabled.

* `Only Show Matching Symbols <script:show_preferences_gui#prefname="edit.filter-all-symbols-in-autocompleter">`__
  is used to control whether the completer shows all available symbols in the current
  context, or only those that match the fragment you have typed into the editor.

* `Symbol Types <script:show_preferences_gui#prefname="edit.autocompleter-symbol-types">`__
  controls whether to show also snippets, builtins, keywords, or __names__ in the 
  auto-completer.

* `Auto-completer Height <script:show_preferences_gui#prefname="edit.autocompleter-height">`__ 
  controls how lines of completions are shown at once in the auto-completer.
~~~

Other options are available for delaying display of the completer, auto-hiding the
completer after a timeout, controlling whether existing symbols are replaced by
completions, whether symbol matching is case insensitive, and how the completer works in
non-Python files.

~~~if WINGPRO:
**Auto-Imports**

In Wing Pro, the auto-completer can be configured to include the names of modules that
could be but have not yet been imported. When these choices are completed, Wing places the
name at the current position in the editor and also automatically adds the necessary
``import`` statement at the top of your source file.

A single ``Undo`` will remove the completion and the import, if it was entered in error.
The import may also be removed using the `Import Tool <ref:refactoring/imports-tool>`__
if the code that used it is deleted after other edits are made to the file. 

When and how auto-import items are added to the auto-completer is controlled by the
following preferences:

* `Editor > Auto-Completion > Python Auto-Imports <script:show_preferences_gui#prefname="edit.add-auto-imports-to-autocompleter">`__ 
  selects whether to include auto-import items in the auto-completer, either always, never, 
  on request for the current completion only (the default), or on request until disabled.
  
* `Editor > Auto-Completion > Only Show Matching Auto-Imports <script:show_preferences_gui#prefname="edit.filter-auto-imports-in-autocompleter">`__
  controls whether to include all possible auto-imports or only those that match the currently typed fragment
  for which the completer is being snow.

See also the `Import Tool <ref:refactoring/imports-tool>`__.
~~~

~~~if WINGPRO:
**Code Snippets**

In Wing Pro, the auto-completer also contains the names of snippets defined in the
`Snippets <script:show-panel-snippets>`__ tool. Completing a snippet enters it into the
editor and collects any snippet arguments inline in the editor, in fields that can be
traversed with the ``Tab`` key. For details, see `Snippets <ref:edit/snippets>`__.

To prevent Wing from including snippets in the auto-completer, uncheck ``Snippets``
in the `Editor > Auto-completion > Symbol Types
<script:show_preferences_gui#prefname="edit.autocompleter-symbol-types">`__ preference.
~~~

