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-desktop-file-factory.h"
28
#include "cairo-dock-load.h"
29
#include "cairo-dock-icons.h"
30
#include "cairo-dock-container.h"
34
*@file cairo-dock-dock-factory.h This class defines the Docks, and gives the way to create, destroy, and fill them.
36
* A dock is a container that holds a set of icons and a renderer (also known as view).
38
* It has the ability to be placed anywhere on the screen edges and to resize itself automatically to fit the screen's size.
40
* It supports internal dragging of its icons with the mouse, and dragging of itself with alt+mouse.
42
* 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.
47
CAIRO_DOCK_BOTTOM = 0,
51
CAIRO_DOCK_INSIDE_SCREEN,
52
CAIRO_DOCK_NB_POSITIONS
53
} CairoDockPositionType;
55
#define CAIRO_DOCK_UPDATE_DOCK_SIZE TRUE
56
#define CAIRO_DOCK_ANIMATE_ICON TRUE
57
#define CAIRO_DOCK_INSERT_SEPARATOR TRUE
59
typedef void (*CairoDockComputeSizeFunc) (CairoDock *pDock);
60
typedef Icon * (*CairoDockCalculateIconsFunc) (CairoDock *pDock);
61
typedef void (*CairoDockRenderFunc) (cairo_t *pCairoContext, CairoDock *pDock);
62
typedef void (*CairoDockRenderOptimizedFunc) (cairo_t *pCairoContext, CairoDock *pDock, GdkRectangle *pArea);
63
typedef void (*CairoDockSetSubDockPositionFunc) (Icon *pPointedIcon, CairoDock *pParentDock);
64
typedef void (*CairoDockGLRenderFunc) (CairoDock *pDock);
65
typedef void (*CairoDockRenderFreeDataFunc) (CairoDock *pDock);
67
/// Dock's renderer, also known as 'view'.
68
struct _CairoDockRenderer {
69
/// function that computes the sizes of a dock.
70
CairoDockComputeSizeFunc compute_size;
71
/// function that computes all the icons' parameters.
72
CairoDockCalculateIconsFunc calculate_icons;
73
/// rendering function (cairo)
74
CairoDockRenderFunc render;
75
/// optimized rendering function (cairo) that only redraw a part of the dock.
76
CairoDockRenderOptimizedFunc render_optimized;
77
/// rendering function (OpenGL, optionnal).
78
CairoDockGLRenderFunc render_opengl;
79
/// function that computes the position of the dock when it's a sub-dock.
80
CairoDockSetSubDockPositionFunc set_subdock_position;
81
/// TRUE if the view uses the OpenGL stencil buffer.
83
/// TRUE is the view uses reflects.
85
/// name displayed in the GUI (translated).
86
const gchar *cDisplayedName;
87
/// path to a readme file that gives a short description of the view.
88
gchar *cReadmeFilePath;
89
/// path to a preview image.
90
gchar *cPreviewFilePath;
91
/// function called when the renderer is unset from the dock.
92
CairoDockRenderFreeDataFunc free_data;
96
CAIRO_DOCK_MOUSE_INSIDE,
97
CAIRO_DOCK_MOUSE_ON_THE_EDGE,
98
CAIRO_DOCK_MOUSE_OUTSIDE
99
} CairoDockMousePositionType;
102
CAIRO_DOCK_INPUT_ACTIVE,
103
CAIRO_DOCK_INPUT_AT_REST,
104
CAIRO_DOCK_INPUT_HIDDEN
105
} CairoDockInputState;
108
CAIRO_DOCK_VISI_KEEP_ABOVE=0,
109
CAIRO_DOCK_VISI_RESERVE,
110
CAIRO_DOCK_VISI_KEEP_BELOW,
111
CAIRO_DOCK_VISI_AUTO_HIDE_ON_OVERLAP,
112
CAIRO_DOCK_VISI_AUTO_HIDE_ON_OVERLAP_ANY,
113
CAIRO_DOCK_VISI_AUTO_HIDE,
114
CAIRO_DOCK_VISI_SHORTKEY,
116
} CairoDockVisibility;
118
/// Definition of a Dock, which derives from a Container.
121
CairoContainer container;
122
/// the list of icons.
124
/// Set to TRUE for the main dock (the first to be created, and the one containing the taskbar).
125
gboolean bIsMainDock;
126
/// number of icons pointing on the dock (0 means it is a root dock, >0 a sub-dock).
129
//\_______________ Config parameters.
130
gint iGapX; // ecart de la fenetre par rapport au bord de l'ecran.
131
gint iGapY; // decalage de la fenetre par rapport au point d'alignement sur le bord de l'ecran.
132
gdouble fAlign; // alignment, between 0 and 1, on the screen's edge.
134
CairoDockVisibility iVisibility;
135
/// Horizontal offset of the screen where the dock lives, according to Xinerama.
137
/// Vertical offset of the screen where the dock lives, according to Xinerama.
139
/// number of the screen the dock is placed on (Xinerama).
142
/// maximum height of the icons.
143
gdouble iMaxIconHeight;
144
/// width of the dock, only taking into account an alignment of the icons.
145
gdouble fFlatDockWidth;
149
gint iMinRightMargin;
151
gint iMaxRightMargin;
155
//\_______________ current state of the dock.
156
gboolean bAutoHide; // auto-hide activated.
157
gint iScrollOffset; // pour faire defiler les icones avec la molette.
158
gint iMagnitudeIndex; // indice de calcul du coef multiplicateur de l'amplitude de la sinusoide (entre 0 et CAIRO_DOCK_NB_MAX_ITERATIONS).
159
/// (un)folding factor, between 0(unfolded) to 1(folded). It's up to the renderer on how to make use of it.
160
gdouble fFoldingFactor;
161
gint iAvoidingMouseIconType;// type d'icone devant eviter la souris, -1 si aucun.
162
gdouble fAvoidingMouseMargin;// marge d'evitement de la souris, en fraction de la largeur d'an icon (entre 0 et 0.5)
163
GList *pFirstDrawnElement;// pointeur sur le 1er element de la liste des icones a etre dessine, en partant de la gauche.
164
gdouble fDecorationsOffsetX;// decalage des decorations pour les faire suivre la souris.
165
// counter for the fade out effect.
167
// direction of the fade out effect.
169
/// counter for auto-hide.
171
/// counter for the post-hiding animation for icons always visible.
172
gdouble fPostHideOffset;
175
/// Whether the dock is in a popped up state or not.
177
/// whether the menu is visible (to keep the dock on high position).
178
gboolean bMenuVisible;
179
/// whether the user is dragging something over the dock.
180
gboolean bIsDragging;
181
/// Backup of the auto-hide state before quick-hide.
182
gboolean bTemporaryHidden;
183
/// whether mouse can't enter into the dock.
184
gboolean bEntranceDisabled;
185
/// whether the dock is shrinking down.
186
gboolean bIsShrinkingDown;
187
/// whether the dock is growing up.
188
gboolean bIsGrowingUp;
189
/// whether the dock is hiding.
191
/// whether the dock is showing.
193
/// whether an icon is being dragged away from the dock
194
gboolean bIconIsFlyingAway;
196
//\_______________ Source ID of events running on the dock.
197
/// Source ID for window resizing.
198
guint iSidMoveResize;
199
/// Source ID for window popping down to the bottom layer.
200
guint iSidUnhideDelayed;
201
/// Source ID of the timer that delays the "leave" event.
202
guint iSidLeaveDemand;
203
/// Source ID for pending update of WM icons geometry.
204
guint iSidUpdateWMIcons;
205
/// Source ID for hiding back the dock.
208
//\_______________ Renderer and fields set by it.
209
// nom de la vue, utile pour (re)charger les fonctions de rendu posterieurement a la creation du dock.
210
gchar *cRendererName;
211
/// current renderer, never NULL.
212
CairoDockRenderer *pRenderer;
213
/// data that can be used by the renderer.
214
gpointer pRendererData;
215
/// Set to TRUE by the renderer if one can drop between 2 icons.
217
/// set by the view to say if the mouse is currently on icons, on the egde, or outside of icons.
218
CairoDockMousePositionType iMousePositionType;
219
/// width of the dock at rest.
221
/// height of the dock at rest.
223
/// maximum width of the dock.
225
/// maximum height of the dock.
227
/// width of background decorations, set by the renderer.
228
gint iDecorationsWidth;
229
/// height of background decorations, set by the renderer.
230
gint iDecorationsHeight;
231
/// maximal magnitude of the zoom, between 0 and 1.
232
gdouble fMagnitudeMax;
234
//\_______________ input shape.
235
/// state of the input shape (active, at rest, hidden).
236
CairoDockInputState iInputState;
237
/// input shape of the window when the dock is at rest.
238
GdkBitmap* pShapeBitmap;
239
/// input shape of the window when the dock is hidden.
240
GdkBitmap* pHiddenShapeBitmap;
242
gint iOffsetForExtend;
243
gboolean bWMIconsNeedUpdate;
244
GLuint iRedirectedTexture;
247
//\_______________ background.
248
/// whether the dock should use the global background parameters.
250
/// path to an image, or NULL
252
/// whether to repeat the image as a pattern, or to stretch it to fill the dock.
253
gboolean bBgImageRepeat;
254
/// first color of the gradation
255
gdouble fBgColorBright[4];
256
/// second color of the gradation
257
gdouble fBgColorDark[4];
258
/// Background image buffer of the dock.
259
CairoDockImageBuffer backgroundBuffer;
260
/// Source ID for loading the background.
263
gboolean bPreventDraggingIcons; // whether icons in the dock can be dragged with the mouse (inside and outside of the dock).
269
/** Say if a Container is a Dock.
270
* @param pContainer the container.
271
* @return TRUE if the container is a Dock.
273
#define CAIRO_DOCK_IS_DOCK(pContainer) (pContainer != NULL && ((CairoContainer*)pContainer)->iType == CAIRO_DOCK_TYPE_DOCK)
275
/** Cast a Container into a Dock.
276
* @param pDock the container to consider as a dock.
279
#define CAIRO_DOCK(pDock) ((CairoDock *)pDock)
282
CairoDock *cairo_dock_new_dock (const gchar *cRendererName);
284
void cairo_dock_free_dock (CairoDock *pDock);
286
void cairo_dock_make_sub_dock (CairoDock *pDock, CairoDock *pParentDock);
288
/** Insert an icon into a dock.
289
* Do nothing if the icon already exists inside the dock.
290
* @param icon the icon to be inserted. It should have been filled beforehand.
291
* @param pDock the dock to insert inside.
292
* @param bUpdateSize TRUE to update the size of the dock after the insertion.
293
* @param bAnimated TRUE to arm the icon's animation for insertion.
294
* @param bInsertSeparator TRUE to insert an automatic separator if needed.
295
* @param pCompareFunc a sorting function to place the new icon amongst the others, or NULL to sort by group/order.
297
void cairo_dock_insert_icon_in_dock_full (Icon *icon, CairoDock *pDock, gboolean bUpdateSize, gboolean bAnimated, gboolean bInsertSeparator, GCompareFunc pCompareFunc);
299
/** Insert an icon into a dock, at the position given by its 'fOrder' field.
300
* Insert an automatic separator if needed. 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.
306
#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)
308
/** 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 looses its dialogs. Do nothing if the icon doesn't exist inside the dock.
309
*@param icon the icon to detach.
310
*@param pDock the dock containing the icon.
311
*@param bCheckUnusedSeparator TRUE to check and remove unnecessary separators.
312
*@return TRUE if the icon has been detached.
314
gboolean cairo_dock_detach_icon_from_dock (Icon *icon, CairoDock *pDock, gboolean bCheckUnusedSeparator);
316
void cairo_dock_remove_icon_from_dock_full (CairoDock *pDock, Icon *icon, gboolean bCheckUnusedSeparator);
318
/** 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).
319
* Unnecessary separators are not tested.
320
* The icon is not yet destroyed, but looses its sub-dock in case of a container launcher.
321
*@param pDock the dock containing the icon, or NULL if the icon is already detached.
322
*@param icon the icon to be removed.
324
#define cairo_dock_remove_one_icon_from_dock(pDock, icon) cairo_dock_remove_icon_from_dock_full (pDock, icon, FALSE)
326
/** 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).
327
* Unnecessary separators are removed as well.
328
* The icon is not yet destroyed, but looses its sub-dock in case of a container launcher.
329
*@param pDock the dock containing the icon, or NULL if the icon is already detached.
330
*@param icon the icon to be removed.
332
#define cairo_dock_remove_icon_from_dock(pDock, icon) cairo_dock_remove_icon_from_dock_full (pDock, icon, TRUE)
334
/** Remove and destroy all automatic separators inside a dock.
335
*@param pDock the dock.
337
void cairo_dock_remove_automatic_separators (CairoDock *pDock);
339
/** Add automatic separators between the different types of icons inside a dock.
340
*@param pDock the dock.
342
void cairo_dock_insert_separators_in_dock (CairoDock *pDock);
344
Icon *cairo_dock_add_new_launcher_by_uri_or_type (const gchar *cExternDesktopFileURI, CairoDockDesktopFileType iType, CairoDock *pReceivingDock, double fOrder, CairoDockIconType iGroup);
346
/** 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.
347
*@param cExternDesktopFileURI path to a desktop file.
348
*@param pReceivingDock the dock that will hold the new launcher.
349
*@param fOrder the order of the icon inside the dock.
350
*@return the newly created Icon corresponding to the file, or NULL if an error occured.
352
#define cairo_dock_add_new_launcher_by_uri(cExternDesktopFileURI, pReceivingDock, fOrder) cairo_dock_add_new_launcher_by_uri_or_type (cExternDesktopFileURI, 0, pReceivingDock, fOrder, CAIRO_DOCK_LAUNCHER)
354
/** Add an empty default launcher of a given type : create and add the corresponding .desktop file with the others, load the corresponding icon, and insert it inside a dock with an animtion. The launcher is then suitable for being edited by the user to add real properties.
355
*@param iType type of the launcher.
356
*@param pReceivingDock the dock that will hold the new launcher.
357
*@param fOrder the order of the icon inside the dock.
358
*@return the newly created Icon corresponding to the type, or NULL if an error occured.
360
#define cairo_dock_add_new_launcher_by_type(iType, pReceivingDock, fOrder, iGroup) cairo_dock_add_new_launcher_by_uri_or_type (NULL, iType, pReceivingDock, fOrder, iGroup)
362
/** Remove all icons from a dock (and its sub-docks). If the receiving dock is NULL, the icons are destroyed and removed from the current theme itself.
363
*@param pDock a dock.
364
*@param pReceivingDock the dock that will receive the icons, or NULL to destroy and remove the icons.
365
*@param cReceivingDockName name of the receiving dock.
367
void cairo_dock_remove_icons_from_dock (CairoDock *pDock, CairoDock *pReceivingDock, const gchar *cReceivingDockName);
370
void cairo_dock_create_redirect_texture_for_dock (CairoDock *pDock);