<type>documentation</type>
<domain>custom</domain>
<id>syntax</id>
<title>Custom Syntax Coloring</title>
<date>$Date: 2007-09-24 23:16:39 -0400 (Mon, 24 Sep 2007) $</date>
<version>$Revision: 16483 $</version>
<product>per+</product>
<product-version>5+</product-version>

There are two ways to configure syntax highlighting in Wing:  Minor adjustments
can be made in preferences, and comprehensive configuration can be achieved
by creating a syntax color specification file.

Minor Adjustments
-----------------

For minor tweaks to syntax coloring in the editor, use the `Editor > Syntax Coloring >
Syntax Formatting
<script:show_preferences_gui#prefname="edit.syntax-formatting">`__ preference. 
For each supported file type,
and each lexical state for the file type, it is possible to set the
foreground and background colors, to use bold or italic font, and to fill the
end of line character so it appears as a solid block of color.

Comprehensive Changes
---------------------

For more comprehensive changes to syntax coloring, textual syntax
coloring specifications can be placed into a directory called ``syntax`` within
the `Settings Directory <ref:install/user-settings-dir>`__.  This
directory must be created if it is not already present.  

Your custom syntax coloring configuration files can be modeled on the system-wide
defaults, which are stored in ``resources/syntax`` within the Install Directory listed in
Wing's `About <script:about-application>`__ box. Copy only the files you intend to edit.
Any values missing from these files cause Wing to fall back to the system-wide defaults.

Wing must be restarted to pick up changes made in these files. To make this easier to do
while working on syntax color configurations, bind a key to the command ``restart-wing``
or right-click on the toolbar to add an icon for this command.

Changing Editor Background Color
................................

The editor background color is set not by the syntax configuration file, but rather in
the theme selected by the `User Interface > Light Editor
<script:show_preferences_gui#prefname="gui.light-editor-theme">`__ and `User Interface >
Dark Editor <script:show_preferences_gui#prefname="gui.dark-editor-theme">`__ preferences.

Wing automatically adjusts all configured editor foreground colors when necessary to
ensure that the text remains visible. This avoids the need to create completely new color
configurations for different editor background colors.

This feature applies both to colors set in preferences and colors in a ``*.stx`` file.
However, automatic color adjustment is disabled when using a theme-specific syntax
configuration file, as describe below, since in that case the colors are being designed
for a specific background color.

To select a specific editor background color, you must create and use a custom display
theme. The color value ``editor-background`` determines the editor background
color. See *Adding a Custom Theme* at the end of `Display Styles and Colors
<ref:custom/qt-styles>`__ for more information on creating custom themes.

Overriding Preferences
......................

Note that any non-default syntax coloring preferences will take precedence 
over syntax files found in the settings directory or system-wide.  So
if you have previously set syntax colors in preferences, you will need
to undo those settings.  One way to do this is to edit the ``preferences``
file in your `Settings Directory <ref:install/user-settings-dir>`__
and remove the value for ``edit.syntax-formatting``.  You'll need to do
this when Wing is not running, or edit a copy of the file in Wing and 
move it into place while Wing is not running.

Theme-Specific Configuration
............................

To override syntax colors only for one particular theme listed in the `User
Interface > Light Editor Theme
<script:show_preferences_gui#prefname="gui.light-editor-theme">`__ and `User Interface > Dark
Editor Theme <script:show_preferences_gui#prefname="gui.dark-editor-theme">`__ preferences,
place the syntax file in a sub-directory of the ``syntax`` directory whose name matches
the theme specification ``.plt`` file name. For example, use
``syntax/black-background/python.stx`` to specify colors to use in Python files only with
the Black Background display theme, which is defined in ``resources/palettes/black-background.plt``
in Wing's installation directory.

Print-Only Colors
.................

To override syntax colors for printing only, place the syntax file in a 
``print`` sub-directory of the ``syntax`` directory.  For example,
use ``syntax/print/python.stx`` to specify colors to use
in Python files when printing.

Color Names for Python
----------------------

The syntax color names shown in preferences and the ``*.stx`` files vary by file type. For
Python they are defined as follows:

* ``default`` -- any text that is not covered by the following (does not include white space)
* ``commentline`` -- a comment starting with a single ``#``
* ``number`` -- any integer, float, binary, octal, or hexadecimal number
* ``string`` -- a string with double quotes ``"like this"``
* ``character`` -- a string with single quotes ``'like this'``
* ``word`` -- any Python keyword, like ``if``, ``else``, ``for``, ``try``, etc.
* ``triple`` -- a triple quoted string with single quotes ``'''like this'''``
* ``tripledouble`` -- a triple quoted string with double quotes ``"""like this"""``
* ``classname`` -- the name of a class when just after the keyword ``class``
* ``defname`` -- the name of a function or method when just after the keyword ``def``
* ``operator`` -- any operator, like ``+``, ``-``, ``/``, ``==``, and so forth
* ``identifier`` -- any variable including function or class names if not at point of definition
* ``commentblock`` -- a comment starting with ``##``
* ``stringeol`` -- indicates an unterminated string
* ``word2`` -- any Python builtin like ``open``, ``file``, ``ord``, ``int``, ``isinstance``, and so forth
* ``decorator`` -- a function, method, or class decorator starting with ``@``
* ``fstring`` -- a double-quoted f-string ``f"like this"``
* ``fcharacter`` -- a single-quoted f-string ``f'like this'``
* ``ftriple`` -- a triple quoted f-string with single quotes ``f'''like this'''``
* ``ftripledouble`` -- a triple quoted f-string with double quotes ``f"""like this"""``

