Home Forums Wiki Doc Install Extras Screenshots Source Code Projects Blog Users Groups Register
Glx-Dock / Cairo-Dock List of forums Website | Le site web remanier la partie dev
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)
Website | Le site web

Subjects Author Language Messages Last message
[Locked] remanier la partie dev
fabounet Français 8 matttbe [Read]
21 December 2010 à 01:33

fabounet, Tuesday 14 December 2010 à 16:58


Subscription date : 30 November 2007
Messages : 17118
je propose de remanier un peu cette partie, qui n'est vraiment pas visible.
par exemple dans le bandeau du haut, enlever "sources", et faire une page pour "doc" qui contient :
- le tuto que je viens d'écrire sur comment écrire une applet
- lien vers la doc C
- lien vers la doc DBus
- lien vers les sources
Je poste le tuto ici pour voir comment l'intégrer au mieux.
=== Introduction ===
There are 2 ways to write an applet for Cairo-Dock, depending on what kind of applet you want:
- an applet that does fancy things, like some new 3D animations or OpenGL effects, or just that draws its icon dynamically, like a Clock.
-> in this case, go for the C API and let your hacker heart express itself !
- an aplet that just displays some values/text, responds to basic actions like click or scroll, adds entries in the menu and can pop-up dialogs, all in a convenient way.
-> in this case, pick up your favorite langage (yes, literally), write few lines, and be happy with a functionnal applet !

=== Write a full-feature applet in C ===
Cairo-Dock is very modular: it comes with a core library (itself separated in several components) called libgldi (GL Desktop Interface). It exposes a clear and powerful API, that you can use to write any kind of applet.
Most of the time however, writing an applet in C is very straightforward, since a lot of convenient macros are provided.

==== To start: ====
go into the plug-ins folder, and run the script generate-new-applet.sh; answer the few questions, install the applet, restart your dock, and voila! a new applet is available in the config window of Cairo-Dock.

==== To continue: ====
the best is to look at the code of some simple applets like Logout or ShowDesktop.
If you want to write a plug-in that extends the possibilities of the dock (not an applet which has an icon inside the dock), take a look at Icon-effects for instance.
The complete API is described at [[doc.glx-dock.org]], or you can generate it by going into cairo-dock-core/doc and running "generate-doc.sh".

=== Write simply an applet in your favorite language ===
Whatever language you choose, the way is the same: ++write a class that inherits from the **CDApplet** class, and then override the method you need++.
Currently supported languages are Python, Ruby, Mono, Vala, and Bash. You can easily write an interface in any language that support DBus (Java, Perl, etc).
==== Overriding the methods you need ====
The methods available are:
===== Applet definition =====
begin : do here what you need to do when your applet is started
end : if you have anything to do when your applet is terminated
reload : reload your applet with the new config parameters
get_config : get your config parameters from the config keyfile.
===== Actions from the user =====
on_click : action to do when the user clicks on the icon
on_middle_click : same with middle-click
on_scroll : same with scroll up/down
on_build_menu: same with right-click (which opens the menu)
on_menu_select : action to do when the user selects one of the entries you added beforehand in the menu
on_drop_data : action to do when the user drops some data on the icon
on_answer_dialog : action to do when the user answers a dialog you raised beforehand
on_shortkey : action to do when the user triggers a shortkey you registered beforehand
on_change_focus : action to do when the user give or remove the focus on the window controlled by the applet
==== Acting on the icon ====
The CDApplet class holds the main icon of your applet (++icon++), and the sub-icons (the icons in the sub-dock, optional) (++sub_icons++). You can act on the icon and the sub-icons with several methods (examples are given in Python, you can easily adapt):

