.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
.. _settings:

********
Settings
********

Creating custom Settings (Preferences) is one of the ways you can customize
Sublime |nbsp| Text's behavior.

The global default Settings are accessed (read-only) by:

    :menuselection:`Preferences --> Settings` (left side since Sublime |nbsp| Text 4)

This opens a window with a pair of :file:`.sublime-settings` files shown side by side.

The right side of the window that appears is your own settings file that overrides the
settings on the left-hand side.  Note that the entire file is one large JSON object
(dictionary when translated to a Python object).  JSON objects contain key/value
pairs.  Each "key" is a setting name, and each "value" is the setting value.

You customize settings by copying key/value pairs from the left side to your
own :file:`.sublime-settings` file on the right side, and changing its value by
editing and saving the file on the right side (your settings override file).  The
documentation for each setting is conveniently right there in the left-side file
with each setting.

.. note::

    If you have the ``PackageDev`` Package installed, this copy/pasting can be done
    by a single mouse click on the setting's pencil icon, among many other things.

Settings are stored in :term:`JSONC format` (JSON with comments), which means you can
include end-of-line comments after ``//`` to document why you did certain things so
you can remember the reasons later, as well as leave commas after the last item in a
list.

Obviously it helps to be familiar with JSON data format.  If you need to brush up
on it, or need to learn it from scratch, here are a couple of good references:

- `Introducing JSON`_   (authoritative reference for JSON beginners)
- `JSON on Wikipedia`_  (article including JSON history)

The major sections of the default settings file are:

    - Editor settings (the top 2/3 of the file),
    - UI settings,
    - Application settings.

The last 2 "sections" of the settings file are headed by a "header comment" with
the latter 2 titles.

:u:`Syntax-Specific Settings:`

    :menuselection:`Preferences --> Settings---Syntax-Specific`

This is a subset of the main settings that override global defaults when editing
a file that uses that Syntax.

:u:`Package Settings:`

:term:`Package` settings, which apply to specific Package behavior, and are
are accessed by:

    :menuselection:`Preferences --> Package Settings --> PackageName --> ...`

These settings are applied in layers like CSS, where lower (more specific)
preferences override higher-level preferences of the same name.

The "path" of the "layer cascade" is guided by the :term:`Syntax` of the
current :term:`View` as follows:

.. container:: tighter-table-6

    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | Layer                 | Access                                                                          | Notes                                                                     |
    +=======================+=================================================================================+===========================================================================+
    | global defaults       | :menuselection:`Preferences --> Settings` (left side)                           | shipped:  Packages/Default/Preferences.sublime-settings                   |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | platform defaults     | :menuselection:`Tools --> View Package File` > Default/Preferences (<platform>) | override folder:  Packages/Default/Preferences (Windows).sublime-settings |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | user overrides        | :menuselection:`Preferences --> Settings` (right side)                          | Packages/User/Preferences.sublime-settings                                |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | project overrides     | :menuselection:`Project --> Edit Project` > "settings": { ... } entry           | Pjt File; editor preferences only, not UI or APP preferences.             |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | syntax defaults       | :menuselection:`Preferences --> Settings - Syntax Specific` (left)              | shipped:  Packages/<syntax>/<syntax>.sublime-settings                     |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | syntax file overrides | :menuselection:`Preferences --> Settings - Syntax Specific` (left if present)   | override folder:  Packages/<syntax>/<syntax>.sublime-settings             |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | syntax overrides      | :menuselection:`Preferences --> Settings - Syntax Specific` (right)             | Packages/User/C.sublime-settings                                          |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+
    | buffer-specific       | Programmatic/by command (see below)                                             | no file involved                                                          |
    +-----------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+

In a :term:`Plugin`, you can get settings from a :term:`View` or :term:`Window`.  The
object returned is like a dictionary, and you can read and write live settings using
it using its ``get()`` and ``set()`` methods respectively.  Changes to settings made
are in the :ui:`buffer-specific` category shown in table, and are only temporary
until that View or Window is closed.  You can also create a dictionary from it by:

    ``my_settings_dict = settings.to_dict()``

but be advised:  the dictionary acquired is only a copy and changes to it have no
impact on the actual settings.

Additionally, there are 2 :term:`Commands <Command>` you can use anywhere Commands
can be used:

.. container:: tighter-table-3

    +----------------+-----------------------------------------------+-----------------------------------------------------------------+
    | Command        | Args                                          | Example                                                         |
    +================+===============================================+=================================================================+
    | toggle_setting | {"setting": "<setting_name>"}                 | {"setting": "word_wrap"}                                        |
    +----------------+-----------------------------------------------+-----------------------------------------------------------------+
    | set_setting    | {"setting": "<setting_name>", "value": Value} | | {                                                             |
    |                |                                               | |     "setting": "color_scheme",                                |
    |                |                                               | |     "value": "Packages/Color Scheme - Default/Cobalt.tmTheme" |
    |                |                                               | | }                                                             |
    +----------------+-----------------------------------------------+-----------------------------------------------------------------+