mirror of
https://github.com/lbonn/rofi
synced 2024-11-15 16:38:00 +00:00
First stab at nicer phrasing of specifications, to be continued
This commit is contained in:
Rasmus Steinke
parent
ce5b8c0216
commit
533517f97b
1 changed files with 32 additions and 39 deletions
|
|
@ -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.
|
||||
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 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.
|
||||
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.
|
||||
A theme can have one or more global properties sections (If there is more than one
|
||||
they will be merged)
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue