<type>documentation</type>
<domain>edit</domain>
<id>the-tab-key</id>
<title>The Tab Key</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

The action of the tab key depends on the `Editor > Keyboard > Personality
<script:show_preferences_gui#prefname="edit.personality">`__ preference, the file type
being edited, and the position within the file. 

To insert a real tab character, press ``Ctrl-T``.

**Tab Key Action**

The behavior of the tab key can be altered with the `User Interface > 
Keyboard > Tab Key Action`__ preference, which provides the following options:

__ script:show_preferences_gui#prefname="edit.tab-key-action"

**Default for Personality** selects from the other tab key actions below, according to the current
`keyboard personality <ref:custom/keyboard-personalities>`__ and file type. In all
non-Python files, the default is ``Move to Next Tab Stop``. In Python files, the defaults
are as follows:

  ``Normal``: Smart Tab
  
  ``VI/VIM``: Move to Next Tab Stop
  
  ``Emacs``: Indent to Match
  
  ``Brief``: Smart Tab
  
  ``Visual Studio``: Move to Next Tab Stop
  
  ``OS X``: Smart Tab
  
  ``Eclipse``: Emulates Eclipse
  
  ``XCode``: Smart Tab
  
  ``MATLAB``: Insert Tab Character

**Indent to Match** indents the current line or selected lines to position them at the
computed indent level for their context in the file.

**Move to Next Tab Stop** enters indentation so that the caret reaches the next tab stop.

**Indent Region** increases the indentation of the current line or selected lines
by one level.

**Insert Tab Character** inserts a ``Tab`` character ``chr(9)`` into the file.

**Smart Tab** is equivalent to ``Move to Next Tab Stop`` in non-Python files, and
implements the following behavior in Python files:

  **(1)** When the caret is within a line or there is a non-empty selection, this
  performs ``Indent to Match``.  When the line or lines are already at the matching
  position, indentation is toggled between other valid positions.
  
  **(2)** When the caret is at the end of a non-empty line and there is no selection,
  one indent level is inserted. The `User Interface > Keyboard > Smart Tab End 
  of Line Indents <script:show_preferences_gui(prefname="edit.smart-tab-eol-indents")>`__ 
  preference alters the type of indentation used in this case, or disables this aspect
  of the ``Smart Tab`` feature.

