OpenToonz - An open-source full-featured 2D animation creation software
Developing Stylesheets
Stylesheets are written with LESS, which is a dynamic preprocessor stylesheet language that can be compiled into Qt stylesheets.
[!TIP] List of LESS Functions.
Recommended Setup
Windows
Although any LESS compiler will work fine, here is a recommended setup.
- Install Visual Studio Code by Microsoft.
- Add the Easy LESS extension (by mrcrowl) from the marketplace which will be used as the compiler (on save).
- In VSCode, navigate to your OpenToonz stuff folder and open
config/qss/Default/less.
A settings.json file is already included to ensure developers work to the same standards located in .vscode. If the file must be created manually then the following should apply.
"editor.tabSize": 2,
"less.compile": {
"compress": true,
"sourceMap": false,
"out": false
}
Linux
On Linux you can use the recommended VSCode setup or use a command-line compiler lessc.
Ubuntu:
$ apt install node-less
Fedora:
$ dnf install nodejs-less
How To Compile
Windows
The Easy LESS extension uses a compile on save feature, so the theme files must be saved to generate an output.
less/themes/default/default-theme.less
less/themes/others/default-green-theme.less
less/themes/others/blue-theme.less
less/themes/others/dark-theme.less
less/themes/others/clay-theme.less
less/themes/others/neutral-theme.less
less/themes/others/light-theme.less
less/themes/others/synthwave-theme.less
Linux
From opentoonz source directory root execute the following commands:
$ lessc -x less/themes/default/default-theme.less stuff/config/qss/Default/Default.qss
$ lessc -x less/themes/others/default-green-theme.less stuff/config/qss/Default-Green/Default-Green.qss
$ lessc -x less/themes/others/blue-theme.less stuff/config/qss/Blue/Blue.qss
$ lessc -x less/themes/others/dark-theme.less stuff/config/qss/Dark/Dark.qss
$ lessc -x less/themes/others/clay-theme.less stuff/config/qss/Clay/Clay.qss
$ lessc -x less/themes/others/neutral-theme.less stuff/config/qss/Neutral/Neutral.qss
$ lessc -x less/themes/others/light-theme.less stuff/config/qss/Light/Light.qss
$ lessc -x less/themes/others/synthwave-theme.less stuff/config/qss/Synthwave/Synthwave.qss
How They Work
The stylesheets use LESS to separate the layout structure from theme colors. A shared base skeleton defines the component structure without hard-coded colors, while individual theme files provide color variables.
Each theme is compiled with the same base layout to generate the final QSS files for different color schemes.
Cascade Hierarchy
The include pathway is important as certain parts need to be included before others so they can be overridden later. The important chain is as follows as defined in _main.less:
// Base
@import 'base/_styles.less';
// Layouts
@import 'layouts/_mainwindow.less'; // load mainwindow first!
@import 'layouts/_user-controls.less';
// Others (at this point any order is fine)
The _mainwindows.less file contains classes for ScrollBars, Tabs, and general window styles that other panels may override, so it is important this is included early.
Variables
The themes use a variable-driven system where a set of base variables define the interface colors and properties. Many variables may be derived from others such as using LESS color functions like darken(). This allows a theme to change the entire interface appearance by overriding only a few base variables.
Example:
@bg-color: black;
@panel-bg-color: darken(@bg-color, 5%);
@border-color: darken(@bg-color, 15%);
If a theme overrides @bg-color, all derived colors automatically update. This keeps themes consistent and reduces the number of values that must be manually maintained.
[!TIP] For a full list of available color variables and properties, view
themes/default/default-theme.less.
Adding New Features
This is an example of how to add new features into the layout files.
#NewWindow {
background-color: @bg-color;
border: 1 solid @accent-color;
& QPushButton#OK {
background-color: @button-bg-color;
border-color: @button-border-color;
color: @button-text-color;
padding: 3;
&:hover {
border-color: @hl-bg-color;
}
}
}
To reuse styles from another class you can reference another class as a mixin:
#NewWindow {
.some-style(); // import properties
}
[!NOTE] This is more stable than using
extend, even if it produces a larger.qssoutput.
Creating New Themes
It's possible to create custom themes.
How To
- Make sure you have a LESS compiler setup and working before proceeding.
- Navigate to
stuff/config/qss/Default/less/themes/others. - You can either duplicate an existing theme and rename it (pay attention to the header section to rename the
outpath) or create a new empty.lesstheme file.
If creating an empty file, make sure to include the required sections:
// out: "../../../../Theme-Name/Theme-Name.qss"
//! The above line is for EasyLESS (VSCode extension) compile output location
// -----------------------------------------------------------------------------
// THEME NAME
// -----------------------------------------------------------------------------
// Theme to inherit/override (this inherits colors/properties)
@import '../default/default-theme.less';
// Image path relative to where this *.qss is output
@img-url: '../Default/imgs/white';
//------------------------------------------------------------------------------
//! Now override variables necessary for this theme below!
// -----------------------------------------------------------------------------
// SETTINGS --------------------------------------------------------------------
@ui-contrast: 1.0; //? example
// COLORS ----------------------------------------------------------------------
@bg-color: green; //? example
[!NOTE] You only need to override most base variables, like
@bg-color, if another variable referenced it using a LESS color function the updated color is automatically propogated.
[!TIP] A full list of possible color variables and properties can be found by viewing the default theme file at
themes/default/default-theme.less.
Development Guidelines
[!IMPORTANT]
- Always develop using the Default theme first as most layout changes will automatically propogate to other themes.
- Only adjust other themes if a variable override is needed.
- Avoid hard-coded colors in layout files and always use variables so themes remain compatible.
Folder Responsibilities
Base
Reusable UI structures such as buttons, tabs, icon layouts, etc.
Layouts
Window-level layout definitions for widgets, panels and containers.
Themes
Color definitions that override base variables.