documentation update and some cosmetic

This commit is contained in:
Julien Danjou 2008-02-27 09:32:45 +01:00
parent 3ccf163357
commit 46742a56e4
3 changed files with 88 additions and 23 deletions

View File

@ -280,6 +280,9 @@ cfg_opt_t awesome_opts[] =
CFG_END() CFG_END()
}; };
/** Return default configuration file path
* \return path to the default configuration file
*/
char * char *
config_file(void) config_file(void)
{ {
@ -297,6 +300,10 @@ config_file(void)
return confpath; return confpath;
} }
/** Check configuration file syntax in regard of libconfuse parsing
* \param path to config file
* \return status returned by cfg_parse()
*/
int int
config_check(const char *confpatharg) config_check(const char *confpatharg)
{ {

View File

@ -32,6 +32,10 @@
#include "draw.h" #include "draw.h"
#include "common/util.h" #include "common/util.h"
/** Convert text from any charset to UTF-8 using iconv
* \param iso the ISO string to convert
* \return NULL if error, otherwise pointer to the new converted string
*/
static char * static char *
draw_iso2utf8(char *iso) draw_iso2utf8(char *iso)
{ {
@ -74,9 +78,11 @@ draw_iso2utf8(char *iso)
} }
/** Get a draw context /** Get a draw context
* \param disp Display ref
* \param phys_screen physical screen id * \param phys_screen physical screen id
* \param width width * \param width width
* \param height height * \param height height
* \param dw Drawable object to store in DrawCtx
* \return draw context ref * \return draw context ref
*/ */
DrawCtx * DrawCtx *
@ -97,6 +103,9 @@ draw_context_new(Display *disp, int phys_screen, int width, int height, Drawable
return d; return d;
}; };
/** Delete a draw context
* \param ctx DrawCtx to delete
*/
void void
draw_context_delete(DrawCtx *ctx) draw_context_delete(DrawCtx *ctx)
{ {
@ -106,10 +115,8 @@ draw_context_delete(DrawCtx *ctx)
} }
/** Draw text into a draw context /** Draw text into a draw context
* \param x x coord * \param ctx DrawCtx to draw to
* \param y y coord * \param area area to draw to
* \param w width
* \param h height
* \param align alignment * \param align alignment
* \param padding padding to add before drawing the text * \param padding padding to add before drawing the text
* \param font font to use * \param font font to use
@ -204,11 +211,11 @@ draw_text(DrawCtx *ctx,
* \param pcolor_end color at 100% of width * \param pcolor_end color at 100% of width
* \return pat pattern or NULL; needs to get cairo_pattern_destroy()'ed; * \return pat pattern or NULL; needs to get cairo_pattern_destroy()'ed;
*/ */
cairo_pattern_t * static cairo_pattern_t *
setup_cairo_color_source(DrawCtx *ctx, int x, int y, int width, draw_setup_cairo_color_source(DrawCtx *ctx, int x, int y, int width,
XColor color, XColor *pcolor_center, XColor *pcolor_end) XColor color, XColor *pcolor_center, XColor *pcolor_end)
{ {
cairo_pattern_t *pat; cairo_pattern_t *pat = NULL;
if(pcolor_center || pcolor_end) /* draw a gradient */ if(pcolor_center || pcolor_end) /* draw a gradient */
{ {
@ -226,19 +233,17 @@ setup_cairo_color_source(DrawCtx *ctx, int x, int y, int width,
cairo_pattern_add_color_stop_rgb(pat, 1, color.red / 65535.0, cairo_pattern_add_color_stop_rgb(pat, 1, color.red / 65535.0,
color.green / 65535.0, color.blue / 65535.0); color.green / 65535.0, color.blue / 65535.0);
cairo_set_source(ctx->cr, pat); cairo_set_source(ctx->cr, pat);
return pat;
} }
else /* no gradient */ else
{
cairo_set_source_rgb(ctx->cr, color.red / 65535.0, color.green / 65535.0, color.blue / 65535.0); cairo_set_source_rgb(ctx->cr, color.red / 65535.0, color.green / 65535.0, color.blue / 65535.0);
return NULL;
} return pat;
} }
/** Draw rectangle /** Draw rectangle
* \param ctx Draw context * \param ctx Draw context
* \param geometry geometry * \param geometry geometry
* \param filled filled rectangle? * \param filled fill rectangle?
* \param color color to use * \param color color to use
*/ */
void void
@ -276,7 +281,7 @@ draw_rectangle_gradient(DrawCtx *ctx, Area geometry, int fullwidth, Bool filled,
cairo_set_antialias(ctx->cr, CAIRO_ANTIALIAS_NONE); cairo_set_antialias(ctx->cr, CAIRO_ANTIALIAS_NONE);
cairo_set_line_width(ctx->cr, 1.0); cairo_set_line_width(ctx->cr, 1.0);
pat = setup_cairo_color_source(ctx, geometry.x, geometry.y, fullwidth, pat = draw_setup_cairo_color_source(ctx, geometry.x, geometry.y, fullwidth,
color, pcolor_center, pcolor_end); color, pcolor_center, pcolor_end);
if(filled) if(filled)
@ -305,6 +310,7 @@ draw_graph_setup(DrawCtx *ctx)
/* without it, it can draw over the path on sharp angles (...too long lines) */ /* without it, it can draw over the path on sharp angles (...too long lines) */
cairo_set_line_join (ctx->cr, CAIRO_LINE_JOIN_ROUND); cairo_set_line_join (ctx->cr, CAIRO_LINE_JOIN_ROUND);
} }
/** Draw a graph /** Draw a graph
* \param ctx Draw context * \param ctx Draw context
* \param x x-offset of widget * \param x x-offset of widget
@ -323,7 +329,7 @@ draw_graph(DrawCtx *ctx, int x, int y, int w, int *from, int *to, int cur_index,
{ {
int i; int i;
cairo_pattern_t *pat; cairo_pattern_t *pat;
pat = setup_cairo_color_source(ctx, x, y, w, color, pcolor_center, pcolor_end); pat = draw_setup_cairo_color_source(ctx, x, y, w, color, pcolor_center, pcolor_end);
i = -1; i = -1;
while(++i < w) while(++i < w)
@ -341,6 +347,7 @@ draw_graph(DrawCtx *ctx, int x, int y, int w, int *from, int *to, int cur_index,
if(pat) if(pat)
cairo_pattern_destroy(pat); cairo_pattern_destroy(pat);
} }
/** Draw a line into a graph-widget /** Draw a line into a graph-widget
* \param ctx Draw context * \param ctx Draw context
* \param x x-offset of widget * \param x x-offset of widget
@ -360,7 +367,7 @@ draw_graph_line(DrawCtx *ctx, int x, int y, int w, int *to, int cur_index,
int flag = 0; /* used to prevent drawing a line from 0 to 0 values */ int flag = 0; /* used to prevent drawing a line from 0 to 0 values */
cairo_pattern_t *pat; cairo_pattern_t *pat;
pat = setup_cairo_color_source(ctx, x, y, w, color, pcolor_center, pcolor_end); pat = draw_setup_cairo_color_source(ctx, x, y, w, color, pcolor_center, pcolor_end);
/* x-1 (on the border), paints *from* the last point (... not included itself) */ /* x-1 (on the border), paints *from* the last point (... not included itself) */
/* makes sense when you assume there is already some line drawn to it. */ /* makes sense when you assume there is already some line drawn to it. */
@ -394,6 +401,14 @@ draw_graph_line(DrawCtx *ctx, int x, int y, int w, int *to, int cur_index,
cairo_pattern_destroy(pat); cairo_pattern_destroy(pat);
} }
/** Draw a circle
* \param ctx Draw context to draw to
* \param x x coordinate
* \param y y coordinate
* \param r size of the circle
* \param filled fill circle?
* \param color color to use
*/
void void
draw_circle(DrawCtx *ctx, int x, int y, int r, Bool filled, XColor color) draw_circle(DrawCtx *ctx, int x, int y, int r, Bool filled, XColor color)
{ {
@ -413,6 +428,17 @@ draw_circle(DrawCtx *ctx, int x, int y, int r, Bool filled, XColor color)
cairo_stroke(ctx->cr); cairo_stroke(ctx->cr);
} }
/** Draw an image from ARGB data to a draw context.
* Data should be stored as an array of alpha, red, blue, green for each pixel
* and the array size should be w * h elements long.
* \param ctx Draw context to draw to
* \param x x coordinate
* \param y y coordinate
* \param w width
* \param h height
* \param wanted_h wanted height: if > 0, image will be resized
* \param data the image pixels array
*/
void draw_image_from_argb_data(DrawCtx *ctx, int x, int y, int w, int h, void draw_image_from_argb_data(DrawCtx *ctx, int x, int y, int w, int h,
int wanted_h, unsigned char *data) int wanted_h, unsigned char *data)
{ {
@ -437,6 +463,13 @@ void draw_image_from_argb_data(DrawCtx *ctx, int x, int y, int w, int h,
cairo_surface_destroy(source); cairo_surface_destroy(source);
} }
/** Draw an image (PNG format only) from a file to a draw context
* \param ctx Draw context to draw to
* \param x x coordinate
* \param y y coordinate
* \param wanted_h wanted height: if > 0, image will be resized
* \param filename file name to draw
*/
void void
draw_image(DrawCtx *ctx, int x, int y, int wanted_h, const char *filename) draw_image(DrawCtx *ctx, int x, int y, int wanted_h, const char *filename)
{ {
@ -450,6 +483,7 @@ draw_image(DrawCtx *ctx, int x, int y, int wanted_h, const char *filename)
if((cairo_st = cairo_surface_status(source))) if((cairo_st = cairo_surface_status(source)))
{ {
warn("failed to draw image %s: %s\n", filename, cairo_status_to_string(cairo_st)); warn("failed to draw image %s: %s\n", filename, cairo_status_to_string(cairo_st));
cairo_surface_destroy(source);
return; return;
} }
cr = cairo_create (ctx->surface); cr = cairo_create (ctx->surface);
@ -467,6 +501,10 @@ draw_image(DrawCtx *ctx, int x, int y, int wanted_h, const char *filename)
cairo_surface_destroy(source); cairo_surface_destroy(source);
} }
/** Get an imag size (PNG format only)
* \param filename file name
* \return Area structure with width and height set to image size
*/
Area Area
draw_get_image_size(const char *filename) draw_get_image_size(const char *filename)
{ {
@ -484,12 +522,21 @@ draw_get_image_size(const char *filename)
size.y = 0; size.y = 0;
size.width = cairo_image_surface_get_width(surface); size.width = cairo_image_surface_get_width(surface);
size.height = cairo_image_surface_get_height(surface); size.height = cairo_image_surface_get_height(surface);
cairo_surface_destroy(surface);
} }
cairo_surface_destroy(surface);
return size; return size;
} }
/** Rotate a drawable
* \param ctx Draw context to draw to
* \param phys_screen physical screen id
* \param angle angle to rotate
* \param tx translate to this x coordinate
* \param ty translate to this y coordinate
* \return new rotated drawable
*/
Drawable Drawable
draw_rotate(DrawCtx *ctx, int phys_screen, double angle, int tx, int ty) draw_rotate(DrawCtx *ctx, int phys_screen, double angle, int tx, int ty)
{ {
@ -518,6 +565,12 @@ draw_rotate(DrawCtx *ctx, int phys_screen, double angle, int tx, int ty)
return newdrawable; return newdrawable;
} }
/** Return the width of a text in pixel
* \param disp Display ref
* \param font font to use
* \param text the text
* \return text width
*/
unsigned short unsigned short
draw_textwidth(Display *disp, XftFont *font, char *text) draw_textwidth(Display *disp, XftFont *font, char *text)
{ {
@ -545,6 +598,12 @@ draw_textwidth(Display *disp, XftFont *font, char *text)
return MAX(te.x_advance, te.width); return MAX(te.x_advance, te.width);
} }
/** Transform a string to a Alignment type.
* Recognized string are left, center or right. Everything else will be
* recognized as AlignAuto.
* \param align string with align text
* \return Alignment type
*/
Alignment Alignment
draw_get_align(const char *align) draw_get_align(const char *align)
{ {
@ -560,9 +619,10 @@ draw_get_align(const char *align)
/** Initialize an X color /** Initialize an X color
* \param disp display ref * \param disp display ref
* \param screen Physical screen number * \param phys_screen Physical screen number
* \param colstr Color specification * \param colstr Color specification
* \return XColor struct * \param color XColor struct to store color to
* \return true if color allocation was successfull
*/ */
Bool Bool
draw_color_new(Display *disp, int phys_screen, const char *colstr, XColor *color) draw_color_new(Display *disp, int phys_screen, const char *colstr, XColor *color)
@ -581,8 +641,7 @@ draw_color_new(Display *disp, int phys_screen, const char *colstr, XColor *color
} }
/** Remove a area from a list of them, /** Remove a area from a list of them,
* spliting the space between several area that * spliting the space between several area that can overlaps
* can overlaps
* \param head list head * \param head list head
* \param elem area to remove * \param elem area to remove
*/ */

View File

@ -98,7 +98,6 @@ void draw_text(DrawCtx *, Area, Alignment, int, XftFont *, char *, XColor fg, XC
void draw_rectangle(DrawCtx *, Area, Bool, XColor); void draw_rectangle(DrawCtx *, Area, Bool, XColor);
void draw_rectangle_gradient(DrawCtx *, Area, int, Bool, XColor, XColor *, XColor *); void draw_rectangle_gradient(DrawCtx *, Area, int, Bool, XColor, XColor *, XColor *);
cairo_pattern_t * setup_cairo_color_source(DrawCtx *, int, int, int, XColor, XColor *, XColor *);
void draw_graph_setup(DrawCtx *); void draw_graph_setup(DrawCtx *);
void draw_graph(DrawCtx *, int, int, int, int *, int *, int, XColor, XColor *, XColor *); void draw_graph(DrawCtx *, int, int, int, int *, int *, int, XColor, XColor *, XColor *);
void draw_graph_line(DrawCtx *, int, int, int, int *, int, XColor, XColor *, XColor *); void draw_graph_line(DrawCtx *, int, int, int, int *, int, XColor, XColor *, XColor *);