Update documentation on colour themes

This commit is contained in:
Veronica Berglyd Olsen
2025-06-03 17:30:59 +02:00
parent 60b5f660e8
commit df7a721626
4 changed files with 242 additions and 169 deletions
+1
View File
@@ -75,6 +75,7 @@ storage for robustness.
more/counting more/counting
more/typography more/typography
more/dictionaries
more/customise more/customise
more/handling_errors more/handling_errors
more/project_format more/project_format
+185 -168
View File
@@ -1,94 +1,35 @@
.. _docs_more_custom: .. _docs_more_custom:
************** *************
Customisations Custom Themes
************** *************
.. _Enchant: https://rrthomas.github.io/enchant/ There are a few ways you can customise novelWriter yourself. Currently, you can relatively easily
.. _Free Desktop: https://cgit.freedesktop.org/libreoffice/dictionaries/tree/ add new GUI themes. You can also add new icon themes, although this is not as straightforward.
There are a few ways you can customise novelWriter yourself. Currently, you can add new GUI themes,
your own syntax themes, and install additional dictionaries.
.. _docs_more_custom_dict:
Spell Check Dictionaries
========================
novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
may not load all installed spell check dictionaries automatically.
Linux and MacOS
---------------
On Linux and MacOS, you generally only have to install hunspell, aspell or myspell dictionaries on
your system like you do for other applications. See your distro or OS documentation for how to do
this. These dictionaries should show up as available spell check languages in novelWriter.
Windows
-------
For Windows, English is included with the installation. For other languages you have to download
and add dictionaries yourself.
**Install Tool**
A small tool to assist with this can be found under **Tools > Add Dictionaries**. It will import
spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries are then
installed in the install location for the Enchant library and should thus work for any application
that uses Enchant for spell checking.
**Manual Install**
If you prefer to do this manually or want to use a different source than the ones mentioned above,
You need to get compatible dictionary files for your language. You need two files files ending with
``.aff`` and ``.dic``. These files must then be copied to the following location:
``C:\Users\<USER>\AppData\Local\enchant\hunspell``
This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or two folders may
not exist, so you may need to create them.
You can find the various dictionaries on the `Free Desktop`_ website.
.. note::
The Free Desktop link points to a repository, and what may look like file links inside the
dictionary folder are actually links to web pages. If you right-click and download those, you
get HTML files, not dictionaries!
In order to download the actual dictionary files, right-click the "plain" label at the end of
each line and download that.
.. _docs_more_custom_theme: .. _docs_more_custom_theme:
Syntax and GUI Themes Colour Themes
===================== =============
Adding your own GUI and syntax themes is relatively easy, although it requires that you manually Adding your own colour themes is relatively easy, although it requires that you manually edit
edit config files with colour values. The themes are defined by simple plain text config files with config files with colour values. The themes are defined by simple plain text config files with meta
meta data and colour settings. data and colour settings.
In order to make your own versions, first copy one of the existing files to your local computer and In order to make your own versions, first copy one of the existing files to your local computer and
modify it as you like. modify it as you like.
* The existing syntax themes are stored in The existing colour themes are stored in
`novelwriter/assets/syntax <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/syntax>`_. `novelwriter/assets/themes <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/themes>`_.
* The existing GUI themes are stored in
`novelwriter/assets/themes <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/themes>`_.
* The existing icon themes are stored in
`novelwriter/assets/icons <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/icons>`_.
Remember to also change the name of your theme by modifying the ``name`` setting at the top of the Remember to also change the name of your theme by modifying the ``name`` setting at the top of the
file, otherwise you may not be able to distinguish them in **Preferences**. file, otherwise you may not be able to distinguish them in **Preferences**.
For novelWriter to be able to locate the custom theme files, you must copy them to the For novelWriter to be able to locate the custom theme files, you must copy them to the
:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder there named :ref:`docs_technical_locations_data` location in your home or user area. There should be a folder
``syntax`` for syntax themes, just ``themes`` for GUI themes, and ``icons`` for icon themes. These there named ``themes`` for colour themes. These folders are created the first time you start
folders are created the first time you start novelWriter. novelWriter.
Once the files are copied there, they should show up in **Preferences** with the label you Once the files are copied there, they should show up in **Preferences** with the label you
set as ``name`` inside the file. set as ``name`` inside the file.
@@ -99,71 +40,123 @@ set as ``name`` inside the file.
files up to date. files up to date.
Custom GUI and Icons Theme The Theme File Format
-------------------------- ---------------------
A GUI theme ``.conf`` file consists of the following settings: A colour theme ``.conf`` file consists of the following settings:
.. code-block:: cfg .. code-block:: cfg
:caption: The theme file for the "Default Light Theme"
[Main] [Main]
name = My Custom Theme name = Default Light Theme
description = A description of my custom theme mode = light
author = Jane Doe description = The novelWriter standard light theme
credit = John Doe author = Veronica Berglyd Olsen
url = https://example.com credit = Veronica Berglyd Olsen
url = https://github.com/vkbo/novelWriter
license = CC BY-SA 4.0 license = CC BY-SA 4.0
licenseurl = https://creativecommons.org/licenses/by-sa/4.0/ licenseurl = https://creativecommons.org/licenses/by-sa/4.0/
[Icons] [Base]
default = 100, 100, 100 default = #303030
faded = 100, 100, 100 faded = #6c6c6c
red = 255, 0, 0 red = #a62a2d
orange = 255, 128, 0 orange = #b36829
yellow = 255, 255, 0 yellow = #a68542
green = 0, 255, 0 green = #296629
aqua = 0, 255, 255 cyan = #269999
blue = 0, 0, 255 blue = #3a70a6
purple = 255, 0, 255 purple = #b35ab3
[Project] [Project]
root = 0, 255, 255 root = blue
folder = 255, 255, 0 folder = yellow
file = 100, 100, 100 file = default
title = 0, 255, 0 title = green
chapter = 255, 0, 0 chapter = red
scene = 0, 0, 255 scene = blue
note = 255, 255, 0 note = yellow
[Palette] [Palette]
window = 100, 100, 100 window = #efefef
windowtext = 100, 100, 100 windowtext = #000000
base = 100, 100, 100 base = #ffffff
alternatebase = 100, 100, 100 alternatebase = #e0e0e0
text = 100, 100, 100 text = #000000
tooltipbase = 100, 100, 100 tooltipbase = #ffffc0
tooltiptext = 100, 100, 100 tooltiptext = #15150d
button = 100, 100, 100 button = #efefef
buttontext = 100, 100, 100 buttontext = #000000
brighttext = 100, 100, 100 brighttext = #ffffff
highlight = 100, 100, 100 highlight = #3087c6
highlightedtext = 100, 100, 100 highlightedtext = #ffffff
link = 100, 100, 100 link = blue
linkvisited = 100, 100, 100 linkvisited = blue
[GUI] [GUI]
helptext = 0, 0, 0 helptext = #5c5c5c
fadedtext = 128, 128, 128 fadedtext = #6c6c6c
errortext = 255, 0, 0 errortext = red
In the Main section you must at least define the ``name`` settings. [Syntax]
background = #ffffff
text = #000000
link = blue
headertext = green
headertag = green:160
emphasis = orange
dialog = blue
altdialog = blue
note = yellow
hidden = faded
shortcode = green
keyword = red
tag = green
value = blue
optional = green
spellcheckline = red
errorline = green
replacetag = green
modifier = green
texthighlight = #c8c80060
The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the
`Qt documentation <https://doc.qt.io/qt-6/qpalette.html#ColorRole-enum>`_ for more details. The Theme Sections
colour values are RGB numbers on the format ``r, g, b`` where each is an integer from ``0`` to --------------
``255``. Omitted values are not loaded and will use default values. If the ``helptext`` colour is
not defined, it is computed as a colour between the ``window`` and ``windowtext`` colour. .. _ColorRole: https://doc.qt.io/qt-6/qpalette.html#ColorRole-enum
Additional shades of some of the colours are also computed. These are mainly used for 3D effects.
The theme file is made up of different sections depending on what part of novelWriter the theme
affects.
.. csv-table:: Theme Sections Overview
:header: "Section", "Description"
:class: "tight-table"
"``[Main]``", "Meta data about the theme, You must at least set ``name`` and ``mode``, and ``mode`` must be either ``light`` or ``dark``."
"``[Base]``", "The base colours of the theme. These are also selectable colours in various places inside the app, like for icon colours in **Preferences**."
"``[Project]``", "The colours used for icons and markers for the different project item types."
"``[Palette]``", "The colours used for styling the user interface. The values correspond to the ColorRole_ values in the Qt library."
"``[GUI]``", "The colours used for styling additional elements of the user interface."
"``[Syntax]``", "The colours used for syntax highlighting in documents."
Colour Value Formats
--------------------
There are several ways to enter colour values:
.. csv-table:: Colour Formats
:header: "Syntax", "Description"
:class: "tight-table"
"``#RRGGBB``", "A CSS style hexadecimal values, like ``#ff0000`` for red."
"``#RRGGBBAA``", "A CSS style hexadecimal values with transparency, like ``#ff00007f`` for half-transparent red."
"``name``", "A name referring to one of the colours already specified under the ``[Base]`` section, like ``red``. Note that you should not use named colours in the ``[Base]`` section itself as that may have unintended results."
"``name:alpha``", "A name referring to one of the colours already specified under the ``[Base]`` section, with a transparency value added. The alpha value must be in the range ``0`` to ``255``, like ``red:127`` for half-transparent red."
"``r, g, b``", "A set of red, green and blue numbers in the range ``0`` to ``255``, like ``255, 0, 0`` for red."
"``r, g, b, a``", "A set of red, green, blue and alpha numbers in the range ``0`` to ``255``, like ``255, 0, 0, 127`` for half-transparent red."
.. versionadded:: 2.5 .. versionadded:: 2.5
The ``fadedtext`` and ``errortext`` theme colour entries were added. The ``fadedtext`` and ``errortext`` theme colour entries were added.
@@ -172,60 +165,84 @@ Additional shades of some of the colours are also computed. These are mainly use
The ``icontheme`` setting was dropped as the icon theme is now its own setting. The ``icontheme`` setting was dropped as the icon theme is now its own setting.
The ``[Icons]`` and ``[Project]`` sections were added, and the ``status*`` settings removed. The ``[Icons]`` and ``[Project]`` sections were added, and the ``status*`` settings removed.
.. versionadded:: 2.8
The ``[Syntax]`` section was moved into the main theme file. Previously, these settings were in
their own file. The ``[Icons]`` section was renamed to ``[Base]``.
Custom Syntax Theme
-------------------
A syntax theme ``.conf`` file consists of the following settings: Icon Themes
===========
Icon themes are *not* straightforward to add, but if you want to make the effort, this section
describes how to do it.
The existing icon themes are stored in
`novelwriter/assets/icons <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/icons>`_.
As with colour themes, remember to change the name of your theme by modifying the ``name`` setting
at the top of the file, otherwise you may not be able to distinguish them in **Preferences**.
For novelWriter to be able to locate the custom theme files, you must copy them to the
:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder
there ``icons`` for icon themes. These folders are created the first time you start novelWriter.
The Icons File Format
---------------------
Icon themes are kept in files with the ``.icons`` file extension. The file format is a custom
format with entries on the form ``section:key = value``.
.. code-block:: cfg .. code-block:: cfg
:caption: The icons file for "Material Symbols - Rounded Medium" (truncated)
[Main] # Meta
name = My Syntax Theme meta:name = Material Symbols - Rounded Medium
author = Jane Doe meta:author = Google Inc
credit = John Doe meta:license = Apache 2.0
url = https://example.com
license = CC BY-SA 4.0
licenseurl = https://creativecommons.org/licenses/by-sa/4.0/
[Syntax] # Icons
background = 255, 255, 255 icon:alert_error = <svg ...>
text = 0, 0, 0 icon:alert_info = <svg ...>
link = 0, 0, 0 icon:alert_question = <svg ...>
headertext = 0, 0, 0 icon:alert_warn = <svg ...>
headertag = 0, 0, 0 icon:cls_archive = <svg ...>
emphasis = 0, 0, 0 icon:cls_character = <svg ...>
dialog = 0, 0, 0 icon:cls_custom = <svg ...>
altdialog = 0, 0, 0 icon:cls_entity = <svg ...>
note = 0, 0, 0 icon:cls_none = <svg ...>
hidden = 0, 0, 0 icon:cls_novel = <svg ...>
shortcode = 0, 0, 0 icon:cls_object = <svg ...>
keyword = 0, 0, 0 icon:cls_plot = <svg ...>
tag = 0, 0, 0 icon:cls_template = <svg ...>
value = 0, 0, 0 icon:cls_timeline = <svg ...>
optional = 0, 0, 0 icon:cls_trash = <svg ...>
spellcheckline = 0, 0, 0 icon:cls_world = <svg ...>
errorline = 0, 0, 0
replacetag = 0, 0, 0
modifier = 0, 0, 0
texthighlight = 255, 255, 255, 128
In the Main section, you must define at least the ``name`` setting. The Syntax colour values are The icon keys are associated with icon placement locations inside novelWriter, and the template for
RGB(A) numbers of the format ``r, g, b, a`` where each is an integer from ``0`` to ``255``. The them is defined in the script that generates the default icon themes.
fourth value is the alpha channel, which can be omitted.
Omitted syntax colours default to black, except ``background`` which defaults to white, and The script can be found under
``texthighlight`` which defaults to white with half transparency. `utils/icon_themes.py <https://github.com/vkbo/novelWriter/blob/main/utils/icon_themes.py>`__
in the source code.
.. versionadded:: 2.2 This file includes all the code needed to generate the themes that are included in novelWriter. The
The ``shortcode`` syntax colour entry was added. icon keys are mapped to icon keys from the specific themes in JSON files in the ``icon_themes``
folder next to the script. This is the recommended way to generate these themes. Doing it manually
is not advisable.
.. versionadded:: 2.3
The ``optional`` syntax colour entry was added.
.. versionadded:: 2.4 Icon Value Format
The ``texthighlight`` syntax colour entry was added. -----------------
.. versionadded:: 2.5 As can be seen from the example, an icon is defined in the ``icon`` section with a key and an
The ``dialog``, ``altdialog``, ``note`` and ``tag`` syntax colour entries were added. in-line SVG XML block. The XML must fit on one line and obey the following rules:
``straightquotes``, ``doublequotes`` and ``singlequotes`` were removed.
#. It must be single colour, that is, the fill colour attribute must be able to colourise the
entire icon.
#. The fill colour attribute *must* be defined and must be set to: ``fill="#000000"``. This value
is replaced by the relevant theme colour when the icon is processed in novelWriter.
.. versionadded:: 2.7
The icon theme files were added. Previously, icons were stored as individual SVG files with a
config file mapping the file names to the internal icon keys.
+55
View File
@@ -0,0 +1,55 @@
.. _docs_more_dictionaries:
************************
Spell Check Dictionaries
************************
.. _Enchant: https://rrthomas.github.io/enchant/
.. _Free Desktop: https://cgit.freedesktop.org/libreoffice/dictionaries/tree/
Spell checking is provided by the Enchant_ library. Depending on your operating system, it may or
may not load all installed spell check dictionaries automatically.
Linux and MacOS
===============
On Linux and MacOS, you generally only have to install hunspell, aspell or myspell dictionaries on
your system like you do for other applications. See your distro or OS documentation for how to do
this. These dictionaries should show up as available spell check languages in novelWriter.
Windows
=======
For Windows, English is included with the installation. For other languages you have to download
and add dictionaries yourself.
**Install Tool**
A small tool to assist with this can be found under **Tools > Add Dictionaries**. It will import
spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries are then
installed in the install location for the Enchant library and should thus work for any application
that uses Enchant for spell checking.
**Manual Install**
If you prefer to do this manually or want to use a different source than the ones mentioned above,
You need to get compatible dictionary files for your language. You need two files files ending with
``.aff`` and ``.dic``. These files must then be copied to the following location:
``C:\Users\<USER>\AppData\Local\enchant\hunspell``
This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or two folders may
not exist, so you may need to create them.
You can find the various dictionaries on the `Free Desktop`_ website.
.. note::
The Free Desktop link points to a repository, and what may look like file links inside the
dictionary folder are actually links to web pages. If you right-click and download those, you
get HTML files, not dictionaries!
In order to download the actual dictionary files, right-click the "plain" label at the end of
each line and download that.
+1 -1
View File
@@ -55,7 +55,7 @@ edited from the **Project Word List** tool available from the **Tools** menu.
.. note:: .. note::
Generally, spell checking dictionaries are collected from your operating system, but on Windows Generally, spell checking dictionaries are collected from your operating system, but on Windows
they are not. See :ref:`docs_more_custom_dict` for how to add spell checking dictionaries on they are not. See :ref:`docs_more_dictionaries` for how to add spell checking dictionaries on
Windows. Windows.