Home Forums Wiki Doc Install Extras Screenshots Source Code Projects Blog Users Groups Register
Glx-Dock / Cairo-Dock Wiki A complete tutorial on how to customize your dock
The latest stable release is the *3.4.0* : How to install it here.
Note: We just switched from BZR to Git on Github! (only to host the code and your future pull requests)
History View code

Glx-Dock / Cairo-Dock




en English

fr Français

Support Us

Flattr this


A complete tutorial on how to customize your dock

The purpose of this tutorial :
Cairo-Dock is fully themable, and you can really make your dock behave and look totaly different from any other dock. This ability has a drawback : there are a *lot* of options. This little tutorial doesn't have the ambition to describe all of the options (they are already described in the config panel with a lot of tooltips), but to guide you along the customization of your dock.
It also contains some useful tricks.

First Step :
To start with, you have to install it. Check if it is in your distro's repository; If not, or if you want the latest version, you can grab it from the BerliOS website (sources or .deb). Be sure to install the plug-ins too.

Once it’s installed, run it, and you will be asked to choose a theme. The packaged themes are very nice, and you may be happy just using one of those, but there is probably a configuration that fits your taste the best.
Let's start with the Coz’s "Clear" theme as a starting base, for instance.

Coz's Clear Theme for Cairo-Dock

Switching and saving themes :
A good habit is to save your current theme after you made some changes to it.
Just <right-click> on Cairo-Dock, go to the Cairo-Dock sub-menu, and choose ‘Manage Themes’. The 2nd tab will let you save the current theme, under the name of your choice.

If you want to apply another theme on your dock, go to the 1st tab, choose a theme, and validate.
You can choose to apply the theme's behaviour and/or the launchers behaviour, but you probably want to keep yours, so let the 2 boxes unthicked.

If you want to delete some themes you don't want anymore, go to the 3rd tab, and thick the unwanted themes, then validate, that will delete them.

A quick overview :
To start making your own customisations, <right-click> on Cairo-Dock, go to the Cairo-Dock sub-menu, and choose Configure. If you’re using ’simple mode’ you will only see a couple of tabs that don’t let you do much. Click ‘advanced mode’ in the bottom left corner. You will then see that there are quite a few different settings groups you can modify, and we’ll quickly go through each tab one by one.

The first 4 tabs are about the behaviour of your dock. They are recorded in your theme, but will not be altered by switching to another theme (cf the precedent paragraph).
  • The first tab, Position, can be used to modify where the dock is in relation to the desktop. However, it’s usually easier just to hit alt and drag it where you want it to be. You can also turn on auto-hide and ‘keep below’ features here.
  • The Task-Bar tab is quite interesting. Here you can toggle features like the ‘window’ display - Cairo-Dock can show the current applications in the dock alongside the launcher icons, if you choose. You can configure how launchers and applications are grouped, how application icons display, and so on.
  • The System tab quite technical, but it has a few useful options, namely the option to ‘click to show sub-docks’.
  • The Applets tab is far more handy; here you find some of the fun little gadgets that are being developed and adapted for Cairo-Dock. Just thick an applet's box to activate, or deactivate it. We'll come back later on them, since they offer a lot of possibilities. The only important thing is to be sure that the "rendering" applet is present and activated, as it provides the views of Cairo-Dock.

The 5 next tabs are what interests us the most here, since they define the look of Cairo-Dock, and we will come back to this in more detail later.
  • The Background tab lets you customize everything about he background of the docks : frame, background image, etc.
  • The Icons tab is about the displaying of icons : their sizes, animations, labels, order, etc..
  • The Views tabs changes the way the dock is drawn. Pick up a view, and your dock will appear totally differently ! Once you’ve chosen your view, you can hit preferences to configure it further, such as changing the vanishing point of a 3D dock, so there are also a lot of options there.
  • The Dialogs tab changes the appearance and behaviour of the warning, notice, and general query dialogs that occasionally pop up. You will usually want to set them up accordingly to the dock's background.
  • The Desklet contains a few optins about desklets. Desklets are applets that have been detached from the dock, and live on your desktop.
  • Finally, the Indicators tab let you personnalize all the indicators. These are graphics that are displayed to show something, like the where you can drop something inside the dock, which is the current active window, which launchers are launched, etc

The Background :
Enough talking, let's go !
It is a good idea to follow the tabs' order, so let's start with the Background options.

  • If you're using the auto-hide, you can set up an image to be displayed when the dock is hidden. It is the "callback zone", where you place your cursor to let the dock show up. Usually you will set up a wide and not high rectangular zone, so choose your image accordingly, as it will be stretched to fill it.
  • Then, we'll do the same for the background when the dock is visible. You can choose to display an image in the background, or to fill it with a gradation of 2 colors.
