tahoma2d/doc/how_to_stylesheet.md

# Developing Stylesheets
Stylesheets are written with [LESS](http://lesscss.org/), which is a dynamic preprocessor stylesheet language that can be compiled into Qt stylesheets.

ℹ️ [LESS Functions](http://lesscss.org/functions/)

## Recommended Setup

### Windows
Although any LESS compiler will work fine, here is a recommended setup.

- Install [Visual Studio Code](https://code.visualstudio.com/) by Microsoft.
- Add the [Easy LESS](https://marketplace.visualstudio.com/items?itemName=mrcrowl.easy-less) extension from the marketplace which will be used as the compiler.
- In VSCode, navigate to your Tahoma2D 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.

``` json
  "editor.tabSize": 2,
  "less.compile": {
  "compress":  true,
  "sourceMap": false,
  "out":       false
}
```

ℹ️ [How to Change Settings in Visual Studio Code](https://code.visualstudio.com/docs/getstarted/settings).

### Linux

On Linux you will need a command-line compiler `lessc`.

Ubuntu:

    $ apt install node-less

Fedora:

    $ dnf install nodejs-less



## How To Compile

### Windows

Easy LESS uses a compile on save feature, so the theme files must be saved to generate an output.

```
Default.less
themes/Blue.less
themes/Dark.less
themes/Light.less
```

### Linux
From Tahoma2D source directory root execute the following commands:
```
$ lessc -x stuff/config/qss/Default/less/Default.less stuff/config/qss/Default/Default.qss
$ lessc -x stuff/config/qss/Default/less/themes/Blue.less stuff/config/qss/Blue/Blue.qss
$ lessc -x stuff/config/qss/Default/less/themes/Dark.less stuff/config/qss/Dark/Dark.qss
$ lessc -x stuff/config/qss/Default/less/themes/Light.less stuff/config/qss/Light/Light.qss
```

## How They Work
The stylesheets are designed into a component, wire-frame and palette structure similar to web design that exploits the cascade of the LESS language to generate multiple theme colors from a single layout. This method was used to prevent duplication.

### Cascade Hierarchy 
The include pathway is important as `components` need to be included before `layouts`. The cascade order is defined in the `main.less` file.

``` LESS
// Base
@import 'base/colors';
@import 'base/mixins';

// Components
@import 'components/all';

// Layouts
@import 'layouts/all';
```

Then import the `main.less` file into the theme file which will add values to every variable in `Default.less`.

## Variable List
There are many variables, for a full list look at `Default.less`, below is a list of the core variables.

`@bg` is the main background color for the interface, almost all other color variables use it as their base color and instead use color functions to either lighten or darken the value.

`@text-color` is the main text color for the interface.

`@accent` is used for accenting, such as borders, separators, boxes, wrappers, think of it as secondary.

`@hl-bg-color` changes the color for highlighted items and focused text fields, think of it as tertiary.

# Adding New Features
This is an example of how to add new features into the layout files.

``` LESS
#NewWindow {
  background-color: @bg;
  border: 1 solid @accent;
  
  & 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 call components, use the LESS extend function.

``` LESS
#NewWindow {
  &:extend(#ComponentName all);
}
```

ℹ️ [LESS Extend Docs](http://lesscss.org/features/#extend-feature)

# Creating New Themes
It's possible to create custom themes.

## How To
- Navigate to your Tahoma2D stuff directory, and create a new folder in `config/qss`.
- Create a new text file in the new folder, give it the same name as the folder and save it with the `.less` extension.
- Open the LESS file and add the following line at the top.
- `// out: filename.qss`
- Which will control where Easy LESS outputs the compiled file on save.
- Next, choose which theme you want to base from, in this example the base will be Default.
- Add this line under the Easy LESS line but above everything else.
- `@import '../Default/less/Default.less'`
- Now the theme file is a clone of Default, so variables can be overridden.

``` LESS
//out: filename.qss

@import '../Default/less/Default.less';

@bg: red;
@text-color: white;
@hl-bg-color: yellow;

// etc
```

# Notes
⚠️ When developing, always develop with the Default theme, then decide later if any changes need porting to alternate themes, in most cases it won't be necessary.

⚠️ Layout files must never have hard-coded color values, color values **must always** be variable. Each function area of Tahoma2D is split into a separate file.

### Directory Information
**Base:** Contains generic color palettes, legacy code, mixins and functions. It's fine to place junk code here.

**Components:** Anything re-usable is here, such as multiple tab structures, button styles, icon layouts, frames, wrappers and folder trees.

**Layouts:** The core wire-frame, every window, widget and control is designed here.

**Themes:** Alternate theme colors that inherit the Default theme, it is only necessary to override variable values unique to the theme.