Add THEMING.md

This commit is contained in:
miruka 2021-01-04 01:01:37 -04:00
parent 1a101d9888
commit c80316c8e1
2 changed files with 57 additions and 3 deletions

View File

@ -1,8 +1,8 @@
# PCN File Format # PCN File Format
Config and theme files are written in the PCN (Python Config Notation) format, This document explains in details the PCN (Python Config Notation) format.
which are organized in a hierarchy of sections and properties. PCN files are organized in a hierarchy of sections and properties.
PCN files can also contain usual Python code, such as imports and PCN files can also contain normal Python code, such as imports and
custom functions. custom functions.
- [Overview](#overview) - [Overview](#overview)

54
docs/THEMING.md Normal file
View File

@ -0,0 +1,54 @@
# Theming
A default theme from this repository can be copied to use as a base and edit,
for example:
```sh
cp mirage/src/themes/Midnight.qpl \
"${XDG_DATA_HOME:-$HOME/.local/share}/mirage/themes/MyTheme.qpl"
```
Or for Flatpak users:
```sh
cp mirage/src/themes/Midnight.qpl \
~/.var/app/io.github.mirukana.mirage/data/mirage/themes/MyTheme.qpl
```
The `theme` property in [`settings.py`](CONFIG.md#settingspy) would need
to be set to `MyTheme.qpl` in this case.
Theme files are nested-by-indentations sections of properties and values.
Properties are declared as `<type> <name>: <value>`.
Values can be any JavaScript (ECMAScript 7) expressions.
Most of the properties are of type `color`.
Their values, if not just refering to another property,
can be expressed with a:
- [SVG/CSS color name](https://www.december.com/html/spec/colorsvg.html)
string, e.g. `"blue"`
- Hexadecimal code string, e.g. `"#fff"` or `"#cc0000"`
- RGBA value, using the `Qt.rgba(0-1, 0-1, 0-1, 0-1)` function
- HSLA value, using the `Qt.hsla(0-1, 0-1, 0-1, 0-1)` function
- HSVA value, using the `Qt.hsva(0-1, 0-1, 0-1, 0-1)` function
- [HSLUV](https://www.hsluv.org/) value, using the
`hsluv(0-360, 0-100, 0-100, 0-1)` function. This is the prefered method
used throughout the default theme files
(why? see [this](https://www.hsluv.org/comparison/#rainbow-hsluv) and
[that](https://www.boronine.com/2012/03/26/Color-Spaces-for-Human-Beings/#hsl-is-a-lemon))
If you just want to change the background picture,
or use a gradient/simple color instead, search for the `ui:` section in your
text editor.
When an in-use theme file is saved while the application is running, it
will automatically be reloaded and changes will be seen immediatly.
**Warnings**:
- API currently unstable: theme properties are often renamed, added or deleted.
- The file format for themes will soon change
- The current file format forces all theme to have all properties
defined, instead of being able to only specify the ones to override from the
default theme.