=============
Color Schemes
=============
.. contents::
:local:
:depth: 2
Overview
========
Color schemes define the colors
used to highlight source code in Sublime Text views
and to style different elements
found in the editing area:
background, foreground, selection, caret...
File Format
===========
.. include:: /_includes/color_scheme_summary_table.g.txt
The file format of color scheme files
is inherited from Textmate.
.. note::
Sublime Text uses the ``.tmTheme`` extension for color scheme files
to maintain compatibility with Textmate.
Rather confusingly,
Sublime Text also has a notion
of a user interface (UI) theme.
A UI theme is a set of styles and decorations
to alter the look of the editor's UI.
It's important to remember
that UI themes and color schemes
are two different customization mechanisms.
Generally speaking, it is far less complex
to create a new color scheme
than it is to create a new UI theme.
Where to Store Color Schemes
============================
By convention,
:doc:`packages ` primarily containing
a set of color scheme files
have the *Color Scheme -* prefix.
For example: *Color Scheme - Default*.
The file names of all available color schemes
are displayed in the **Preferences → Color Scheme** menu,
grouped by the containing package.
.. _color-scheme-structure:
Structure of a Color Scheme File
================================
All color scheme files share
the same topmost structure.
Colors can be expressed in the
following formats:
``#RRGGBB``, ``#RGB``, `X11 color names`__
.. __: https://en.wikipedia.org/wiki/X11_color_names
Most elements controlling colors
accept an alpha channel value:
``#RRGGBBAA``.
.. contents:: Contents
:local:
Topmost Elements in Color Schemes Files
***************************************
.. code-block:: xml
name
Monokai
settings
uuid
D8D5E82E-3D5B-46B5-B38E-8C841C21347D
``name``
Optional.
Name of the color scheme.
Ignored by Sublime Text.
``settings``
Required.
Container for further color scheme settings.
See :ref:`color-scheme-settings` for details.
``uuid``
Optional.
A unique identifier for the file.
Ignored by Sublime Text.
.. _color-scheme-settings:
Sub-elements of Settings
************************
Sublime Text supports
the following color scheme settings:
Global Settings
---------------
Not associated with any scope.
These settings affect global visual items
in the editing area.
Global settings go inside a ```` element
within the topmost ````.
.. code-block:: xml
settings
background
#272822
caret
#F8F8F0
...
...
General
^^^^^^^
``foreground``
Default foreground color for the view.
Affects file contents, the gutter, rulers and guides.
The alpha channel does not apply to file contents.
Because there is no override setting for rulers,
the only way to change the color of rulers
is a "hack" further described `here`__.
.. __: https://github.com/icylace/CursorRuler/wiki/Tips#ruler-colors
``background``
Default background color of the view (and gutter).
``invisibles``
Ignored.
``caret``
Color of the caret.
``lineHighlight``
Color of the line the caret is in.
Only used when the ``higlight_line`` setting is set to ``true``.
Brackets
^^^^^^^^
``bracketContentsOptions``
Controls how brackets are highlighted
when a caret is between a bracket pair.
Expects a space-separated list of the available options.
Only applied when the ``match_brackets`` setting
is set to ``true``.
Options: ``underline``, ``stippled_underline``, ``squiggly_underline``,
``foreground``
Default: ``underline``
``bracketContentsForeground``
Color of the highlighting(s)
selected by ``bracketContentsOptions``.
Only applied when the ``match_brackets`` setting
is set to ``true``.
``bracketsOptions``
Controls how brackets are highlighted
when a caret is next to a bracket.
Expects a space-separated list of the available options.
Only applied when the ``match_brackets`` setting
is set to ``true``.
Options: ``underline``, ``stippled_underline``, ``squiggly_underline``,
``foreground``
Default: ``underline``
``bracketsForeground``
Color of the highlighting(s)
selected by ``bracketOptions``.
Only applied when the ``match_brackets`` setting
is set to ``true``.
Tags
^^^^
``tagsOptions``
Controls how tags are highlighted
when a caret is inside a tag.
Expects a space-separated list of the available options.
Only applied when the ``match_tags`` setting
is set to ``true``.
Options: ``underline``, ``stippled_underline``, ``squiggly_underline``,
``foreground``
Default: ``stippled_underline``
``tagsForeground``
Color of the highlighting(s)
selected by ``tagsOptions``.
Only applied when the ``match_tags`` setting
is set to ``true``.
Find
^^^^
``findHighlight``
Background color of regions matching the current search.
``findHighlightForeground``
Foreground color of regions matching the current search.
Gutter
^^^^^^
``gutter``
Background color of the gutter.
``gutterForeground``
Foreground color of the gutter.
Selection
^^^^^^^^^
``selection``
Color of the selection regions.
``selectionBorder``
Color of the selection regions' border.
``inactiveSelection``
Color of inactive selections (inactive view).
Guides
^^^^^^
``guide``
Color of the guides displayed to indicate nesting levels.
Only used if the ``indent_guide_options`` setting
includes``draw_normal``.
``activeGuide``
Color of the guide lined up with the caret.
Only applied if the ``indent_guide_options`` setting
includes ``draw_active``.
``stackGuide``
Color of the current guide's parent guide levels.
Only used if the ``indent_guide_options`` setting
is set to ``draw_active``.
.. TODO image
Highlighted Regions
^^^^^^^^^^^^^^^^^^^
``highlight``
Background color for regions added via ``sublime.add_regions()``
with the ``sublime.DRAW_OUTLINED`` flag added.
``highlightForeground``
Foreground color for regions added via ``sublime.add_regions()``
with the ``sublime.DRAW_OUTLINED`` flag added.
Shadow
^^^^^^
``shadow``
Color of the shadow effect when the buffer is scrolled.
``shadowWidth``
Width of the shadow effect when the buffer is scrolled.
Values greater than 32
cause the shadow to be hidden.
The default is 8.
Note that, despite its nature,
this expects a **string value**.
Scoped Settings
---------------
Settings associated with a particular scope.
.. code-block:: xml
...
name
Comment
scope
comment
settings
foreground
#75715E
...
``name``
Descriptive name of the item.
``scope``
Target scope name.
``settings``
Container for settings.
Valid settings are:
``fontStyle``
Space-separated list of
styles for the font.
Options: ``bold``, ``italic``, nothing (resets fontStyle to normal)
``foreground``
Foreground color.
``background``
Background color.
Minimal Scope Coverage
======================
Refer to the `official Scope Naming guidelines`__
in order to find out
which scopes a color scheme should cover at minimum.
.. __: http://www.sublimetext.com/docs/3/scope_naming.html#color_schemes
Sublime Text Settings Related to Color Schemes
==============================================
View Settings
*************
``color_scheme``
Path to a color scheme file
relative to the Data folder
(example: :file:`Packages/Color Scheme - Default/Monokai.tmTheme`).