31
31
*@file cairo-dock-data-renderer.h This class defines the Data Renderer structure and API.
32
* A CairoDataRenderer is a generic way to render onto an icon a set of values defined by : {yk = f(tk)}, k=0..n where yk is a vector.
33
* Data Renderers are binded to an icon, and initialized with a set of attributes, that derives from a CairoDataRendererAttribute, with the function /ref cairo_dock_add_new_data_renderer_on_icon.
34
* You update a Data Renderer with /ref cairo_dock_render_new_data_on_icon, providing it the correct number of values.
32
* A CairoDataRenderer is a generic way to render onto an icon a set of N values defined by : {yk = f(t)}, k=0..N. For instance you could represent the (cpu, mem, swap) evolution over the time.
33
* You bind a Data Renderer with /ref cairo_dock_add_new_data_renderer_on_icon. You can specify some configuration parameters for the Data Renderer with a set of attributes, that derive from a CairoDataRendererAttribute.
34
* You feed the Data Renderer with /ref cairo_dock_render_new_data_on_icon, providing it the correct number of values.
35
35
* If you want to change any parameter of a Data Renderer, use /ref cairo_dock_reload_data_renderer_on_icon, which keeps the history.
36
36
* To remove the Data Renderer from an icon, use /ref cairo_dock_remove_data_renderer_on_icon.
52
52
#define CAIRO_DOCK_DATA_FORMAT_MAX_LEN 20
53
53
/// Prototype of a function used to format the values in a short readable format (to be displayed as quick-info).
54
typedef void (*CairoDockGetValueFormatFunc) (double fValue, int iNumValue, gchar *cFormatBuffer, int iBufferLength, gpointer data);
54
typedef void (*CairoDataRendererFormatValueFunc) (CairoDataRenderer *pRenderer, int iNumValue, gchar *cFormatBuffer, int iBufferLength, gpointer data);
55
55
/// Generic DataRenderer attributes structure. The attributes of any implementation of a DataRenderer will derive from this class.
56
56
struct _CairoDataRendererAttribute {
57
/// name of the model ("gauge", "graph", etc) [mandatory].
57
58
const gchar *cModelName;
59
/// number of values to represent (for instance 3 for (cpu, mem, swap)) [1 by default and minimum].
61
/// number of values to remember over time. For instance graphs can display as much values as the icon's width [2 by default and minimum].
63
/// an array of pairs of (min,max) values. [optionnal, input values will be considered between 0 and 1 if NULL].
60
64
gdouble *pMinMaxValues;
65
/// whether to automatically update the values' range [false by default].
61
66
gboolean bUpdateMinMax;
67
/// whether to write the values on the icon. [false by default].
62
68
gboolean bWriteValues;
69
/// time needed to update to the new values. The update is smooth in OpenGL mode. [0 by default]
64
CairoDockGetValueFormatFunc format_value;
71
/// a function used to format the values into a string. Only useful if you make te DataRenderer write the values [optionnal, by default the values are formatted with 2 decimals].
72
CairoDataRendererFormatValueFunc format_value;
73
/// data to be passed to the format function [optionnal].
65
74
gpointer pFormatData;
75
/// an optionnal list of emblems to draw on the overlay.
68
gdouble fTextColor[3];
77
/// an optionnal list of labels to write on the overlay.
71
81
typedef CairoDataRenderer * (*CairoDataRendererNewFunc) (void);
73
83
typedef void (*CairoDataRendererRenderFunc) (CairoDataRenderer *pDataRenderer, cairo_t *pCairoContext);
74
84
typedef void (*CairoDataRendererRenderOpenGLFunc) (CairoDataRenderer *pDataRenderer);
75
85
typedef void (*CairoDataRendererReloadFunc) (CairoDataRenderer *pDataRenderer);
76
typedef void (*CairoDataRendererFreeFunc) (CairoDataRenderer *pDataRenderer);
86
typedef void (*CairoDataRendererUnloadFunc) (CairoDataRenderer *pDataRenderer);
77
87
/// Interface of a DataRenderer.
78
88
struct _CairoDataRendererInterface {
79
CairoDataRendererNewFunc new;
89
/// function that loads anything the DataRenderer will need. It also completes the DataRenderer structure (for instance the text zones).
80
90
CairoDataRendererLoadFunc load;
91
/// function that draws the values with cairo.
81
92
CairoDataRendererRenderFunc render;
93
/// function that draws the values with opengl.
82
94
CairoDataRendererRenderOpenGLFunc render_opengl;
95
/// function that reloads the DataRenderer's buffers when the icon is resized.
83
96
CairoDataRendererReloadFunc reload;
84
CairoDataRendererFreeFunc free;
97
/// function that unload all the previously allocated buffers.
98
CairoDataRendererUnloadFunc unload;
102
struct _CairoDataRendererEmblemParam {
103
gdouble fX, fY; // [-1;1]
104
gdouble fWidth, fHeight; // [-1;1]
88
108
struct _CairoDataRendererEmblem {
90
gdouble fWidth, fHeight;
92
cairo_surface_t *pSurface;
96
struct _CairoDataRendererTextZone {
98
gdouble fWidth, fHeight;
109
CairoDataRendererEmblemParam param;
111
cairo_surface_t *pSurface;
115
struct _CairoDataRendererTextParam {
116
gdouble fX, fY; // [-1;1], center of the text.
117
gdouble fWidth, fHeight; // [-1;1]
121
struct _CairoDataRendererText {
122
CairoDataRendererTextParam param;
124
gint iTextWidth, iTextHeight;
125
cairo_surface_t *pSurface;
103
130
/// Generic DataRenderer. Any implementation of a DataRenderer will derive from this class.
104
131
struct _CairoDataRenderer {
105
// fill at init by the high level renderer.
132
//\_________________ filled at init by the implementation.
106
133
/// interface of the Data Renderer.
107
134
CairoDataRendererInterface interface;
108
// fill at load time independantly of the renderer type.
135
//\_________________ filled at loading time independantly of the renderer type.
109
136
/// internal data to be drawn by the renderer.it
110
137
CairoDataToRenderer data;
111
138
/// size of the drawing area.
112
139
gint iWidth, iHeight; // taille du contexte de dessin.
113
140
/// specific function to format the values as text.
114
CairoDockGetValueFormatFunc format_value;
141
CairoDataRendererFormatValueFunc format_value;
115
142
/// buffer for the text.
116
143
gchar cFormatBuffer[CAIRO_DOCK_DATA_FORMAT_MAX_LEN+1];
117
144
/// data passed to the format fonction.
122
149
gboolean bWriteValues;
123
150
/// the time it will take to update to the new value, with a smooth animation (require openGL capacity)
124
151
gint iLatencyTime;
125
// fill at load time by the high level renderer.
152
//\_________________ filled at load time by the implementation.
126
153
/// the rank of the renderer, eg the number of values it can display at once (for exemple, 1 for a bar, 2 for a dual-gauge)
127
154
gint iRank; // nbre de valeurs que peut afficher 1 unite (en general : gauge:1/2, graph:1/2, bar:1)
128
155
/// set to TRUE <=> the renderer can draw the values as text itself.
129
156
gboolean bCanRenderValueAsText;
157
/// set to TRUE <=> the drawing will be rotated if the container is vertical.
158
gboolean bRotateWithContainer;
159
/// an optionnal list of labels to be displayed on the Data Renderer to indicate the nature of each value. Same size as the set of values.
160
CairoDataRendererText *pLabels;
161
/// an optionnal list of emblems to be displayed on the Data Renderer to indicate the nature of each value. Same size as the set of values.
162
CairoDataRendererEmblem *pEmblems;
163
/// an optionnal list of text zones to write the values. Same size as the set of values.
164
CairoDataRendererTextParam *pValuesText;
165
//\_________________ dynamic.
131
166
/// the animation counter for the smooth movement.
132
167
gint iSmoothAnimationStep;
133
168
/// latency due to the smooth movement (0 means the displayed value is the current one, 1 the previous)
134
169
gdouble fLatency;
135
/// an optionnal list of tiltes to be displayed on the Data Renderer next to each value. Same size as the set of values.
137
/// color of the titles.
138
gdouble fTextColor[3];
139
/// an optionnal list of emblems to be displayed on the Data Renderer next to each value. Same size as the set of values.
141
/// an optionnal list of emblems to be displayed on the Data Renderer to indicate the nature of each value. Same size as the set of values.
142
CairoDataRendererEmblem *pEmblems;
143
/// an optionnal list of titles to be displayed on the Data Renderer to indicate the nature of each value. Same size as the set of values.
144
CairoDataRendererTextZone *pTextZones;
191
216
void cairo_dock_refresh_data_renderer (Icon *pIcon, CairoContainer *pContainer, cairo_t *pCairoContext);
219
void cairo_dock_render_overlays_to_context (CairoDataRenderer *pRenderer, int iNumValue, cairo_t *pCairoContext);
221
void cairo_dock_render_overlays_to_texture (CairoDataRenderer *pRenderer, int iNumValue);
195
225
/// Structure Access
228
#define cairo_dock_get_icon_data_renderer(pIcon) (pIcon)->pDataRenderer
197
230
/**Get the elementary part of a Data Renderer
198
231
*@param r a high level data renderer
199
232
*@return a CairoDataRenderer* */
206
239
*@param pAttr a high level data renderer attribute
207
240
*@return a CairoDataRendererAttribute* */
208
241
#define CAIRO_DATA_RENDERER_ATTRIBUTE(pAttr) ((CairoDataRendererAttribute *) pAttr)
242
/**Get the number of values a DataRenderer displays. It's also the size of any of its arrays.
243
*@param pRenderer a data renderer
244
*@return number of values a DataRenderer displays */
245
#define cairo_data_renderer_get_nb_values(pRenderer) ((pRenderer)->data.iNbValues)
247
#define cairo_data_renderer_get_history_size(pRenderer) ((pRenderer)->data.iMemorySize)
249
#define cairo_data_renderer_get_nth_label(pRenderer, i) (&(pRenderer)->pLabels[i])
250
#define cairo_data_renderer_get_nth_value_text(pRenderer, i) (&(pRenderer)->pValuesText[i])
251
#define cairo_data_renderer_get_nth_emblem(pRenderer, i) (&(pRenderer)->pEmblems[i])
211
254
/*#define cairo_data_renderer_set_attribute(pRendererAttribute, cAttributeName, ) g_datalist_get_data (pRendererAttribute->pExtraProperties)
270
313
*@param fValue the normalized value
271
314
*@param i the number of the value
272
315
*@param cBuffer a buffer where to write*/
273
#define cairo_data_renderer_format_value_full(pRenderer, fValue, i, cBuffer) do {\
316
#define cairo_data_renderer_format_value_full(pRenderer, i, cBuffer) do {\
274
317
if (pRenderer->format_value != NULL)\
275
(pRenderer)->format_value (fValue, i, cBuffer, CAIRO_DOCK_DATA_FORMAT_MAX_LEN, (pRenderer)->pFormatData);\
277
snprintf (cBuffer, CAIRO_DOCK_DATA_FORMAT_MAX_LEN, fValue < .0995 ? "%.1f" : (fValue < 1 ? " %.0f" : "%.0f"), fValue * 100.); } while (0)
318
(pRenderer)->format_value (pRenderer, i, cBuffer, CAIRO_DOCK_DATA_FORMAT_MAX_LEN, (pRenderer)->pFormatData);\
320
double x_ = cairo_data_renderer_get_normalized_current_value (pRenderer, i);\
321
snprintf (cBuffer, CAIRO_DOCK_DATA_FORMAT_MAX_LEN, x_ < .0995 ? "%.1f" : (x_ < 1 ? " %.0f" : "%.0f"), x_ * 100.); }\
278
323
/**Write a value in a readable text format in the renderer text buffer.
279
324
*@param pRenderer a data renderer
280
325
*@param fValue the normalized value
281
326
*@param i the number of the value*/
282
#define cairo_data_renderer_format_value(pRenderer, fValue, i) cairo_data_renderer_format_value_full (pRenderer, fValue, i, (pRenderer)->cFormatBuffer)
327
#define cairo_data_renderer_format_value(pRenderer, i) cairo_data_renderer_format_value_full (pRenderer, i, (pRenderer)->cFormatBuffer)
284
#define cairo_data_renderer_can_write_value(pRenderer) (pRenderer)->bCanRenderValueAsText
329
#define cairo_data_renderer_can_write_values(pRenderer) (pRenderer)->bCanRenderValueAsText
330
#define cairo_data_renderer_actually_writes_values(pRenderer) (pRenderer)->bCanRenderValueAsText
287
333
GHashTable *cairo_dock_list_available_themes_for_data_renderer (const gchar *cRendererName);
added
removed
src/gldit/cairo-dock-data-renderer.h
