|Gauges themes creation or modification is really easy, so don't be afraid to try it.
Custom gauge themes directory is $HOME/.config/cairo-dock/extras/gauges/
If you want to edit one of the downloaded themes, it's better to copy it's directory into another so you won't loose your changes when the theme will be auto updated.
- last-modif : only contains the last modif date (format YYYYMMDD).
- version : only contains the theme version value (integer).
- preview : preview image (format png or jpg).
- readme : theme description shown in applet configuration.
- theme.xml : the main configuration file.
Besides the few common options, you will have to declare at least one indicator key to handle your applet values.
Indicator : One or many ?If your theme defines only one indicator, and the applet using the theme have more than one value to display, it will share the available space between values to display. The indicator options you defined will be used for all gauge values. Only the size and position of each gauge area will change according to the multi_display setting you choosed.
If your theme defines more than indicator, then those multi gauges positions will remain stable, and your theme will always display the same number of gauges. So it would be better used with a number of monitored values close to the number of indicators defined. (too few and you will keep empty values, or if many monitors would be dropped)
Display valueThere is two way to display values :
- Images : The theme will use the current value to choose which image to display from the list. An effect can also be applied to this image before display.
- Needle : The theme will show a needle whose position will depend on current value and theme settings.
Gauge theme keysUsing the XML format, you must provide values between opening and closing XML keys.
The first key is the gauge key which will contain all other options.
- name : Defines theme name. Will be displayed in theme select list.
- author : Author name shown with theme details.
- file : With a parameter key="foreground" or key="background", give the name of an image to add around your gauge image.
- multi_display : Choose how multi gauges are displayed (for themes with only 1 indicator). (More to come if you have ideas or needs).
- 0 : scattered (default) - 2/3 size main gauge on top left for first one. 1/3 size for the next three, with position in that order : bottom right, top right, bottom left. Fifth and higher are dropped.
- 1 : shared - space will be evenly shared between gauges. So if you have 3, each one will have 33.3% width allocated.
- text_zone : Defines the area used to display text value.
- x_center : Position of area center on X axis. From -0.5 to 0.5
- y_center : Position of area center on Y axis. From -0.5 to 0.5
- width : Area width. From 0 to 1
- height : Area height. From 0 to 1
- red : Red part for text color. From 0 to 255
- green : Green part for text color. From 0 to 255
- blue : Blue part for text color. From 0 to 255
The indicator also have different keys depending on which display mode you will use.
You need to provide at least one image to use the image list. The gauge renderer will select which one should be displayed according to the current gauge value.
- file : With a parameter key="image", you must define at least one image to be displayed.
- effect : Effect to apply to the current gauge image. (More to come if you have ideas or needs).
- 0 : no effect (default)
- 1 : crop - from bottom to top
- 2 : stretch - from bottom to top
- 3 : zoom - centered
- 4 : fade
Gauge theme exampleHere is an example of a progress bar like theme with the code of Fluid Reggae.
This is an image theme, with 5 images defined. The same image can be used more than once to extend its display range, so this one only use 3 different images (image will change only on higher values). As the crop effect is activated, this image will be truncated according to the current value. If the monitored value is 24%, the displayed part will be only 24% of the image.
This image will be drawn between a foreground and background images that enhance the display with a few shadows and highlights, and using a textarea with RGB values at 0, adds an almost centered black text on top.
Multiple gauges will be displayed the same way with a shared display so it will adapt to most use cases (multi_display=1)