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-factory.h"
28
#include "cairo-dock-desklet-manager.h"
33
*@file cairo-dock-modules.h This class defines and handles the external and internal modules of Cairo-Dock.
35
* A module has an interface and a visit card :
36
* - the visit card allows it to define itself (name, category, default icon, etc)
37
* - the interface defines the entry points for init, stop, reload, read config, and reset datas.
39
* 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.
41
* 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.
44
struct _CairoDockModuleMgr {
46
void (*foreach_module) (GHRFunc pCallback, gpointer user_data);
47
void (*foreach_module_in_alphabetical_order) (GCompareFunc pCallback, gpointer user_data);
48
CairoDockModule* (*find_module_from_name) (const gchar *cModuleName);
49
int (*get_nb_modules) (void);
50
const gchar* (*get_modules_dir) (void);
51
gchar* (*list_active_modules) (void);
52
void (*write_active_modules_cb) (void);
55
/// Categories a module can be in.
57
CAIRO_DOCK_CATEGORY_BEHAVIOR=0,
58
CAIRO_DOCK_CATEGORY_THEME,
59
CAIRO_DOCK_CATEGORY_APPLET_FILES,
60
CAIRO_DOCK_CATEGORY_APPLET_INTERNET,
61
CAIRO_DOCK_CATEGORY_APPLET_DESKTOP,
62
CAIRO_DOCK_CATEGORY_APPLET_ACCESSORY,
63
CAIRO_DOCK_CATEGORY_APPLET_SYSTEM,
64
CAIRO_DOCK_CATEGORY_APPLET_FUN,
65
CAIRO_DOCK_NB_CATEGORY
66
} CairoDockModuleCategory;
69
CAIRO_DOCK_MODULE_IS_PLUGIN = 0,
70
CAIRO_DOCK_MODULE_CAN_DOCK = 1<<0,
71
CAIRO_DOCK_MODULE_CAN_DESKLET = 1<<1,
72
CAIRO_DOCK_MODULE_CAN_OTHERS = 1<<2
73
} CairoDockModuleContainerType;
76
/// Definition of the visit card of a module. Contains everything that is statically defined for a module.
77
struct _CairoDockVisitCard {
78
// nom du module qui servira a l'identifier.
79
const gchar *cModuleName;
80
// numero de version majeure de cairo-dock necessaire au bon fonctionnement du module.
81
gint iMajorVersionNeeded;
82
// numero de version mineure de cairo-dock necessaire au bon fonctionnement du module.
83
gint iMinorVersionNeeded;
84
// numero de version micro de cairo-dock necessaire au bon fonctionnement du module.
85
gint iMicroVersionNeeded;
86
// chemin d'une image de previsualisation.
87
const gchar *cPreviewFilePath;
88
// Nom du domaine pour la traduction du module par 'gettext'.
89
const gchar *cGettextDomain;
90
// Version du dock pour laquelle a ete compilee le module.
91
const gchar *cDockVersionOnCompilation;
92
// version courante du module.
93
const gchar *cModuleVersion;
94
// repertoire du plug-in cote utilisateur.
95
const gchar *cUserDataDir;
96
// repertoire d'installation du plug-in.
97
const gchar *cShareDataDir;
98
// nom de son fichier de conf.
99
const gchar *cConfFileName;
100
// categorie de l'applet.
101
CairoDockModuleCategory iCategory;
102
// chemin d'une image pour l'icone du module dans le panneau de conf du dock.
103
const gchar *cIconFilePath;
104
// taille de la structure contenant la config du module.
106
// taille de la structure contenant les donnees du module.
108
// VRAI ssi le plug-in peut etre instancie plusiers fois.
109
gboolean bMultiInstance;
110
// description et mode d'emploi succint.
111
const gchar *cDescription;
113
const gchar *cAuthor;
114
// nom d'un module interne auquel ce module se rattache, ou NULL si aucun.
115
const gchar *cInternalModule;
116
// nom du module tel qu'affiche a l'utilisateur.
118
CairoDockModuleContainerType iContainerType;
119
gboolean bStaticDeskletSize;
120
// octets reserves pour preserver la compatibilite binaire lors de futurs ajouts sur l'interface entre plug-ins et dock.
124
/// Definition of the interface of a module.
125
struct _CairoDockModuleInterface {
126
void (* initModule) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
127
void (* stopModule) (CairoDockModuleInstance *pInstance);
128
gboolean (* reloadModule) (CairoDockModuleInstance *pInstance, CairoContainer *pOldContainer, GKeyFile *pKeyFile);
129
gboolean (* read_conf_file) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
130
void (* reset_config) (CairoDockModuleInstance *pInstance);
131
void (* reset_data) (CairoDockModuleInstance *pInstance);
132
void (* load_custom_widget) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
133
void (* save_custom_widget) (CairoDockModuleInstance *pInstance, GKeyFile *pKeyFile);
136
/// Definition of an instance of a module. A module can be instanciated several times.
137
struct _CairoDockModuleInstance {
138
/// the module this instance represents.
139
CairoDockModule *pModule;
140
/// conf file of the instance.
141
gchar *cConfFilePath;
142
/// TRUE if the instance can be detached from docks (desklet mode).
144
/// the icon holding the instance.
146
/// container of the icon.
147
CairoContainer *pContainer;
148
/// this field repeats the 'pContainer' field if the container is a dock, and is NULL otherwise.
150
/// this field repeats the 'pContainer' field if the container is a desklet, and is NULL otherwise.
151
CairoDesklet *pDesklet;
152
/// a drawing context on the icon.
153
cairo_t *pDrawContext;
154
/// a unique ID to insert external data on icons and containers.
156
/*gpointer *myConfig;
160
/// Pre-init function of a module. Fills the visit card and the interface of a module.
161
typedef gboolean (* CairoDockModulePreInit) (CairoDockVisitCard *pVisitCard, CairoDockModuleInterface *pInterface);
163
/// Definition of an external module.
164
struct _CairoDockModule {
165
/// path to the .so file.
167
/// internal structure of the .so file, once it has been opened.
169
/// interface of the module.
170
CairoDockModuleInterface *pInterface;
171
/// visit card of the module.
172
CairoDockVisitCard *pVisitCard;
173
/// conf file of the module.
174
gchar *cConfFilePath;
175
/// TRUE if the appet can be detached from a dock (desklet mode).
177
/// last time the module was (re)activated.
178
gdouble fLastLoadingTime;
179
/// List of instances of the module.
180
GList *pInstancesList;
183
struct _CairoDockMinimalAppletConfig {
184
gint iDesiredIconWidth;
185
gint iDesiredIconHeight;
187
gchar *cIconFileName;
190
gboolean bAlwaysVisible;
191
CairoDeskletAttribute deskletAttribute;
192
gboolean bIsDetached;
196
typedef gpointer CairoInternalModuleConfigPtr;
197
typedef gpointer CairoInternalModuleDataPtr;
198
typedef void (* CairoDockInternalModuleReloadFunc) (CairoInternalModuleConfigPtr *pPrevConfig, CairoInternalModuleConfigPtr *pNewConfig);
199
typedef gboolean (* CairoDockInternalModuleGetConfigFunc) (GKeyFile *pKeyFile, CairoInternalModuleConfigPtr *pConfig);
200
typedef void (* CairoDockInternalModuleResetConfigFunc) (CairoInternalModuleConfigPtr *pConfig);
201
typedef void (* CairoDockInternalModuleResetDataFunc) (CairoInternalModuleDataPtr *pData);
202
struct _CairoDockInternalModule {
203
//\_____________ Carte de visite.
204
const gchar *cModuleName;
205
const gchar *cDescription;
208
CairoDockModuleCategory iCategory;
211
const gchar **cDependencies; // NULL terminated.
212
//\_____________ Interface.
213
CairoDockInternalModuleReloadFunc reload;
214
CairoDockInternalModuleGetConfigFunc get_config;
215
CairoDockInternalModuleResetConfigFunc reset_config;
216
CairoDockInternalModuleResetDataFunc reset_data;
217
//\_____________ Instance.
218
CairoInternalModuleConfigPtr pConfig;
219
CairoInternalModuleDataPtr pData;
220
GList *pExternalModules;
228
void cairo_dock_initialize_module_manager (const gchar *cModuleDirPath);
230
/** Get the module which has a given name.
231
*@param cModuleName the unique name of the module.
233
CairoDockModule *cairo_dock_find_module_from_name (const gchar *cModuleName);
235
CairoDockModule *cairo_dock_foreach_module (GHRFunc pCallback, gpointer user_data);
236
CairoDockModule *cairo_dock_foreach_module_in_alphabetical_order (GCompareFunc pCallback, gpointer user_data);
238
int cairo_dock_get_nb_modules (void);
240
const gchar *cairo_dock_get_modules_dir (void);
242
gchar *cairo_dock_list_active_modules (void);
244
#define cairo_dock_module_is_auto_loaded(pModule) (pModule->pInterface->initModule == NULL || pModule->pInterface->stopModule == NULL || pModule->pVisitCard->cInternalModule != NULL)
251
/* 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.
252
*@param pVisitCard la carte de visite du module.
253
*@return Le chemin du fichier de conf en espace utilisateur, ou NULL si le fichier n'a pu etre ni trouve, ni cree.
255
gchar *cairo_dock_check_module_conf_file (CairoDockVisitCard *pVisitCard);
257
void cairo_dock_free_visit_card (CairoDockVisitCard *pVisitCard);
259
gboolean cairo_dock_register_module (CairoDockModule *pModule);
260
void cairo_dock_unregister_module (const gchar *cModuleName);
262
/** Load a module into the table of modules. The module is opened and its visit card and interface are retrieved.
263
*@param cSoFilePath path to the .so file.
264
*@param erreur error set if something bad happens.
265
*@return the newly allocated module.
267
CairoDockModule * cairo_dock_load_module (gchar *cSoFilePath, GError **erreur);
269
/** Load all the modules of a given folder.
270
*@param cModuleDirPath path to the a folder containing .so files.
271
*@param erreur error set if something bad happens.
273
void cairo_dock_load_modules_in_directory (const gchar *cModuleDirPath, GError **erreur);
276
/////////////////////
277
// MODULE INSTANCE //
278
/////////////////////
280
GKeyFile *cairo_dock_pre_read_module_instance_config (CairoDockModuleInstance *pInstance, CairoDockMinimalAppletConfig *pMinimalConfig);
282
/* Cree une nouvelle instance d'un module. Cree l'icone et le container associe, et les place ou il faut.
284
CairoDockModuleInstance *cairo_dock_instanciate_module (CairoDockModule *pModule, gchar *cConfFilePah);
286
/** Stop and free a module instance. If it was an applet, the icon is not destroyed (but is no more a valid applet). If it was in a desklet, the desklet is destroyed.
287
*@param pInstance the instance to stop.
289
void cairo_dock_deinstanciate_module (CairoDockModuleInstance *pInstance);
291
/** Reload an instance of a module.
292
*@param pInstance the instance to reload
293
*@param bReloadAppletConf TRUE to reload the config of the instance before reloading it.
295
void cairo_dock_reload_module_instance (CairoDockModuleInstance *pInstance, gboolean bReloadAppletConf);
302
void cairo_dock_free_module (CairoDockModule *module);
304
void cairo_dock_free_minimal_config (CairoDockMinimalAppletConfig *pMinimalConfig);
306
/** Create and initialize all the instances of a module.
307
*@param module the module to activate.
308
*@param erreur error set if something bad happens.
310
void cairo_dock_activate_module (CairoDockModule *module, GError **erreur);
312
/** Stop and destroy all the instances of a module.
313
*@param module the module to deactivate
315
void cairo_dock_deactivate_module (CairoDockModule *module);
317
/** Reload all the instances of a module.
318
*@param module the module to reload
319
*@param bReloadAppletConf TRUE to reload the config of the instances before reloading them.
321
void cairo_dock_reload_module (CairoDockModule *module, gboolean bReloadAppletConf);
324
void cairo_dock_activate_modules_from_list (gchar **cActiveModuleList, double fTime);
326
void cairo_dock_deactivate_old_modules (double fTime);
328
void cairo_dock_deactivate_all_modules (void);
331
///////////////////////
332
// MODULES HIGH LEVEL//
333
///////////////////////
335
// activate_module or reload, update_dock, redraw, write
336
void cairo_dock_activate_module_and_load (const gchar *cModuleName);
337
// deactivate_module_instance_and_unload all instances, write
338
void cairo_dock_deactivate_module_and_unload (const gchar *cModuleName);
340
// deactivate_module_instance_and_unload + remove file + rename last instance file
341
void cairo_dock_remove_module_instance (CairoDockModuleInstance *pInstance);
343
gchar *cairo_dock_add_module_conf_file (CairoDockModule *pModule);
344
// cp file + instanciate_module + update_dock_size
345
void cairo_dock_add_module_instance (CairoDockModule *pModule);
346
// update conf file + reload_module_instance
347
void cairo_dock_detach_module_instance (CairoDockModuleInstance *pInstance);
348
// update conf file + reload_module_instance
349
void cairo_dock_detach_module_instance_at_position (CairoDockModuleInstance *pInstance, int iCenterX, int iCenterY);
352
gboolean cairo_dock_reserve_data_slot (CairoDockModuleInstance *pInstance);
353
void cairo_dock_release_data_slot (CairoDockModuleInstance *pInstance);
355
#define cairo_dock_get_icon_data(pIcon, pInstance) ((pIcon)->pDataSlot[pInstance->iSlotID])
356
#define cairo_dock_get_container_data(pContainer, pInstance) ((pContainer)->pDataSlot[pInstance->iSlotID])
358
#define cairo_dock_set_icon_data(pIcon, pInstance, pData) \
359
(pIcon)->pDataSlot[pInstance->iSlotID] = pData
360
#define cairo_dock_set_container_data(pContainer, pInstance, pData) \
361
(pContainer)->pDataSlot[pInstance->iSlotID] = pData
364
//////////////////////
365
// INTERNAL MODULES //
366
//////////////////////
368
void cairo_dock_reload_internal_module_from_keyfile (CairoDockInternalModule *pModule, GKeyFile *pKeyFile);
369
void cairo_dock_preload_internal_modules (GHashTable *pModuleTable);
371
void cairo_dock_reload_internal_module (CairoDockInternalModule *pModule, const gchar *cConfFilePath);
373
CairoDockInternalModule *cairo_dock_find_internal_module_from_name (const gchar *cModuleName);
375
gboolean cairo_dock_get_internal_module_config (CairoDockInternalModule *pModule, GKeyFile *pKeyFile);
377
gboolean cairo_dock_get_global_config (GKeyFile *pKeyFile);
380
void cairo_dock_popup_module_instance_description (CairoDockModuleInstance *pModuleInstance);
382
void cairo_dock_attach_to_another_module (CairoDockVisitCard *pVisitCard, const gchar *cOtherModuleName);
385
void cairo_dock_write_active_modules (void);