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_FACTORY__
22
#define __CAIRO_DOCK_FACTORY__
26
#include "cairo-dock-struct.h"
27
#include "cairo-dock-container.h"
31
*@file cairo-dock-dock-factory.h This class defines the Docks, and gives the way to create, destroy, and fill them.
33
* A dock is a container that holds a set of icons and a renderer (also known as view).
35
* It has the ability to be placed anywhere on the screen edges and to resize itself automatically to fit the screen's size.
37
* It supports internal dragging of its icons with the mouse, and dragging of itself with alt+mouse.
39
* A dock can be either a main-dock (not linked to any icon) or a sub-dock (linked to an icon of another dock), and there can be as many docks of each sort as you want.
44
CAIRO_DOCK_BOTTOM = 0,
48
CAIRO_DOCK_INSIDE_SCREEN,
49
CAIRO_DOCK_NB_POSITIONS
50
} CairoDockPositionType;
52
#define CAIRO_DOCK_UPDATE_DOCK_SIZE TRUE
53
#define CAIRO_DOCK_ANIMATE_ICON TRUE
54
#define CAIRO_DOCK_INSERT_SEPARATOR TRUE
56
typedef void (*CairoDockComputeSizeFunc) (CairoDock *pDock);
57
typedef Icon * (*CairoDockCalculateIconsFunc) (CairoDock *pDock);
58
typedef void (*CairoDockRenderFunc) (cairo_t *pCairoContext, CairoDock *pDock);
59
typedef void (*CairoDockRenderOptimizedFunc) (cairo_t *pCairoContext, CairoDock *pDock, GdkRectangle *pArea);
60
typedef void (*CairoDockSetSubDockPositionFunc) (Icon *pPointedIcon, CairoDock *pParentDock);
61
typedef void (*CairoDockGLRenderFunc) (CairoDock *pDock);
62
typedef void (*CairoDockRenderFreeDataFunc) (CairoDock *pDock);
64
/// Dock's renderer, also known as 'view'.
65
struct _CairoDockRenderer {
66
/// function that computes the sizes of a dock.
67
CairoDockComputeSizeFunc compute_size;
68
/// function that computes all the icons' parameters.
69
CairoDockCalculateIconsFunc calculate_icons;
70
/// rendering function (cairo)
71
CairoDockRenderFunc render;
72
/// optimized rendering function (cairo) that only redraw a part of the dock.
73
CairoDockRenderOptimizedFunc render_optimized;
74
/// rendering function (OpenGL, optionnal).
75
CairoDockGLRenderFunc render_opengl;
76
/// function that computes the position of the dock when it's a sub-dock.
77
CairoDockSetSubDockPositionFunc set_subdock_position;
78
/// TRUE if the view uses the OpenGL stencil buffer.
80
/// TRUE is the view uses reflects.
82
/// name displayed in the GUI (translated).
83
const gchar *cDisplayedName;
84
/// path to a readme file that gives a short description of the view.
85
gchar *cReadmeFilePath;
86
/// path to a preview image.
87
gchar *cPreviewFilePath;
88
/// function called when the renderer is unset from the dock.
89
CairoDockRenderFreeDataFunc free_data;
93
CAIRO_DOCK_MOUSE_INSIDE,
94
CAIRO_DOCK_MOUSE_ON_THE_EDGE,
95
CAIRO_DOCK_MOUSE_OUTSIDE
96
} CairoDockMousePositionType;
99
CAIRO_DOCK_INPUT_ACTIVE,
100
CAIRO_DOCK_INPUT_AT_REST,
101
CAIRO_DOCK_INPUT_HIDDEN
102
} CairoDockInputState;
104
/// Definition of a Dock, which derives from a Container.
107
CairoContainer container;
108
/// the list of icons.
110
/// Set to TRUE for the main dock (the first to be created, and the one containing the taskbar).
111
gboolean bIsMainDock;
112
/// number of icons pointing on the dock (0 means it is a root dock, >0 a sub-dock).
115
//\_______________ Config parameters.
116
/// ecart de la fenetre par rapport au bord de l'ecran.
118
/// decalage de la fenetre par rapport au point d'alignement sur le bord de l'ecran.
120
/// alignment, between 0 and 1, on the screen's edge.
122
/// whether the dock automatically hides itself or not.
124
/// Horizontal offset of the screen where the dock lives, according to Xinerama.
126
/// Vertical offset of the screen where the dock lives, according to Xinerama.
128
/// number of the screen the dock is placed on (Xinerama).
131
/// maximum height of the icons.
132
gdouble iMaxIconHeight;
133
/// width of the dock, only taking into account an alignment of the icons.
134
gdouble fFlatDockWidth;
138
gint iMinRightMargin;
140
gint iMaxRightMargin;
144
//\_______________ current state of the dock.
145
/// pour faire defiler les icones avec la molette.
147
/// indice de calcul du coef multiplicateur de l'amplitude de la sinusoide (entre 0 et CAIRO_DOCK_NB_MAX_ITERATIONS).
148
gint iMagnitudeIndex;
149
/// (un)folding factor, between 0(unfolded) to 1(folded). It's up to the renderer on how to make use of it.
150
gdouble fFoldingFactor;
151
/// type d'icone devant eviter la souris, -1 si aucun.
152
gint iAvoidingMouseIconType;
153
/// marge d'evitement de la souris, en fraction de la largeur d'an icon (entre 0 et 0.5)
154
gdouble fAvoidingMouseMargin;
155
/// pointeur sur le 1er element de la liste des icones a etre dessine, en partant de la gauche.
156
GList *pFirstDrawnElement;
157
/// decalage des decorations pour les faire suivre la souris.
158
gdouble fDecorationsOffsetX;
159
/// counter for the fade out effect.
161
/// direction of the fade out effect.
163
/// state of the input shape.
164
/// counter for auto-hide.
167
/// Whether the dock is in a popped up state or not.
169
/// whether the menu is visible (to keep the dock on high position).
170
gboolean bMenuVisible;
171
/// whether the user is dragging something over the dock.
172
gboolean bIsDragging;
173
/// Backup of the auto-hide state before quick-hide.
174
gboolean bAutoHideInitialValue;
175
/// whether mouse can't enter into the dock.
176
gboolean bEntranceDisabled;
177
/// whether the dock is shrinking down.
178
gboolean bIsShrinkingDown;
179
/// whether the dock is growing up.
180
gboolean bIsGrowingUp;
181
/// whether the dock is hiding.
183
/// whether the dock is showing.
185
/// whether an icon is being dragged away from the dock
186
gboolean bIconIsFlyingAway;
188
//\_______________ Source ID of events running on the dock.
189
/// Source ID for window resizing.
190
guint iSidMoveResize;
191
/// Source ID for window popping down to the bottom layer.
193
/// Source ID of the timer that delays the "leave" event.
194
guint iSidLeaveDemand;
195
/// Source ID for pending update of WM icons geometry.
196
guint iSidUpdateWMIcons;
198
//\_______________ Renderer and fields set by it.
199
/// nom de la vue, utile pour (re)charger les fonctions de rendu posterieurement a la creation du dock.
200
gchar *cRendererName;
201
/// current renderer, never NULL.
202
CairoDockRenderer *pRenderer;
203
/// data that can be used by the renderer.
204
gpointer pRendererData;
205
/// Set to TRUE by the renderer if one can drop between 2 icons.
207
/// set by the view to say if the mouse is currently on icons, on the egde, or outside of icons.
208
CairoDockMousePositionType iMousePositionType;
209
/// minimum width of the dock.
211
/// minimum height of the dock.
213
/// maximum width of the dock.
215
/// maximum height of the dock.
217
/// width of background decorations.
218
gint iDecorationsWidth;
219
/// height of background decorations.
220
gint iDecorationsHeight;
221
/// maximal magnitude of the zoom, between 0 and 1.
222
gdouble fMagnitudeMax;
224
//\_______________ input shape.
225
/// state of the input shape (active, at rest, hidden).
226
CairoDockInputState iInputState;
227
/// input shape of the window when the dock is at rest.
228
GdkBitmap* pShapeBitmap;
229
/// input shape of the window when the dock is hidden.
230
GdkBitmap* pHiddenShapeBitmap;
232
gint iOffsetForExtend;
233
gboolean bWMIconsNeedUpdate;
238
/** Say if a Container is a Dock.
239
* @param pContainer the container.
240
* @return TRUE if the container is a Dock.
242
#define CAIRO_DOCK_IS_DOCK(pContainer) (pContainer != NULL && ((CairoContainer*)pContainer)->iType == CAIRO_DOCK_TYPE_DOCK)
244
/** Cast a Container into a Dock.
245
* @param pDock the container to consider as a dock.
248
#define CAIRO_DOCK(pDock) ((CairoDock *)pDock)
251
/** Create a new root dock.
252
* @param cDockName name of the dock, used to identify it quickly. If the name is already used, the corresponding dock is returned.
253
* @param cRendererName name of a renderer. If NULL, the default renderer will be applied.
254
* @return the newly allocated dock, to destroy with #cairo_dock_destroy_dock
256
CairoDock *cairo_dock_create_new_dock (const gchar *cDockName, const gchar *cRendererName);
259
* Desactive a dock : le rend inoperant, en detruisant tout ce qu'il contient, sauf sa liste d'icones.
260
* @param pDock the dock.
262
void cairo_dock_deactivate_one_dock (CairoDock *pDock);
264
/** Decrease the number of pointing icons, and destroy the dock if no more icons point on it. Also destroy all of its sub-docks, and free any allocated ressources. Do nothing for the main dock, use #cairo_dock_free_all_docks for it.
265
* @param pDock the dock to be destroyed.
266
* @param cDockName its name.
267
* @param ReceivingDock a dock that will get its icons, or NULL to also destroy its icons.
268
* @param cReceivingDockName the name of the dock that will get its icons, or NULL if none is provided.
270
void cairo_dock_destroy_dock (CairoDock *pDock, const gchar *cDockName, CairoDock *ReceivingDock, const gchar *cReceivingDockName);
272
/** Increase by 1 the number of pointing icons. If the dock was a root dock, it becomes a sub-dock.
273
* @param pDock a dock.
274
* @param pParentDock its parent dock, if it becomes a sub-dock, otherwise it can be NULL.
276
void cairo_dock_reference_dock (CairoDock *pDock, CairoDock *pParentDock);
278
/** Create a new dock of type "sub-dock", and load a given list of icons inside. The list then belongs to the dock, so it must not be freeed after that. The buffers of each icon are loaded, so they just need to have an image filename and a name.
279
* @param pIconList a list of icons that will be loaded and inserted into the new dock.
280
* @param cDockName desired name for the new dock.
281
* @param pParentDock the parent dock.
282
* @return the newly allocated dock.
284
CairoDock *cairo_dock_create_subdock_from_scratch (GList *pIconList, gchar *cDockName, CairoDock *pParentDock);
286
/** Load a set of .desktop files that define icons, and build the corresponding tree of docks.
287
* All the icons are created and placed inside their dock, which is created if necessary.
288
* In the end, each dock is computed and placed on the screen.
289
* @param pMainDock a dock, needed to have an initial cairo context (because icons are created before their container).
290
* @param cDirectory a folder containing some .desktop files.
292
void cairo_dock_build_docks_tree_with_desktop_files (CairoDock *pMainDock, gchar *cDirectory);
294
/** Destroy all docks and all icons contained inside, and free all allocated ressources. Applets and Taskbar are stopped beforehand.
296
void cairo_dock_free_all_docks (void);
299
/** Insert an icon into a dock.
300
* Do nothing if the icon already exists inside the dock.
301
* @param icon the icon to be inserted. It should have been filled beforehand.
302
* @param pDock the dock to insert inside.
303
* @param bUpdateSize TRUE to update the size of the dock after the insertion.
304
* @param bAnimated TRUE to arm the icon's animation for insertion.
305
* @param bInsertSeparator TRUE to insert an automatic separator if needed.
306
* @param pCompareFunc a sorting function to place the new icon amongst the others, or NULL to sort by group/order.
308
void cairo_dock_insert_icon_in_dock_full (Icon *icon, CairoDock *pDock, gboolean bUpdateSize, gboolean bAnimated, gboolean bInsertSeparator, GCompareFunc pCompareFunc);
310
/** Insert an icon into a dock, at the position given by its 'fOrder' field.
311
* Insert an automatic separator if needed. Do nothing if the icon already exists inside the dock.
312
* @param icon the icon to be inserted. It should have been filled beforehand.
313
* @param pDock the dock to insert inside.
314
* @param bUpdateSize TRUE to update the size of the dock after the insertion.
315
* @param bAnimated TRUE to arm the icon's animation for insertion.
317
#define cairo_dock_insert_icon_in_dock(icon, pDock, bUpdateSize, bAnimated) cairo_dock_insert_icon_in_dock_full (icon, pDock, bUpdateSize, bAnimated, myIcons.iSeparateIcons, NULL)
319
/** Detach an icon from its dock, removing the unnecessary separators. The icon is not destroyed, and can be directly re-inserted in another container; it keeps its sub-dock, but loose its dialogs. Do nothing if the icon doesn't exist inside the dock.
320
*@param icon the icon to detach.
321
*@param pDock the dock containing the icon.
322
*@param bCheckUnusedSeparator TRUE to check and remove unnecessary separators.
323
*@return TRUE if the icon has been detached.
325
gboolean cairo_dock_detach_icon_from_dock (Icon *icon, CairoDock *pDock, gboolean bCheckUnusedSeparator);
327
void cairo_dock_remove_icon_from_dock_full (CairoDock *pDock, Icon *icon, gboolean bCheckUnusedSeparator);
329
/** Completely remove an icon from the dock, that is to say detach the icon, and remove all links with Cairo-Dock : its .desktop is deleted, its module is deactivated, and its Xid is removed from the Taskbar (its class is handled too).
330
* Unnecessary separators are not tested.
331
* The icon is not yet destroyed, but looses its sub-dock in case of a container launcher.
332
*@param pDock the dock containing the icon, or NULL if the icon is already detached.
333
*@param icon the icon to be removed.
335
#define cairo_dock_remove_one_icon_from_dock(pDock, icon) cairo_dock_remove_icon_from_dock_full (pDock, icon, FALSE)
337
/** Completely remove an icon from the dock, that is to say detach the icon, and remove all links with Cairo-Dock : its .desktop is deleted, its module is deactivated, and its Xid is removed from the Taskbar (its class is handled too).
338
* Unnecessary separators are removed as well.
339
* The icon is not yet destroyed, but looses its sub-dock in case of a container launcher.
340
*@param pDock the dock containing the icon, or NULL if the icon is already detached.
341
*@param icon the icon to be removed.
343
#define cairo_dock_remove_icon_from_dock(pDock, icon) cairo_dock_remove_icon_from_dock_full (pDock, icon, TRUE)
345
/** Remove and destroy all automatic separators inside a dock.
346
*@param pDock the dock.
348
void cairo_dock_remove_automatic_separators (CairoDock *pDock);
350
/** Add automatic separators between the different types of icons inside a dock.
351
*@param pDock the dock.
353
void cairo_dock_insert_separators_in_dock (CairoDock *pDock);
355
/** Add a launcher from a common desktop file : create and add the corresponding .desktop file with the others, load the corresponding icon, and insert it inside a dock with an animtion.
356
*@param cExternDesktopFileURI path to a desktop file.
357
*@param pReceivingDock the dock that will hold the new launcher.
358
*@param fOrder the order of the icon inside the dock.
360
void cairo_dock_add_new_launcher_by_uri (const gchar *cExternDesktopFileURI, CairoDock *pReceivingDock, double fOrder);
added
removed
src/cairo-dock-dock-factory.h