In the 2 cases, you can choose to fill the background by repeating or by stretching the image/gradation.
  • To complete this, we can configure the Extern Frame, which is the line that runs around the edge of your dock : how ’rounded’ the corners of your dock will be, how thick the line around it will be, (or if there will be a line at all), and its colour.

The previous Clear theme, with a different background color.

The Icons :
Now, we will take care of the icons themselves.
  • First we have the famous "wave" effect; what you probably want to set up is the amplitude of he wave, that is to say the maximum zoom.
  • Then we have the reflection of the icons (for views that use it, like the 3D-plane, Carroussel, or Curve views). A medium value will probably fit to most of people.
Note that if you're not using any view that uses reflects, you should set the "Field depth" of the reflects to 0, as it will save some memory.
  • Another interesting point is the Labels, that is to say how the names of each icon is displayed, in particular the font, the size, and the color (once again, a gradation of 2 colors). To be more readable, you may want to display the text on a background.
  • A little extra is to draw a string that links all the icons of a same dock. Just set its width to 0 isf you don't want it.
  • An important point is the icon theme. There are probably already many icons sets on our system (for instance, the Ubuntu's default icons set is Human). Cairo-Dock can search for images in either an icons set or a folder that contains some icons. Here you can add both of them, and Cairo-Dock will search in them, in the order you entered them. We will come back to it i the next chapter.
  • Last, we can set up the size of the icons by type, and also the order of each type of icons.

Adding "Gartoon" in the list of themes changes all the icons at once, giving your dock a completely different feeling.

Changing the images for launchers, applications, and applets :
The way Cairo-Dock display images on your icons is quite simple, and yet generally misunderstood.
Let me explain it in detail here.

  • To change the icon for a single launcher, <right click> on the launcher, select modify this launcher, and change the image’s name or path to the icon you want to use. Using .svg is better than .png because of Cairo’s ability to ‘zoom in’ on active icons.
If you enter a path of an image that is present on your hard disk, this image will be used for the launcher, but then switching to another theme will let you with this icon, since the path is hard-written in the launcher. What you should rather do, is to write just the name of the image, without the extension (so for exemple, to use /home/toto/image.svg, write "image" in the launcher).
But then Cairo-Dock has to know where to search this image. So enter the folder containing your images in the config Panel of the dock, for exemple "/home/toto".

To be compatible with icons set installed on your system, you should rename your image to a "well-known" name, so for exemple if you want to set an image for Nautilus, rename this image to "nautilus.svg', and write "nautilus" in the launcher.
This way, you can completely switch from a set of images to another by just changing them in the config panel of the dock ! you don't need to tiedously change the images in each launchers.
By default, each theme puts its own images in the "launchers" folder, it is a good habit to do the same, so that you can distribute your theme later. So let's place all of our personnal icons in ~/.cairo-dock/current_theme/launchers (it is a hidden folder, so you may need to 'show hidden files' in your file browser)

  • To change the icon for a single applet, <right click> on it, "configure this module", and in the config panel of the applet, you will be able to change the icon, or for some applet, the theme (Clock, Dustbin, Weather, Cpusage, etc)

  • To change the icon for a running application, you first have to activate "Overwrite X icons with launchers" in the Taskbar configuration options. Doing this will tell Cairo-DOck to ignore the crappy icons provided by X, and to search for a better icon. Now, let's say I have Nautilus running, and its corresponding icon in the dock. There is 2 cases :
There is a "Nautilus" launcher in the dock, then Cairo-Dock will just use the same icon for the application, and we're done.
There is no such launcher, then Cairo-Dock will search for an image named "nautilus.xxx", where "xxx" can be "svg", "png", "xpm", etc. There is a great chance that such an icon will be found in the icons set currently used in the dock. If you want to use your own image, just place an image with this name in a folder that is know by the dock (remember , it is a good practice to put all icons in ~/.cairo-dock/current_theme/launchers).
How to name the image ?
Each icon must have the same name as the *class* for the relevant application. The class of an application is most of the time equal to its name, but not always.
To find the class for an application, make sure it’s open, and then go to a terminal and type
xprop | grep WM_CLASS

This will bring up a little pointer, which you use to click on the relevant window. This will call up a range of information on that window, which grep will then search for the WM_CLASS section. The feedback you get will look something like this:
WM_CLASS(STRING) = "abiword", "Abiword"

To get Cairo-Dock to show the correct icon, the icon in current_theme/launchers must be given the same name as the application class, so for example ‘abiword.svg’ or ‘abiword.png’. You will need to set up icons for all the major programs you’re likely to need.

Changing the way docks are rendered :
Each dock can be rendered differently from the others. Changing the rendering of a dock will make it appear in a totally different way.
In the "Views" tab, you can set the default rendering for docks and sub-docks.
For each subdock, you can modify its rendering (<right click>-> "modify this launcher/applet").

Switching to another view really changes the rendering of your dock. Here, the "Curve" view.

The little plus that will distinguish your theme from the others :
  • To make a really personnal and original theme, I think that you should personnalize the indicators.
There are indicators for the drag-and-drop, drag-over, active window, and launched launchers.
The drag-and-drop indicator can be some image oriented from top to bottom, like an arrow, some rain, a starfall, etc
The drag-over indicator is a little emblem being displayed on the icon when you drag something oer it. Its size will be 1/3 of the icon.
The active window indicator is drawn on the icon of the currently active window. you can set an image or just a back/foreground color. You should try to make it discret since it is drawn at the same place and size as the icon.
The launched launchers indicator show you which indicators have been already launched. It is displayed at the bottom of the icon, but you can adjust its position vertically. It can be a circle, a light, etc. It's up to you to choose and place an image that will be easily visible under the icon.

  • The dialogs and desklets can also be configured, and you will probably want to adapt their colors and shape to the dock's background. The "ok" and "cancel" buttons can be chosen to match the global style of the icons in the dock.

  • Having many docks in a single instance of Cairo-Dock :

Choose a launcher or an applet, and open its configuration panel (<right click> -> modify this launcher/applet).
For a launcher, expand the "Extra Parameters", for an applet, go to the first Tab.
There you can set the name of the dock the icon belongs to. Just set a name that doesn't exist yet; a new dock will be created with this name, and the icon placed inside it. You can then populate it with other icons in the same way.
At first this dock will be placed at the bottom middle of the screen; to change it, <right click> on it -> "Cairo-dock" -> "set up this dock".
Each of these docks will share the same configuration though, and thus the same look.

There is a way to have many docks wih different look, but it requires to launch Cairo-dock many times. Launch cairo-dock, and then launch
cairo-dock --modules-dir /path/to/dir

where /path/to/dir will act like the "~/.cairo-dock" folder.

How to configure Cairo-Dock so that it is as light as possible ?
If you feel your dock is running slowly, here are some tricks that can help you.
-The best way to have a smooth dock is to activate the hardware acceleration. You need a nVidia card, and have to compil your libcairo with the --enable-glitz, and then launch the dock with
cairo-dock --glitz

It may not work completely though, as libcairo has recently broken the compatibility with Glitz.
You have to install glitz 0.5.7 and a patch for libcairo made by Gandalfn.
-If it seems too obscur for you, or just doesn't work, let's configure the dock to be lighter.
Try to descrease the icon size. 48x48 is a good size, and the maximum zoom can be decreased to 1.5 or even less (so set the amplitude of the wave to 0.5 in the "Icons" tab).
Also, only show the pointed icon's label can make a great difference (in the "System" tab).
Try to reduce the number of icons into your dock :
- make some sub-docks to group launchers and/or applets by affinity.
- use the TaskBar options to group applications by class, or to only display applications on current desktop.
- use many root docks (see the precedent chapter)
Try to decrease the refresh frequency of some applets : the seconds don't really need to be shown in Clock, the amount of RAM can be checked every 10s in Ram-meter, etc
Try to remove some applets, like the Cairo-Penguin.
Try another view; some views are more eye-candy, but eye-candy has a cost (like "3D-plane" or "Curve"). If you don't use any view that uses reflects, you should set the "Field depth" of the reflects to 0 in the "Icons" tab.
In the "System" tab, untick the option to drawn reflects in real time, and decrease the refresh frequency (don't go under 20Hz, it might have the opposite effect).

=> It's now included !

Conclusion :
I guess your dock now looks totaly different from what it was at the beginning
I hope this little guide has helped you to not get lost during the configuration. If you have any comment/suggestion, feel free to write me at fabounet (at) users [dot] berlios -dot- de, or pay us a visit at http://glx-dock.org !

Fabounet and Lusule.

Glx-Dock / Cairo-Dock Wiki A complete tutorial on how to customize your dock Top

Online users :

Powered by ElementSpeak © 2007 Adrien Pilleboue, 2009-2013 Matthieu Baerts.
Dock based on CSS Dock Menu (Ndesign) with jQuery. Icons by zgegball
Cairo-Dock is a free software under GNU-GPL3 licence. First stable version created by Fabounet.
Many thanks to TuxFamily for the web Hosting and Mav for the domain name.