=====SetQuickInfo=====
Sets the quick-info on our icon (this is a small text displayed on the icon).
ex.: self.icon.SetQuickInfo("123")
=====SetLabel=====
Sets the label of our icon (its name), overwriting the previous one.
ex.: self.icon.SetLabel("Monday")
=====SetIcon=====
Sets the image of our icon, overwriting the previous one.
You can refer to the image by either its name if it's an image from a icon theme, or by a path.
ex.: self.icon.SetIcon("gimp")
ex.: self.icon.SetIcon("gtk-go-up")
ex.: self.icon.SetIcon("/path/to/image")
=====SetEmblem=====
Sets an emblem on our icon. The emblem is drawn directly on the icon, so if you want to remove it, you have to use SetIcon with the original image.
The image is given by its path, and the position of the emblem is fixed by one of the following integer:
UPPER_LEFT, LOWER_RIGHT, LOWER_LEFT, UPPER_RIGHT, MIDDLE
ex.: self.icon.SetEmblem("./emblem-charged.png", UPPER_RIGHT)
=====Animate=====
Animates our icon, with a given animation and for a given number of rounds.
ex.: self.icon.Animate("default",2)
ex.: self.icon.Animate("fire",30)
=====DemandsAttention=====
Like the ++Animate++ method, but will animate the icon endlessly, and the icon
will be visible even if the dock is hidden. If the animation is an empty
string, or "default", the animation used when an application demands the
attention will be used. The first argument is True to start demanding the
attention, and False to stop it.
ex.: self.icon.DemandsAttention(True,"bounce")
ex.: self.icon.DemandsAttention(False,"")
=====ShowDialog=====
Pops up a simple dialog bubble on our icon, with a given message and for a
given duration (in seconds). The dialog can be closed by clicking on it.
ex.: self.icon.ShowDialog("Cairo-Dock is great!",4)
=====PopupDialog=====
Pops up a dialog bubble on our icon (since 2.2.0). The dialog can contain a
message, an icon, some buttons, and a widget the user can act on.
To get the answer, you need to connect to the "**on_answer_dialog**" signal.
The dialog has several attributes, and the interaction widget too. Each of
these are optionnal.
__dialog attributes:__
* **message** (string) : the message of the dialog (empty by default)
* **icon** (string) : an icon to be displayed next to the message (same
* icon as the applet by default)
* **time-length** (int) : time length of the dialog, in second (unlimited
* duration by default)
* **force-above** (bool): true to force the dialog above (use it with
* parcimony, false by default)
* **use-markup** (bool) : true to use markups (HTML
* **buttons** (string) : images of the buttons, separated by comma ";".
* Adding buttons will trigger an **on_answer_dialog** signal when the user
* press one of them. "ok" and "cancel" are used as keywords for the default
* "ok" and "cancel" buttons defined by the dock.
__widget attributes:__
* **type** (string) : type of the widget (can be "text-entry", "scale",
* "list")
__text-entry attributes:__
* **multi-lines** (bool) : true to have a multi-lines text-entry, ie a
* text-view (false by default)
* **editable** (bool) : whether the user can modify the text or not (true
* by default)
* **visible** (bool) : whether the text will be visible or not (useful to
* type passwords) (true by default)
* **nb-chars** (int) : maximum number of chars (the current number of
* chars will be displayed next to the entry) (infinite by default)
* **initial-value** (string): text initially contained in the entry (empty by
* default)
__scale attributes:__
* **min-value** (double) : lower value (0 by default)
* **max-value** (double) : upper value (100 by default)
* **nb-digit** (int) : number of digits after the dot (2 by default)
* **initial-value** (double): value initially set to the scale (0 by default)
* **min-label** (string) : label displayed on the left of the scale (empty
* by default)
* **max-label** (string) : label displayed on the right of the scale (empty
* by default)
__list attributes:__
* **editable** (bool) : true if a non-existing choice can be entered by
* the user (in this case, the content of the widget will be the selected text,
* and not the number of the selected line) (false by default)
* **values** (string) : a list of values, separated by comma ";", used to
* fill the combo list.
* **initial-value** (string or int, depending on the "editable" attribute) :
* the initial selection (the number of line or the initial text depending on
* the "editable" attribute) (0 or empty by default)
The following example pops up a simple message for 5 seconds.
ex.: self.icon.PopupDialog( {"message" : "Hello World!",
             "time-length" : 5},
             {} )
The following example pops up a dialog to select a password of 30 characters max.
ex.: self.icon.PopupDialog( {"message" : "Enter your password:",
             "buttons" : "ok;cancel",
             "icon" : "gtk-stock-edit"},
             {"widget-type" : "text-entry",
             "visible" : false,
             "nb-chars" : 30} )
=====AddDataRenderer=====
This method lets you add a ++data renderer++, that is to say a gauge, graph, etc.
You define the data renderer with a type ("gauge", "graph"), the number of values to render, and a theme.
ex.: self.icon.AddDataRenderer("gauge",2,"Turbo-night-fuel")
=====RenderValues=====
Renders some values on your icon. You must have added a data renderer before
with the previous method.
The number of values you send to the dock is the one you defined with the
previous method. Values are given between 0 and 1.
ex.: self.icon.RenderValues([0.7, 0.2])
=====ControlAppli=====
Makes your applet control the window of an external application, instead of the Taskbar (Logout, MusicPlayer and System-Monitor use this feature).
The parameter is the class of the application you wish to control (which is most of the time the name of the appli, but not always; use "xprop | grep CLASS" to find it), or "none" to stop controlling any appli. You can then override the ++on_change_focus++ method if you need to track the active state of the application.
ex.: self.icon.ControlAppli("pidgin")
=====BindShortkey=====
Bind ++keyboard shortcuts++ to your applet (since 2.2.0). You can bind several shortkey at once, since the method takes an array as input.
Override the method **on_shortkey** to be notified when the shortkey is pressed.
ex.: self.icon.BindShortkey(["<Control>F8","<Control><Shift>Z"])
=====AddMenuItems=====
It allows you to add any kind of entries to the menu that is popped up on a right-click (so you can only use this method in the **on_build_menu** method).
It takes a an array of dicts as parameter. Each dict represents 1 menu-item.
The dict contains the properties of the menu-item in the form of variants :
**type** (integer) : 0 <-> normal entry, 1 <-> sub-menu, 2 <-> separator, 3 <-> check-box, 4 <-> grouped radio-box. By default it is 0.
**label** (string) : the text displayed in the menu-item.
**icon** (string) : a GTK stock icon, or the path to an image. (optionnal)
**id** (integer) : the ID of the menu-item, that will be passed to the ++on_menu_select++ method when it is selected by the user.
**menu** (integer) : the ID of a menu where the menu-item will be placed : 0 <-> the main menu, -1 <-> the default sub-menu (it is automatically built and contains at least the applet's handbook), another integer <-> the ID of a previously added sub-menu. By default it is -1.
**state** (boolean) : the state of the entry in the case of a check-box or a radio-button. By default it is False.
**tooltip** (string): a tooltip (message that will appear when you let the mouse over the item). (optionnal)
When the user chooses one of these entries, you will get a "++on_menu_select++" signal with the ID of the selected entry.
The following exemple in Python will insert a normal entry in the main menu, followed by a separator and a sub-menu, in which there will be a check-box and an entry, and will insert a group of 3 radio-buttons in the default sub-menu, the 2nd button being active.
ex.: self.icon.AddMenuItems( {"widget-type" : 0,
             "label": "this is an entry of the main menu",
                 "icon" : "gtk-add",
                 "menu" : 0,
                 "id" : 1,
                 "tooltip" : "this is the tooltip that will appear when you hover this entry"},
             {"widget-type" : 2,
             "menu" : 0},
             {"widget-type" : 1,
                 "label": "this is a sub-menu",
                 "icon" : "/path/to/image",
                 "menu" : 0,
                 "id" : 2},
             {"widget-type" : 3,
             "label": "this entry can be true or false",
             "icon" : "/path/to/another/image",
             "menu" : 1,
             "state": True,
             "id" : 101},
             {"widget-type" : 0,
             "label": "bla bla bla",
             "menu" : 1,
             "id" : 102},
             {"widget-type" : 4,
             "label": "you can choose this entry",
             "menu" : -1,
             "group": 201,
             "id" : 201},
             {"widget-type" : 4,
             "label": "or this one",
             "menu" : -1,
             "group": 201,
             "state": True,
             "id" : 202},
             {"widget-type" : 4,
             "label": "or even this one",
             "menu" : -1,
             "group": 201,
             "id" : 203} )
=====Get=====
Get a property of the icon of your applet. Current available properties are :
**x** : x position of the icon's center on the screen (starting from 0 on the left)
**y** : y position of the icon's center on the screen (starting from 0 at the top of the screen)
**width** : width of the icon, in pixels (this is the maximum width, when the icon is zoomed)
**height** : height of the icon, in pixels (this is the maximum height, when the icon is zoomed)
**container** : type of container of the applet (DOCK, DESKLET)
**orientation** : orientation of the container on the screen (BOTTOM, TOP, RIGHT, LEFT). A desklet has always an orientation of BOTTOM.
**Xid** : ID of the application's window which is controlled by the applet, or 0 if none (this parameter can only be non nul if you used the method ++ControlAppli++ beforehand).
**has_focus** : whether the application's window which is controlled by the applet is the current active window (it has the focus) or not.
ex.: w = self.icon.Get(width")
=====GetAll=====
Get all the available properties in a dictionnary.
props = self.icon.GetAll()

Methods that act on the sub-icons are the same, except that they take as their first argument the ID of the icon (a unique string that you have assigned to each icon when using the ++AddSubIcons++ method).

matttbe, Tuesday 14 December 2010 à 21:30


Subscription date : 24 January 2009
Messages : 12573
Et pourquoi pas utiliser des pages de wiki pour y afficher : "Comment contribuer": by...
  • Coding
  • Translating
  • Giving ideas
  • $
  • (...)

fabounet, Wednesday 15 December 2010 à 13:10


Subscription date : 30 November 2007
Messages : 17118
en fait on a déjà un peu ça sur le wiki, et justement je trouve que ça ne le rend pas très visible.
il faudrait qu'on puisse atterrir directement sur la page de dèv.
je vois plus le wiki comme les conseils pour installer, configurer, régler les problèmes récurrents, etc.
bien sûr on pourrait aussi ajouter un lien dans le wiki vers la page de dèv.

matttbe, Wednesday 15 December 2010 à 13:50


Subscription date : 24 January 2009
Messages : 12573
Que penses-tu de ceci: => http://www.glx-dock.org/ww_page.php?p=Documentation&lang=en (au-moins l'intro à traduire)

Sinon, une autre page wiki pour intégrer le "How To Contribute" avec que de grosses icônes pour renvoyer vers cette page (by coding), by Translating (lp), by giving ideas (forum), by rapporting bugs (forum ou lp?), by donning, by, ... ?

fabounet, Wednesday 15 December 2010 à 16:40


Subscription date : 30 November 2007
Messages : 17118
oui, pas mal du tout, merci !
j'ai un peu raccourci l'intro (je suis pas fan des grosses boîtes jaunes )
du coup on peut supprimer l'onglet "sources", étant donné qu'on le retrouve dans la partie "install" et "doc".

matttbe, Wednesday 15 December 2010 à 18:45


Subscription date : 24 January 2009
Messages : 12573
Voilà, j'ai un peu complété la partie Documentation et créé How to contribute.

Il faudrait les traduire mais aussi améliorer le How to contribute, surtout avec de beaux boutons. J'en avais déjà vu mais... n'hésitez surtout pas à en proposer!

fabounet, Friday 17 December 2010 à 16:45


Subscription date : 30 November 2007
Messages : 17118
tiens c'est dommage qu'il ne redirige pas automatiquement sur la version anglaise si la version de notre langue n'existe pas.

en tout cas ça fait 2 pages qui sont très bien, j'ai lié la doc au menu Doc du bandeau, et j'ai remplacé les parties Development & Translation du wiki avec elles.

Edit : au fait, est-ce que le "Home" du bandeau ne pourrait pas être mis sur le logo ? la plupart des sites font ça, et ça pourrait alléger un peu le bandeau.

ppmt, Friday 17 December 2010 à 19:24


Subscription date : 29 November 2007
Messages : 3520
J'ai traduit la page "How to contribute" en francais

matttbe, Tuesday 21 December 2010 à 01:33


Subscription date : 24 January 2009
Messages : 12573
Merci ppmt

@ fabounet: Yep, je prends note !

Website | Le site web

Subjects Author Language Messages Last message
[Locked] remanier la partie dev
fabounet Français 8 matttbe [Read]
21 December 2010 à 01:33


Glx-Dock / Cairo-Dock List of forums Website | Le site web remanier la partie dev 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.