diff options
| -rw-r--r-- | doc/theme3/specification.md | 73 |
1 files changed, 33 insertions, 40 deletions
diff --git a/doc/theme3/specification.md b/doc/theme3/specification.md index 5ee1bcae..44854863 100644 --- a/doc/theme3/specification.md +++ b/doc/theme3/specification.md @@ -1,18 +1,17 @@ # Theme format 3.0 -Rofi is now at the 3rd version of it theming format. Where previous formats was -a basic version with an extension. This format is a full rewrite. Internally in -**rofi** the way the interface is build up is changed in the past releases. -Instead of having widgets placed on a canvas and moved when needed, widgets are -now placed in containers that hierarchically recompute the locations. This -change also allowed for a better theming format. The new format is loosely -modelled after [css](https://en.wikipedia.org/wiki/Cascading_Style_Sheets). -This will hopefully be familiar and make it easier for people to get started -with theming. - -This file is organized as follow, first we give the specification of the file -format. In the second part we will list the possible options. In the final -section a few examples are shown. +The way rofi handled widgets has changed in the last few releases. Widgets are now +put into containers, allowing themes to be much more flexible than before. +To expose these new theming abilities a new theming format has been created, replacing the old one. +It is loosely based on [css](https://en.wikipedia.org/wiki/Cascading_Style_Sheets), a format +widely known, which allows e.g. web developers to create their own rofi themes without learning +a new markup. + +This file is split up into 3 sections: + +1. Specification of the file format +2. List of possible options +3. Examples ## File Format Specification @@ -28,7 +27,7 @@ C and C++ file comments are support. * Anything after `// ` and before a newline is considered a comment. * Everything between `/*` and `*/` is a comment. -Comments can be nested and the C++ comments inline. +Comments can be nested and the C++ comments can be inline. The following is valid: ```css @@ -63,18 +62,16 @@ name ### File extension The preferred file extension for the new theme format is **rasi**. This is an -abbreviation for **r**ofi **a**advanced **s**tyle **i**nformation (Or the nick -of the user that helped form the new specification). +abbreviation for **r**ofi **a**advanced **s**tyle **i**nformation. ### Basic Structure -At the top level of the file there sections. -There exist two type of sections: - * Global properties section. - * Element theme section. +Each element has a section with defined properties. Properties can be inherited +to sub-sections. Global properties can be defined in section `* { }`. +Sub-section names begin with a hash symbol `#`. -The *global properties section* should always be the first section, it is -followed by one or more *element theme sections*. All sections are optional. +It is advised to define the *global properties section* on top of the file to +make inheritance of properties clearer. ``` /* Global properties section */ @@ -93,14 +90,12 @@ followed by one or more *element theme sections*. All sections are optional. #### Global properties section -Each theme has one, optional, global properties list. -If present, the global properties section has the be the first section in the file. - -The global properties section is special, as the properties here denote the -defaults for each element. Reference properties (see properties section) can -only link to properties in this section. +A theme can have one or more global properties sections (If there is more than one +they will be merged) -The section may only contain a `*` before the brace open.. +The global properties section denotes the defaults for each element. +Each property of this section can be referenced with `@{identifier}` +(See Properties section) #### Element theme section @@ -108,7 +103,7 @@ A theme can have multiple element theme sections. The element path can consist of multiple names separated by whitespace or dots. Each element may contain any number of letters, numbers and '-'. -The first element should always start with a `#``. +The first element should always start with a `#`. This is a valid element name: @@ -124,13 +119,13 @@ And is identical to: } ``` -Each section inherits the properties of it parents. If the property is -specified both in the parent, or the global section, as in the child, the -childs property has priority. +Each section inherits the properties of its parents. Inherited properties +can be overridden by defining them again in the section itself. So `#window mainbox` will contain all properties of `#window` and `#window mainbox`. In the following example: + ```css #window { a: 1; @@ -164,8 +159,8 @@ The properties in a section consist of: Both fields are manditory for a property. -The `identifier` names the property specified. Identifier can consist of any -combination of numbers, letters and '-'. It may not contain any whitespace. +The `identifier` names the specified property. Identifiers can consist of any +combination of numbers, letters and '-'. It must not contain any whitespace. The structure of the `value` defines the type of the property. The current theme format support different type: @@ -246,7 +241,6 @@ dynamic: false; Where '{HEX}' is a hexidecimal number ('0-9a-f'). The '{INTEGER}' value can be between 0 and 255, the '{Real}' value between 0.0 and 1.0. - The first formats specify the color as RRGGBB (R = red, G = green, B = Blue), the second adds an alpha (A) channel: AARRGGB. @@ -273,7 +267,6 @@ It currently supports: * `dash`: A dashed line. Where the gap is the same width as the dash. * `solid`: A solid line. - ##### Distance * Format: `{Integer}px` @@ -301,7 +294,7 @@ and right side and 108 pixels on the top and bottom. * Format: `{Distance} {Distance} {Distance}` * Format: `{Distance} {Distance} {Distance} {Distance}` -If no unit is set, it assumes pixels. +If no unit is set, pixels are used. The different number of fields in the formats are parsed like: * 1 field: `all` @@ -401,7 +394,7 @@ These are appended after the name or class of the widget. `#window.mainbox.listview.element selected.urgent { }` -Currently only the entrybox and scrollbar has states: +Currently only the entrybox and scrollbar have states: `{visible modifier}.{state}` @@ -427,7 +420,7 @@ Example: Sets all selected textboxes marked active to the given foreground and background color. -The scrollbar when drawing uses the `handle` state when drawing the small scrollbar handle. +The scrollbar uses the `handle` state when drawing the small scrollbar handle. Allowing overriding of color. |