# Window Manager Configuration

The Window Manager's states and aesthetics can be configured through the config.ini file located in the folder `/etc/window_manager/config.ini`. Developers can add [Entries](#entries), which are specified in [INI format](#basic-format). The configuration file is not a requirement. If the config.ini file is not present, then the Window Manager will use the default settings.

## Basic format

The configuration file is of format INI which are specified by [freedeskop](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html). The basic format consist of [sections](#sections) and [entries](#entries).

### Sections

A section is a logical container that groups related configuration options or settings together.

Example of a section

``` ini
[section]
key1=value1
```

See supported recognized [groups](#recognized-groups)

### Entries

An entry is a single key-value pair within a section.

``` ini
key=value1
```

### Keys

A key is a unique identifier for a particular configuration entry.

See the list of recognized keys in different groups in section [Recognized Keys](#recognized-keys)

### Key types

Keys can be of the following types:

- `Text`: all ASCII characters except for control characters
- `Color`: ARGB [support Qt color value](https://doc.qt.io/qt-6.4/qml-color.html) that can be specified by SVG color name or hexadecimal form.
- `Path`: Linux filesystem path.
- `Url`: Qt QML url type, [see more](https://doc.qt.io/qt-6.4/qml-url.html).
- `Numeric`: valid numeric integer or decimal number.

## Recognized Groups

The following table shows groups that contain keys that the Window Manager recognize and support.

| Group                                                         | Description                                                        |
|---------------------------------------------------------------|--------------------------------------------------------------------|
| [Settings](#keys-recognized-in-group-settings)                | General settings                                                   |
| [Background](#keys-recognized-in-group-background)            | Visual settings for the background                                 |
| [QuickBar](#keys-recognized-in-group-quickbar)                | QuickBar settings                                                  |
| [QuickBarElements](#keys-recognized-in-group-quickbarelements)| Visual settings for QuickBar elements                              |
| [LayoutSelector](#keys-recognized-in-group-layoutselector)    | Visual setting for layout selector                                 |
| [Components](#keys-recognized-in-group-components)            | Replacing built in components with user created custom components  |

## Recognized Keys

Here you can find all recognized keys with their definitions for the different [groups](#recognized-groups).

### Keys recognized in group Settings

Table of [keys](#keys) that are recognized in the [group](#recognized-groups) `Settings`.

| [Key](#keys)        | Description                                                                                        |[Type](#key-types)|  Supported Value                           |
|---------------------|----------------------------------------------------------------------------------------------------|-------------------|-------------------------------------------|
| Orientation         | Window Manager orientation.                                                                        | [Numeric](#key-types)  |0,90,180,270 <br> `DEFAULT:0`         |
| QuickBarPosition    | QuickBar position in the Window Manager.                                                           | [Text](#key-types)|LEFT, TOP, RIGHT, BOTTOM <br> `DEFAULT:LEFT`|
| DefaultLayout       | Default layout to use on startup.                                                                  | [Text](#key-types)|Layout ID <br> `DEFAULT:basic`             |
| DefaultClientIcon   | Default icon used for clients without valid specific icon.                          | [Url](#key-types)  | Valid file url <br> `DEFAULT:defaultClientIcon.gif`     |
| DefaultMinimizedMode|Global default MinimizedMode for clients with no preferences.|[Text](#key-types)|See,[X-MinimizedMode](application_registration.html#minimized-mode) <br> `DEFAULT:PAUSED`|
| LayoutsDir            | Path to the directory of layout json files.                                    |[Path](#key-types) | Layout file path <br> `DEFAULT:/etc/window_manager/layouts` |
| ClientsDir            | Path to directory of client .desktop files.                                    |[Path](#key-types) | Desktop file path <br> `DEFAULT:/etc/window_manager/clients`|
| DisableQuickBar       | Hide quickbar and clients cannot be moved. Intended for static client placements.                | [Numeric](#key-types) |0: false , 1: true <br> `DEFAULT:0`    |
| DisableLayoutSelector | Layout selector will be hidden even when more than one layout is present.                        | [Numeric](#key-types) |0: false , 1: true <br> `DEFAULT:0`    |
| DisableRegionSelect   | Disable longpressing Quickbar elements to assign a region.                                       | [Numeric](#key-types) |0: false , 1: true <br> `DEFAULT:0`    |

### Keys recognized in group Background

Table of [keys](#keys) that are recognized in the [group](#recognized-groups) `Background`.

| [Key](#keys)     | Description                                                                   | [Type](#key-types)    | Supported Value                                  |
|------------------|-------------------------------------------------------------------------------|---------------------- |--------------------------------------------------|
|Color             | Background color                                                              | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:#444`        |
|Color2            | Gradient background color from Color (top) to Color2 (bottom), if set         | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:--`          |
|Image             | File url for background image.                                                | [Url](#key-types)     | Valid file url        <br> `DEFAULT:--`          |
|ImageMarginLeft   | Percentage of available screen width from the left of the operational area.   | [Numeric](#key-types) | 0-100                 <br> `DEFAULT:0`           |
|ImageMarginRight  | Percentage of available screen width from the right of the operational area.  | [Numeric](#key-types) | 0-100                 <br> `DEFAULT:0`           |
|ImageMarginTop    | Percentage of available screen height from the top of the operational area.   | [Numeric](#key-types) | 0-100                 <br> `DEFAULT:0`           |
|ImageMarginBottom | Percentage of available screen height from the bottom of the operational area.| [Numeric](#key-types) | 0-100                 <br> `DEFAULT:0`           |
|FillMode          | FillMode for background image.                                                | [Text](#key-types)    |See, [table](#supported-values-for-fillmode) <br> `DEFAULT:FIT`|

#### Supported values for FillMode

Table of supported values for [FillMode](#keys)

| Supported Value  |[Type](#key-types) | Description                                                   |
|------------------|-------------------|---------------------------------------------------------------|
| FIT              | [Text](#key-types)| Default - uniformly scaled to fit without cropping            |
| CROP             | [Text](#key-types)| Contain keys that supports visual settings for the background |
| STRETCH          | [Text](#key-types)| Non-uniformly scaled to fill                                  |
| TILE             | [Text](#key-types)| Duplicate horizontally and vertically                         |
| TILEVERTICALLY   | [Text](#key-types)| Stretch horizontally, tile vertically                         |
| TILEHORIZONTALLY | [Text](#key-types)| Stretch vertically, tile horizontally                         |

### Keys recognized in group QuickBar

Table of [keys](#keys) that are recognized in the [group](#recognized-groups) `QuickBar`.

| [Key](#keys)| Description                                                                               | [Type](#key-types)| Supported Value                                |
|-------------|-------------------------------------------------------------------------------------------|----------------------|---------------------------------------------|
| DividerColor| Color of divider lines.                                                                   | [Color](#key-types)  | Valid QML color value <br> `DEFAULT:#111`   |
| Size        | Percentage for width or height of the quickbar, depending on the position of the quickbar.| [Numeric](#key-types)| 0-100                 <br> `DEFAULT:12`     |
| Color       | Color of the QuickBar background.                                                         | [Color](#key-types)  | Valid QML color value <br> `DEFAULT:#444`   |
| Color2      | Gradient background color from Color (top) to Color2 (bottom), if set                     | [Color](#key-types)  | Valid QML color value <br> `DEFAULT:--`     |
| Spacing     | Spacing between elements inside the QuickBar in percent of QuickBar size.                 | [Numeric](#key-types)| 0-100                 <br> `DEFAULT:10`     | 
| HeaderImage | Image (typically a logo) to show at the top of the QuickBar, behind the label.            | [Url](#key-types)    | Valid file url        <br> `DEFAULT:--`     |
| Label       | Text to show at top of the QuickBar.                                                      | [Text](#key-types)   | Valid characters      <br> `DEFAULT:APPS`   |
| LabelColor  | Color of the QuickBar label.                                                              | [Color](#key-types)  | Valid QML color value <br> `DEFAULT:#ccc`   |
| LabelSize   | Font size of Header in pixels.                                                            | [Numeric](#key-types)| 0-1000                <br> `DEFAULT:16`     |
| LabelBold   | Bold font variant for Header.                                                             | [Numeric](#key-types)| 0: false, 1: true     <br> `DEFAULT:0`      |
| LabelFont   | Font family to use for Header.                                                            | [Text](#key-types)   | Supported font family <br> `DEFAULT:Verdana`|

### Keys recognized in group QuickBarElements

Table of [keys](#keys) that are recognized in the [group](#recognized-groups) `QuickBarElement`.

| [Key](#keys)  | Description                                       | [Type](#key-types)    | Supported Value |
|---------------|---------------------------------------------------|-----------------------|---------------------------------------------|
| OnScreenColor | Color for clients currently on screen             | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:#aaa`   |
| RunningColor  | Color for minimized and running clients           | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:#55a`   |
| PausedColor   | Color for minimized and paused clients            | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:#333`   |
| StoppedColor  | Color for stopped clients                         | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:#522`   |
| Radius        | Radius of QuickBar elements in percent            | [Numeric](#key-types) | 0-50                  <br> `DEFAULT:#10`    |
| ShowLabel     | Show Client label below icon                      | [Numeric](#key-types) | 0: false, 1: true     <br> `DEFAULT:0`      |
| LabelColor    | Specifies the percent of available screen height. | [Color](#key-types)   | Valid QML color value <br> `DEFAULT:#ddd`   |
| LabelSize     | Font height of Client label (in pixels)           | [Numeric](#key-types) | 0-100                 <br> `DEFAULT:#10`    |
| LabelBold     | Use Bold variant of label font                    | [Numeric](#key-types) |0: false, 1: true      <br> `DEFAULT:#0`     |
| LabelFont     | Font family for Client label                      | [Text](#key-types)    |Supported font family  <br> `DEFAULT:Verdana`|

### Keys recognized in group LayoutSelector

Table of [keys](#keys) that are recognized in the [group](#recognized-groups) `LayoutSelector`.

| [Key](#keys)         | Description                                                            | [Type](#key-types)    | Supported Value                                      |
|----------------------|------------------------------------------------------------------------|-----------------------|------------------------------------------------------|
| Radius               | Corner Radius of component in percent of height                        | [Numeric](#key-types) | 0-50                   <br> `DEFAULT:15`             |
| Color                | Background color                                                       | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#555`           |
| Color2               | Gradient background color from Color (top) to Color2 (bottom), if set  | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#--`            |
| BorderColor          | Color of border lines                                                  | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#111`           |
| Label                | Label text to show above value box                                     | [Text](#key-types)    | Valid characters       <br> `DEFAULT:Layout`         |
| LabelColor           | Color of Client label                                                  | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#ddd`           |
| LabelBold            | Bold variant of label font                                             | [Numeric](#key-types) | 0: false, 1: true      <br> `DEFAULT:0`              |
| LabelFont            | Font height of Client label (in pixels)                                | [Text](#key-types)    | Supported font family  <br> `DEFAULT:Verdana`        |
| LabelSizeFactor      | Scale adjustment factor of label font size                             | [Numeric](#key-types) | 0.0-1000.0             <br> `DEFAULT:1.0`            |
| ValueColor           | Color of text in value box                                             | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#ddd`           |
| ValueBackgroundColor | Background color of value box                                          | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#444`           |
|ListColor1|Font color of even index list elements, Background color of odd index list elements | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#ddd`           |
|ListColor2|Font color of odd index list elements, Background color of even index list elements | [Color](#key-types)   | Valid QML color value  <br> `DEFAULT:#444`           |

### Keys recognized in group Components

Table of [keys](#keys) that are recognized in the [group](#recognized-groups) `Components`. For more information about how to create custom components contact your local CrossControl FAE.


| [Key](#keys)              | Description                                                                        | [Type](#key-types)|Supported Value           |
|---------------------------|------------------------------------------------------------------------------------|-------------------|--------------------------|
| QuickBar                  | Custom component to override QuickBar [group](#recognized-groups)                  | [Url](#key-types) |Url to valid QML component|
| SurfaceContainer          | Custom component to override SurfaceContainer [group](#recognized-groups)          | [Url](#key-types) |Url to valid QML component|
| QuickBarElement           | Custom component to override QuickBarElement [group](#recognized-groups)           | [Url](#key-types) |Url to valid QML component|
| RegionSelectorAreaElement | Custom component to override RegionSelectorAreaElement [group](#recognized-groups) | [Url](#key-types) |Url to valid QML component|
| RegionSelector            | Custom component to override RegionSelector [group](#recognized-groups)            | [Url](#key-types) |Url to valid QML component|
| LayoutSelector            | Custom component to override LayoutSelector [group](#recognized-groups)            | [Url](#key-types) |Url to valid QML component|

## Example of config.ini file

``` ini
#General settings
[Settings]
#Default layout to use on start up
DefaultLayout=nested
#Position of the QuickBar in Window Manager
QuickBarPosition=LEFT
#Define path to layout json files
LayoutsDir=/opt/window_manager_application/examples/feature_showcase/layouts
#Define path to Desktop Entry Files
ClientsDir=/opt/window_manager_application/examples/feature_showcase/clients

#Visual settings for Window Manager background  
[Background]
#Set background colors
Color=#333
Color2=#222
#Set image to use in the background
Image=file:///opt/window_manager_application/examples/assets/bgSmoothedDark.png
#Define FillMode for background to be non-uniformly scaled to fill
FillMode=STRETCH

#Visual settings for QuickBar 
[QuickBar]
#Set size of the QuickBar
Size=14
#Set text to show at the top of the Quick, in this example this label is empty
Label=
#Set image to show on top of the Quick bar
HeaderImage=file:///opt/window_manager_application/examples/assets/crosscontrol-rgb.png
#Set image margin to operation area
HeaderImageMarginTop=30
HeaderImageMarginBottom=30
HeaderImageMarginLeft=20
HeaderImageMarginRight=20
#Set QuickBar color
DividerColor=transparent
Color=#ccc
Color2=#999

# Visual settings for QuickBar elements 
[QuickBarElement]
#Set radius of QuickBar element 
Radius=20
#Set color 
Color=#ccc
Color2=#aaa
HighlightColor=#fff
PausedColor=#000
RunningColor=#000
OnScreenColor=#f70
ShowLabel=0

# Visual setting for layout selector  
[LayoutSelector]
#Set color to layout selector
Color=#aaa
Color2=#ccc
BorderColor=#333
LabelColor=#333

#Custom component settings
[Components]
#Setting path to a custom surface container
SurfaceContainer=file:///opt/window_manager_application/examples/feature_showcase/components/DecoratedContainer.qml
```