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_SURFACE_FACTORY__
22
#define __CAIRO_DOCK_SURFACE_FACTORY__
28
#include <cairo-dock-struct.h>
32
*@file cairo-dock-surface-factory.h This class contains functions to load any image/X buffer/GdkPixbuf/text into a cairo-surface.
33
* The loading of an image can be modified by a mask, to take into account the ratio, zoom, orientation, etc.
35
* The general way to load an image is by using \ref cairo_dock_create_surface_from_image.
37
* If you just want to load an image at a given size, use \ref cairo_dock_create_surface_from_image_simple, or \ref cairo_dock_create_surface_from_icon.
39
* To load a text into a surface, describe your text look with a _CairoDockLabelDescription, and pass it to \ref cairo_dock_create_surface_from_text.
43
/// Types of image loading modifiers.
45
/// fill the space, with transparency if necessary.
46
CAIRO_DOCK_FILL_SPACE = 1<<0,
47
/// keep the ratio of the original image.
48
CAIRO_DOCK_KEEP_RATIO = 1<<1,
49
/// don't zoom in the image if the final surface is larger than the original image.
50
CAIRO_DOCK_DONT_ZOOM_IN = 1<<2,
51
/// orientation horizontal flip
52
CAIRO_DOCK_ORIENTATION_HFLIP = 1<<3,
53
/// orientation 180° rotation
54
CAIRO_DOCK_ORIENTATION_ROT_180 = 2<<3,
55
/// orientation vertical flip
56
CAIRO_DOCK_ORIENTATION_VFLIP = 3<<3,
57
/// orientation 90° rotation + horizontal flip
58
CAIRO_DOCK_ORIENTATION_ROT_90_HFLIP = 4<<3,
59
/// orientation 90° rotation
60
CAIRO_DOCK_ORIENTATION_ROT_90 = 5<<3,
61
/// orientation 90° rotation + vertical flip
62
CAIRO_DOCK_ORIENTATION_ROT_90_VFLIP = 6<<3,
63
/// orientation 270° rotation
64
CAIRO_DOCK_ORIENTATION_ROT_270 = 7<<3
65
} CairoDockLoadImageModifier;
66
/// mask to get the orientation from a CairoDockLoadImageModifier.
67
#define CAIRO_DOCK_ORIENTATION_MASK (7<<3)
69
/// Description of the rendering of a text.
70
struct _CairoDockLabelDescription {
71
/// font size (also approximately the resulting size in pixels)
75
/// text weight. The higher, the thicker the strokes are.
77
/// text style (italic or normal).
79
/// first color of the characters.
80
gdouble fColorStart[3];
81
/// second color of the characters. If different from the first one, it will make a gradation.
82
gdouble fColorStop[3];
83
/// TRUE if the gradation is vertical (from top to bottom).
84
gboolean bVerticalPattern;
85
/// frame background color. Set the alpha channel to 0 to not draw a frame in the background.
86
gdouble fBackgroundColor[4];
87
/// TRUE to stroke the outline of the characters (in black).
89
/// margin around the text, it is also the dimension of the frame if available.
94
/* Calcule la taille d'une image selon une contrainte en largeur et hauteur de manière à remplir l'espace donné.
95
*@param fImageWidth the width of the image. Contient initialement the width of the image, et sera écrasée avec la largeur obtenue.
96
*@param fImageHeight the height of the image. Contient initialement the height of the image, et sera écrasée avec la hauteur obtenue.
97
*@param iWidthConstraint contrainte en largeur (0 <=> pas de contrainte).
98
*@param iHeightConstraint contrainte en hauteur (0 <=> pas de contrainte).
99
*@param bNoZoomUp TRUE ssi on ne doit pas agrandir the image (seulement la rétrécir).
100
*@param fZoomWidth sera renseigné avec le facteur de zoom en largeur qui a été appliqué.
101
*@param fZoomHeight sera renseigné avec le facteur de zoom en hauteur qui a été appliqué.
103
void cairo_dock_calculate_size_fill (double *fImageWidth, double *fImageHeight, int iWidthConstraint, int iHeightConstraint, gboolean bNoZoomUp, double *fZoomWidth, double *fZoomHeight);
105
/* Calcule la taille d'une image selon une contrainte en largeur et hauteur en gardant le ratio hauteur/largeur constant.
106
*@param fImageWidth the width of the image. Contient initialement the width of the image, et sera écrasée avec la largeur obtenue.
107
*@param fImageHeight the height of the image. Contient initialement the height of the image, et sera écrasée avec la hauteur obtenue.
108
*@param iWidthConstraint contrainte en largeur (0 <=> pas de contrainte).
109
*@param iHeightConstraint contrainte en hauteur (0 <=> pas de contrainte).
110
*@param bNoZoomUp TRUE ssi on ne doit pas agrandir the image (seulement la rétrécir).
111
*@param fZoom sera renseigné avec le facteur de zoom qui a été appliqué.
113
void cairo_dock_calculate_size_constant_ratio (double *fImageWidth, double *fImageHeight, int iWidthConstraint, int iHeightConstraint, gboolean bNoZoomUp, double *fZoom);
115
/** Calculate the size of an image according to a constraint on width and height, and a loading modifier.
116
*@param fImageWidth pointer to the width of the image. Initially contains the width of the original image, and is updated with the resulting width.
117
*@param fImageHeight pointer to the height of the image. Initially contains the height of the original image, and is updated with the resulting height.
118
*@param iWidthConstraint constraint on width (0 <=> no constraint).
119
*@param iHeightConstraint constraint on height (0 <=> no constraint).
120
*@param iLoadingModifier a mask of different loading modifiers.
121
*@param fZoomWidth will be filled with the zoom that has been applied on width.
122
*@param fZoomHeight will be filled with the zoom that has been applied on height.
124
void cairo_dock_calculate_constrainted_size (double *fImageWidth, double *fImageHeight, int iWidthConstraint, int iHeightConstraint, CairoDockLoadImageModifier iLoadingModifier, double *fZoomWidth, double *fZoomHeight);
126
/** Create a surface from raw data of an X icon. The biggest icon possible is taken. The ratio is kept, and the surface will fill the space with transparency if necessary.
127
*@param pXIconBuffer raw data of the icon.
128
*@param iBufferNbElements number of elements in the buffer.
129
*@param pSourceContext a drawing context (not altered by the function).
130
*@param fConstraintWidth desired width of the icon.
131
*@param fConstraintHeight desired height of the icon.
132
*@param fMaxScale maximum zoom of the icon.
133
*@param fWidth will be filled with the resulting width of the surface.
134
*@param fHeight will be filled with the resulting height of the surface.
135
*@return the newly allocated surface.
137
cairo_surface_t *cairo_dock_create_surface_from_xicon_buffer (gulong *pXIconBuffer, int iBufferNbElements, cairo_t *pSourceContext, double fConstraintWidth, double fConstraintHeight, double fMaxScale, double *fWidth, double *fHeight);
139
/** Create a surface from a GdkPixbuf.
140
*@param pixbuf the pixbuf.
141
*@param pSourceContext a drawing context (not altered by the function).
142
*@param fMaxScale maximum zoom of the icon.
143
*@param iWidthConstraint constraint on the width, or 0 to not constraint it.
144
*@param iHeightConstraint constraint on the height, or 0 to not constraint it.
145
*@param iLoadingModifier a mask of different loading modifiers.
146
*@param fImageWidth will be filled with the resulting width of the surface (hors zoom).
147
*@param fImageHeight will be filled with the resulting height of the surface (hors zoom).
148
*@param fZoomX if non NULL, will be filled with the zoom that has been applied on width.
149
*@param fZoomY if non NULL, will be filled with the zoom that has been applied on width.
150
*@return the newly allocated surface.
152
cairo_surface_t *cairo_dock_create_surface_from_pixbuf (GdkPixbuf *pixbuf, cairo_t *pSourceContext, double fMaxScale, int iWidthConstraint, int iHeightConstraint, CairoDockLoadImageModifier iLoadingModifier, double *fImageWidth, double *fImageHeight, double *fZoomX, double *fZoomY);
155
/** Create an empty surface (transparent) of a given size. In OpenGL mode, this surface can act as a buffer to generate a texture.
156
*@param pSourceContext un contexte cairo, ou NULL pour creer une surface tampon.
157
*@param iWidth width of the surface.
158
*@param iHeight height of the surface.
159
*@return the newly allocated surface.
161
cairo_surface_t *_cairo_dock_create_blank_surface (cairo_t *pSourceContext, int iWidth, int iHeight);
163
/** Create a surface from any image.
164
*@param cImagePath complete path to the image.
165
*@param pSourceContext a drawing context (not altered by the function).
166
*@param fMaxScale maximum zoom of the icon.
167
*@param iWidthConstraint constraint on the width, or 0 to not constraint it.
168
*@param iHeightConstraint constraint on the height, or 0 to not constraint it.
169
*@param iLoadingModifier a mask of different loading modifiers.
170
*@param fImageWidth will be filled with the resulting width of the surface (hors zoom).
171
*@param fImageHeight will be filled with the resulting height of the surface (hors zoom).
172
*@param fZoomX if non NULL, will be filled with the zoom that has been applied on width.
173
*@param fZoomY if non NULL, will be filled with the zoom that has been applied on width.
174
*@return the newly allocated surface.
176
cairo_surface_t *cairo_dock_create_surface_from_image (const gchar *cImagePath, cairo_t* pSourceContext, double fMaxScale, int iWidthConstraint, int iHeightConstraint, CairoDockLoadImageModifier iLoadingModifier, double *fImageWidth, double *fImageHeight, double *fZoomX, double *fZoomY);
178
/** Create a surface from any image, at a given size. If the image is given by its sole name, it is searched inside the current theme root folder.
179
*@param cImageFile path or name of an image.
180
*@param pSourceContext a drawing context (not altered by the function).
181
*@param fImageWidth the desired surface width.
182
*@param fImageHeight the desired surface height.
183
*@return the newly allocated surface.
185
cairo_surface_t *cairo_dock_create_surface_from_image_simple (const gchar *cImageFile, cairo_t* pSourceContext, double fImageWidth, double fImageHeight);
187
/** Create a surface from any image, at a given size. If the image is given by its sole name, it is searched inside the icons themes known by Cairo-Dock.
188
*@param cImagePath path or name of an image.
189
*@param pSourceContext a drawing context (not altered by the function).
190
*@param fImageWidth the desired surface width.
191
*@param fImageHeight the desired surface height.
192
*@return the newly allocated surface.
194
cairo_surface_t *cairo_dock_create_surface_from_icon (const gchar *cImagePath, cairo_t* pSourceContext, double fImageWidth, double fImageHeight);
195
#define cairo_dock_create_surface_for_icon cairo_dock_create_surface_from_icon
197
/** Create a square surface from any image, at a given size. If the image is given by its sole name, it is searched inside the icons themes known by Cairo-Dock.
198
*@param cImagePath path or name of an image.
199
*@param pSourceContext a drawing context (not altered by the function).
200
*@param fImageSize the desired surface size.
201
*@return the newly allocated surface.
203
#define cairo_dock_create_surface_for_square_icon(cImagePath, pSourceContext, fImageSize) cairo_dock_create_surface_for_icon (cImagePath, pSourceContext, fImageSize, fImageSize)
206
/** Create a surface at a given size, and fill it with a pattern. If the pattern image is given by its sole name, it is searched inside the current theme root folder.
207
*@param cImagePath path or name of an image that will be repeated to fill the surface.
208
*@param pSourceContext a drawing context (not altered by the function).
209
*@param fImageWidth the desired surface width.
210
*@param fImageHeight the desired surface height.
211
*@param fAlpha transparency of the pattern (1 means opaque).
212
*@return the newly allocated surface.
214
cairo_surface_t *cairo_dock_create_surface_from_pattern (const gchar *cImageFile, cairo_t *pSourceContext, double fImageWidth, double fImageHeight, double fAlpha);
217
/** Create a surface by rotating another. Only works for 1/4 of rounds.
218
*@param pSurface surface to rotate.
219
*@param pSourceContext a drawing context (not altered by the function).
220
*@param fImageWidth the width of the surface.
221
*@param fImageHeight the height of the surface.
222
*@param fRotationAngle rotation angle to apply, in radians.
223
*@return the newly allocated surface.
225
cairo_surface_t * cairo_dock_rotate_surface (cairo_surface_t *pSurface, cairo_t *pSourceContext, double fImageWidth, double fImageHeight, double fRotationAngle);
227
/** Create a surface by reflection of another. Apply a transparency gradation. The size of the reflect is given by the global config,and its position if given by the orientation of the icon; if this changes, the reflect needs to be re-created.
228
*@param pSurface surface to reflect.
229
*@param pSourceContext a drawing context (not altered by the function).
230
*@param fImageWidth the width of the surface.
231
*@param fImageHeight the height of the surface.
232
*@param fReflectSize size of the reflection.
233
*@param bIsHorizontal TRUE if the surface is in an horizontal container.
234
*@param bDirectionUp TRUE if the surface is in a container whose direction is towards.
235
*@return the newly allocated surface.
237
cairo_surface_t * cairo_dock_create_reflection_surface (cairo_surface_t *pSurface, cairo_t *pSourceContext, double fImageWidth, double fImageHeight, double fReflectSize, double fAlbedo, gboolean bIsHorizontal, gboolean bDirectionUp);
239
/** Create a surface representing a text, according to a given text description.
240
*@param cText the text.
241
*@param pSourceContext a drawing context (not altered by the function).
242
*@param pLabelDescription description of the text rendering.
243
*@param fMaxScale maximum zoom of the text.
244
*@param iMaxWidth maximum authorized width for the surface; it will be zoomed in to fits this limit. 0 for no limit.
245
*@param iTextWidth will be filled the width of the resulting surface.
246
*@param iTextHeight will be filled the height of the resulting surface.
247
*@param fTextXOffset if non NULL, will be filled the horizontal offset to apply to center the text horizontally.
248
*@param fTextYOffset if non NULL, will be filled the vertical offset to apply to center the text vertically.
249
*@return the newly allocated surface.
251
cairo_surface_t *cairo_dock_create_surface_from_text_full (const gchar *cText, cairo_t *pSourceContext, CairoDockLabelDescription *pLabelDescription, double fMaxScale, int iMaxWidth, int *iTextWidth, int *iTextHeight, double *fTextXOffset, double *fTextYOffset);
253
/** Create a surface representing a text, according to a given text description.
254
*@param cText the text.
255
*@param pSourceContext a drawing context (not altered by the function).
256
*@param pLabelDescription description of the text rendering.
257
*@param iTextWidthPtr will be filled the width of the resulting surface.
258
*@param iTextHeightPtr will be filled the height of the resulting surface.
259
*@return the newly allocated surface.
261
#define cairo_dock_create_surface_from_text(cText, pSourceContext, pLabelDescription, iTextWidthPtr, iTextHeightPtr) cairo_dock_create_surface_from_text_full (cText, pSourceContext, pLabelDescription, 1., 0, iTextWidthPtr, iTextHeightPtr, NULL, NULL)
263
/** Create a surface identical to another, possibly resizing it.
264
*@param pSurface surface to duplicate.
265
*@param pSourceContext a drawing context (not altered by the function).
266
*@param fWidth the width of the surface.
267
*@param fHeight the height of the surface.
268
*@param fDesiredWidth desired width of the copy (0 to keep the same size).
269
*@param fDesiredHeight desired height of the copy (0 to keep the same size).
270
*@return the newly allocated surface.
272
cairo_surface_t * cairo_dock_duplicate_surface (cairo_surface_t *pSurface, cairo_t *pSourceContext, double fWidth, double fHeight, double fDesiredWidth, double fDesiredHeight);