<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.

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.

Color Palette-Specific Configuration
....................................

To override syntax colors only for one particular `User Interface > Color Palette
<script:show_preferences_gui#prefname="gui.qt-color-palette">`__ preference choice,
place the syntax file in a sub-directory of the ``syntax`` directory
whose name matches the palette specification file name.  For example,
use ``syntax/black-background/python.stx`` to specify colors to use
in Python files only with the Black Background color palette.

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.

Automatic Color Adjustment
--------------------------

If the currently selected color palette in the `User Interface > Color Palette
<script:show_preferences_gui#prefname="gui.qt-color-palette">`__ preference uses a
non-white background for the editor, or if the `Editor > Syntax Coloring > 
Background Color <script:show_preferences_gui#prefname="edit.background-color">`__ 
preference is set to a color other than
white, then Wing will automatically adjust all configured 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 palette-specific syntax
configuration file, as describe above, since in that case the colors are being designed
for a specific background color.

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
* ``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"""``

