2
* This file is a part of the Cairo-Dock project
4
* Copyright : (C) see the 'copyright' file.
5
* E-mail : see the 'copyright' file.
7
* This program is free software; you can redistribute it and/or
8
* modify it under the terms of the GNU General Public License
9
* as published by the Free Software Foundation; either version 3
10
* of the License, or (at your option) any later version.
12
* This program is distributed in the hope that it will be useful,
13
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program. If not, see <http://www.gnu.org/licenses/>.
21
#ifndef __CAIRO_DOCK_MODULES__
22
#define __CAIRO_DOCK_MODULES__
26
#include "cairo-dock-struct.h"
27
#include "cairo-dock-desklet.h"
32
*@file cairo-dock-modules.h This class defines and handles the external and internal modules of Cairo-Dock.
34
* A module has an interface and a visit card :
35
* - the visit card allows it to define itself (name, category, default icon, etc)
36
* - the interface defines the entry points for init, stop, reload, read config, and reset datas.
38
* Modules can be instanciated several times; each time they are, an instance is created. This instance will hold all the data used by the module's functions : the icon and its container, the config structure and its conf file, the data structure and a slot to plug datas into containers and icons. All these parameters are optionnal; a module that has an icon is also called an applet.
40
* Internal modules are just simplified version of modules, and are used internally by Cairo-Dock. As a special feature, a module can bind itself to an internal module, if its purpose is to complete it.
43
/// Categories a module can be in.
45
CAIRO_DOCK_CATEGORY_SYSTEM,
46
CAIRO_DOCK_CATEGORY_THEME,
47
CAIRO_DOCK_CATEGORY_APPLET_ACCESSORY,
48
CAIRO_DOCK_CATEGORY_APPLET_DESKTOP,
49
CAIRO_DOCK_CATEGORY_APPLET_CONTROLER,
50
CAIRO_DOCK_CATEGORY_PLUG_IN,
51
CAIRO_DOCK_NB_CATEGORY
52
} CairoDockModuleCategory;
53
#define CAIRO_DOCK_CATEGORY_DESKTOP CAIRO_DOCK_CATEGORY_APPLET_DESKTOP
54
#define CAIRO_DOCK_CATEGORY_ACCESSORY CAIRO_DOCK_CATEGORY_APPLET_ACCESSORY
55
#define CAIRO_DOCK_CATEGORY_CONTROLER CAIRO_DOCK_CATEGORY_APPLET_CONTROLER
57
/// Definition of the visit card of a module.
58
struct _CairoDockVisitCard {
59
/// nom du module qui servira a l'identifier.
60
const gchar *cModuleName;
61
/// numero de version majeure de cairo-dock necessaire au bon fonctionnement du module.
62
gint iMajorVersionNeeded;
63
/// numero de version mineure de cairo-dock necessaire au bon fonctionnement du module.
64
gint iMinorVersionNeeded;
65
/// numero de version micro de cairo-dock necessaire au bon fonctionnement du module.
66
gint iMicroVersionNeeded;
67
/// chemin d'une image de previsualisation.
68
const gchar *cPreviewFilePath;
69
/// Nom du domaine pour la traduction du module par 'gettext'.
70
const gchar *cGettextDomain;
71
/// Version du dock pour laquelle a ete compilee le module.
72
const gchar *cDockVersionOnCompilation;
73
/// version courante du module.
74
const gchar *cModuleVersion;
75
/// repertoire du plug-in cote utilisateur.
76
const gchar *cUserDataDir;
77
/// repertoire d'installation du plug-in.
78
const gchar *cShareDataDir;
79
/// nom de son fichier de conf.
80
const gchar *cConfFileName;
81
/// categorie de l'applet.
82
CairoDockModuleCategory iCategory;
83
/// chemin d'une image pour l'icone du module dans le panneau de conf du dock.
84
const gchar *cIconFilePath;
85
/// taille de la structure contenant la config du module.
87
/// taille de la structure contenant les donnees du module.
89
/// VRAI ssi le plug-in peut etre instancie plusiers fois.
90
gboolean bMultiInstance;
91
/// description et mode d'emploi succint.
92
const gchar *cDescription;
95
/// nom d'un module interne auquel ce module se rattache, ou NULL si aucun.
96
const gchar *cInternalModule;
97
/// nom du module tel qu'affiche a l'utilisateur.
99
/// octets reserves pour preserver la compatibilite binaire lors de futurs ajouts sur l'interface entre plug-ins et dock.
103
/// Definition of the interface of a module.
104
struct _CairoDockModuleInterface {
105
void (* initModule) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
106
void (* stopModule) (CairoDockModuleInstance *pInstance);
107
gboolean (* reloadModule) (CairoDockModuleInstance *pInstance, CairoContainer *pOldContainer, GKeyFile *pKeyFile);
108
gboolean (* read_conf_file) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
109
void (* reset_config) (CairoDockModuleInstance *pInstance);
110
void (* reset_data) (CairoDockModuleInstance *pInstance);
111
void (* load_custom_widget) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
112
void (* save_custom_widget) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
115
/// Definition of an instance of a module.
116
struct _CairoDockModuleInstance {
117
/// the module this instance represents.
118
CairoDockModule *pModule;
119
/// conf file of the instance.
120
gchar *cConfFilePath;
121
/// TRUE if the instance can be detached from docks (desklet mode).
123
/// the icon holding the instance.
125
/// container of the icon.
126
CairoContainer *pContainer;
127
/// this field repeats the 'pContainer' field if the container is a dock, and is NULL otherwise.
129
/// this field repeats the 'pContainer' field if the container is a desklet, and is NULL otherwise.
130
CairoDesklet *pDesklet;
131
/// a drawing context on the icon.
132
cairo_t *pDrawContext;
133
/// a unique ID to insert external data on icons and containers.
135
/*gpointer *myConfig;
139
/// Pre-init function of a module. Fills the visit card and the interface of a module.
140
typedef gboolean (* CairoDockModulePreInit) (CairoDockVisitCard *pVisitCard, CairoDockModuleInterface *pInterface);
142
/// Definition of an external module.
143
struct _CairoDockModule {
144
/// path to the .so file.
146
/// internal structure of the .so file, containing pointers to the module's functions.
148
/// interface of the module.
149
CairoDockModuleInterface *pInterface;
150
/// visit card of the module.
151
CairoDockVisitCard *pVisitCard;
152
/// conf file of the module.
153
gchar *cConfFilePath;
154
/// TRUE if the appet can be detached from a dock (desklet mode).
156
/// last time the module was (re)activated.
157
gdouble fLastLoadingTime;
158
/// List of instances of the module.
159
GList *pInstancesList;
162
struct _CairoDockMinimalAppletConfig {
163
gint iDesiredIconWidth;
164
gint iDesiredIconHeight;
166
gchar *cIconFileName;
169
CairoDeskletAttribute deskletAttribute;
170
gboolean bIsDetached;
174
typedef gpointer CairoInternalModuleConfigPtr;
175
typedef gpointer CairoInternalModuleDataPtr;
176
typedef void (* CairoDockInternalModuleReloadFunc) (CairoInternalModuleConfigPtr *pPrevConfig, CairoInternalModuleConfigPtr *pNewConfig);
177
typedef gboolean (* CairoDockInternalModuleGetConfigFunc) (GKeyFile *pKeyFile, CairoInternalModuleConfigPtr *pConfig);
178
typedef void (* CairoDockInternalModuleResetConfigFunc) (CairoInternalModuleConfigPtr *pConfig);
179
typedef void (* CairoDockInternalModuleResetDataFunc) (CairoInternalModuleDataPtr *pData);
180
struct _CairoDockInternalModule {
181
//\_____________ Carte de visite.
182
const gchar *cModuleName;
183
const gchar *cDescription;
186
CairoDockModuleCategory iCategory;
189
const gchar **cDependencies; // NULL terminated.
190
//\_____________ Interface.
191
CairoDockInternalModuleReloadFunc reload;
192
CairoDockInternalModuleGetConfigFunc get_config;
193
CairoDockInternalModuleResetConfigFunc reset_config;
194
CairoDockInternalModuleResetDataFunc reset_data;
195
//\_____________ Instance.
196
CairoInternalModuleConfigPtr pConfig;
197
CairoInternalModuleDataPtr pData;
198
GList *pExternalModules;
202
void cairo_dock_initialize_module_manager (const gchar *cModuleDirPath);
205
*Verifie que le fichier de conf d'un plug-in est bien present dans le repertoire utilisateur du plug-in, sinon le copie a partir du fichier de conf fournit lors de l'installation. Cree au besoin le repertoire utilisateur du plug-in.
206
*@param pVisitCard la carte de visite du module.
207
*@return Le chemin du fichier de conf en espace utilisateur, ou NULL si le fichier n'a pu etre ni trouve, ni cree.
209
gchar *cairo_dock_check_module_conf_file (CairoDockVisitCard *pVisitCard);
211
void cairo_dock_free_visit_card (CairoDockVisitCard *pVisitCard);
213
/** Load a module into the table of modules. The module is opened and its visit card and interface are retrieved.
214
*@param cSoFilePath path to the .so file.
215
*@param erreur error set if something bad happens.
216
*@return the newly allocated module.
218
CairoDockModule * cairo_dock_load_module (gchar *cSoFilePath, GError **erreur);
220
gboolean cairo_dock_register_module (CairoDockModule *pModule);
222
/** Load all the modules of a given folder.
223
*@param cModuleDirPath path to the a folder containing .so files.
224
*@param erreur error set if something bad happens.
226
void cairo_dock_preload_module_from_directory (const gchar *cModuleDirPath, GError **erreur);
230
void cairo_dock_activate_modules_from_list (gchar **cActiveModuleList, double fTime);
232
void cairo_dock_deactivate_old_modules (double fTime);
235
void cairo_dock_free_module (CairoDockModule *module);
237
GKeyFile *cairo_dock_pre_read_module_instance_config (CairoDockModuleInstance *pInstance, CairoDockMinimalAppletConfig *pMinimalConfig);
239
void cairo_dock_free_minimal_config (CairoDockMinimalAppletConfig *pMinimalConfig);
241
/** Create and initialize all the instances of a module.
242
*@param module the module to activate.
243
*@param erreur error set if something bad happens.
245
void cairo_dock_activate_module (CairoDockModule *module, GError **erreur);
247
/** Stop and destroy all the instances of a module.
248
*@param module the module to deactivate
250
void cairo_dock_deactivate_module (CairoDockModule *module);
252
void cairo_dock_reload_module_instance (CairoDockModuleInstance *pInstance, gboolean bReloadAppletConf);
254
/** Reload all the instances of the module.
255
*@param module the module to reload
256
*@param bReloadAppletConf TRUE to reload the config of the instances before reloading them.
258
void cairo_dock_reload_module (CairoDockModule *module, gboolean bReloadAppletConf);
261
void cairo_dock_deactivate_all_modules (void);
263
void cairo_dock_activate_module_and_load (const gchar *cModuleName);
264
void cairo_dock_deactivate_module_instance_and_unload (CairoDockModuleInstance *pInstance);
265
void cairo_dock_deactivate_module_and_unload (const gchar *cModuleName);
267
void cairo_dock_configure_module_instance (GtkWindow *pParentWindow, CairoDockModuleInstance *pModuleInstance, GError **erreur);
268
void cairo_dock_configure_inactive_module (GtkWindow *pParentWindow, CairoDockModule *pModule);
269
void cairo_dock_configure_module (GtkWindow *pParentWindow, const gchar *cModuleName);
271
/** Get the module which has a given name.
272
*@param cModuleName the unique name of the module.
274
CairoDockModule *cairo_dock_find_module_from_name (const gchar *cModuleName);
276
CairoDockModuleInstance *cairo_dock_foreach_desklet (CairoDockForeachDeskletFunc pCallback, gpointer user_data);
277
CairoDockModule *cairo_dock_foreach_module (GHRFunc pCallback, gpointer user_data);
278
CairoDockModule *cairo_dock_foreach_module_in_alphabetical_order (GCompareFunc pCallback, gpointer user_data);
281
gchar *cairo_dock_list_active_modules (void);
282
void cairo_dock_update_conf_file_with_active_modules (void);
284
void cairo_dock_update_module_instance_order (CairoDockModuleInstance *pModuleInstance, double fOrder);
287
CairoDockModuleInstance *cairo_dock_instanciate_module (CairoDockModule *pModule, gchar *cConfFilePah);
288
void cairo_dock_free_module_instance (CairoDockModuleInstance *pInstance);
289
void cairo_dock_unregister_module (const gchar *cModuleName);
290
void cairo_dock_stop_module_instance (CairoDockModuleInstance *pInstance);
291
void cairo_dock_deinstanciate_module (CairoDockModuleInstance *pInstance);
293
void cairo_dock_remove_module_instance (CairoDockModuleInstance *pInstance);
294
void cairo_dock_add_module_instance (CairoDockModule *pModule);
296
void cairo_dock_read_module_config (GKeyFile *pKeyFile, CairoDockModuleInstance *pInstance);
299
gboolean cairo_dock_reserve_data_slot (CairoDockModuleInstance *pInstance);
300
void cairo_dock_release_data_slot (CairoDockModuleInstance *pInstance);
302
#define cairo_dock_get_icon_data(pIcon, pInstance) ((pIcon)->pDataSlot[pInstance->iSlotID])
303
#define cairo_dock_get_container_data(pContainer, pInstance) ((pContainer)->pDataSlot[pInstance->iSlotID])
305
#define cairo_dock_set_icon_data(pIcon, pInstance, pData) \
306
(pIcon)->pDataSlot[pInstance->iSlotID] = pData
307
#define cairo_dock_set_container_data(pContainer, pInstance, pData) \
308
(pContainer)->pDataSlot[pInstance->iSlotID] = pData
311
void cairo_dock_reload_internal_module_from_keyfile (CairoDockInternalModule *pModule, GKeyFile *pKeyFile);
312
void cairo_dock_preload_internal_modules (GHashTable *pModuleTable);
314
void cairo_dock_reload_internal_module (CairoDockInternalModule *pModule, const gchar *cConfFilePath);
316
CairoDockInternalModule *cairo_dock_find_internal_module_from_name (const gchar *cModuleName);
318
gboolean cairo_dock_get_internal_module_config (CairoDockInternalModule *pModule, GKeyFile *pKeyFile);
320
gboolean cairo_dock_get_global_config (GKeyFile *pKeyFile);
323
void cairo_dock_popup_module_instance_description (CairoDockModuleInstance *pModuleInstance);
326
void cairo_dock_attach_to_another_module (CairoDockVisitCard *pVisitCard, const gchar *cOtherModuleName);
328
#define cairo_dock_module_is_auto_loaded(pModule) (pModule->pInterface->initModule == NULL || pModule->pInterface->stopModule == NULL || pModule->pVisitCard->cInternalModule != NULL)
330
int cairo_dock_get_nb_modules (void);
added
removed
src/cairo-dock-modules.h
