## Cairo drawing utils

Cairo drawing utils — Auxiliary and impedance matching functions for Cairo drawing

## Functions

void | gwy_cairo_set_source_rgba ()
cairo_pattern_t * | gwy_cairo_pattern_create_gradient ()
void | gwy_cairo_checker_rectangle ()
void | gwy_cairo_line ()
void | gwy_cairo_ellipse ()
void | gwy_cairo_cross ()
void | gwy_cairo_times ()
void | gwy_cairo_asterisk ()
void | gwy_cairo_square ()
void | gwy_cairo_diamond ()
void | gwy_cairo_triangle_up ()
void | gwy_cairo_triangle_down ()
void | gwy_cairo_triangle_left ()
void | gwy_cairo_triangle_right ()
void | gwy_cairo_draw_symbol ()
void | gwy_cairo_draw_symbols ()
void | gwy_cairo_draw_line ()
void | gwy_cairo_region_add_line ()
void | gwy_cairo_region_add_crectangle ()
void | gwy_cairo_region_add_erectangle ()
void | gwy_cairo_region_add_ellipse ()
void | gwy_cairo_region_add_layout ()
void | gwy_cairo_draw_or_add_thin_line ()
void | gwy_cairo_draw_or_add_layout ()

## Types and Values

enum | GwySymbolType
enum | GwyLineStyle

## Includes

    #include <libgwyui/gwyui.h>

## Description

Drawing primitives for simple geometrical shapes such as `gwy_cairo_cross()` or `gwy_cairo_triangle_up()` are namely useful for drawing markes and symbols on graphs because they are visually centered on given coordinates. Nevertheless, the sizes are given as natural parameters. Use `gwy_cairo_draw_symbol()` to visually uniform sizes.

## Functions

### gwy_cairo_set_source_rgba()

    void
    gwy_cairo_set_source_rgba (cairo_t *cr,
                               const GwyRGBA *rgba);

Sets the source patter of a Cairo context to GwyRGBA color.

This is a convenience function that is exactly equivalent to

    1

    cairo_set_source_rgba(cr, rgba->r, rgba->g, rgba->b, rgba->a);

#### Parameters

cr | A Cairo drawing context. |
rgba | An RGBA colour. |

### gwy_cairo_pattern_create_gradient()

    cairo_pattern_t *
    gwy_cairo_pattern_create_gradient (GwyGradient *gradient,
                                       GtkPositionType towards,
                                       gboolean use_alpha);

Creates a linear Cairo pattern corresponding to a false colour gradient.

The pattern is always along the interval [0,1] in either horizontal or vertical direction and either towards 1 or towards 0, depending on the value of `towards` .

#### Parameters

gradient | A false colour gradient. |
towards | Gradient direction in the plane. |
use_alpha | `TRUE` to use the alpha components and create a possibly semitransparent pattern; `FALSE` to render all colours with full opacity. |

#### Returns

A newly created linear Cairo pattern.

[transfer full]

### gwy_cairo_checker_rectangle()

    void
    gwy_cairo_checker_rectangle (cairo_t *cr,
                                 const GwyRGBA *even,
                                 const GwyRGBA *odd,
                                 gint width,
                                 gint height,
                                 gint size);

### gwy_cairo_line()

    void
    gwy_cairo_line (cairo_t *cr,
                    gdouble xfrom,
                    gdouble yfrom,
                    gdouble xto,
                    gdouble yto);

Adds a straight line subpath to a Cairo context.

A new subpath is started, but it is not terminated. Use `cairo_new_sub_path()` or other subpath-terminating primitive afterwards if necessary. All parameters are in user coordinates.

This function does `cairo_move_to()` and `cairo_line_to()` in a single call, simplifying common line drawing a bit.

#### Parameters

cr | A Cairo drawing context. |
xfrom | X-coordinate of start point of the line. |
yfrom | Y-coordinate of start point of the line. |
xto | X-coordinate of end point of the line. |
yto | Y-coordinate of end point of the line. |

### gwy_cairo_ellipse()

    void
    gwy_cairo_ellipse (cairo_t *cr,
                       gdouble x,
                       gdouble y,
                       gdouble xr,
                       gdouble yr);

Adds a closed elliptical subpath to a Cairo context.

A new subpath is started and closed. The ellipse is approximated using Bezier curves, on the other hand, it does not rely on transformations. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
xr | Horizontal half-axis length. |
yr | Vertical half-axis length. |

### gwy_cairo_cross()

    void
    gwy_cairo_cross (cairo_t *cr,
                     gdouble x,
                     gdouble y,
                     gdouble halfside);

Adds a cross-shaped subpath to a Cairo context.

A new subpath is started and terminated. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Length of the cross arm (from centre to end), i.e. half of the side of the smallest square containing the cross. |

### gwy_cairo_times()

    void
    gwy_cairo_times (cairo_t *cr,
                     gdouble x,
                     gdouble y,
                     gdouble halfside);

Adds a times-shaped subpath to a Cairo context.

A new subpath is started and terminated. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the smallest square containing the cross. |

### gwy_cairo_asterisk()

    void
    gwy_cairo_asterisk (cairo_t *cr,
                        gdouble x,
                        gdouble y,
                        gdouble halfside);

Adds a rightward pointing triangle-shaped subpath to a Cairo context.

A new subpath is started and terminated. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the containing square. |

### gwy_cairo_square()

    void
    gwy_cairo_square (cairo_t *cr,
                      gdouble x,
                      gdouble y,
                      gdouble halfside);

Adds a square-shaped subpath to a Cairo context.

A new subpath is started and closed. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the square. |

### gwy_cairo_diamond()

    void
    gwy_cairo_diamond (cairo_t *cr,
                       gdouble x,
                       gdouble y,
                       gdouble halfside);

Adds a diamond-shaped subpath to a Cairo context.

A new subpath is started and closed. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the containing square. |

### gwy_cairo_triangle_up()

    void
    gwy_cairo_triangle_up (cairo_t *cr,
                           gdouble x,
                           gdouble y,
                           gdouble halfside);

Adds an upward pointing triangle-shaped subpath to a Cairo context.

A new subpath is started and closed. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the containing square. |

### gwy_cairo_triangle_down()

    void
    gwy_cairo_triangle_down (cairo_t *cr,
                             gdouble x,
                             gdouble y,
                             gdouble halfside);

Adds a downward pointing triangle-shaped subpath to a Cairo context.

A new subpath is started and closed. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the containing square. |

### gwy_cairo_triangle_left()

    void
    gwy_cairo_triangle_left (cairo_t *cr,
                             gdouble x,
                             gdouble y,
                             gdouble halfside);

Adds a leftward pointing triangle-shaped subpath to a Cairo context.

A new subpath is started and closed. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the containing square. |

### gwy_cairo_triangle_right()

    void
    gwy_cairo_triangle_right (cairo_t *cr,
                              gdouble x,
                              gdouble y,
                              gdouble halfside);

Adds a rightward pointing triangle-shaped subpath to a Cairo context.

A new subpath is started and closed. All parameters are in user coordinates.

#### Parameters

cr | A Cairo drawing context. |
x | Centre x-coordinate. |
y | Centre y-coordinate. |
halfside | Half of the side of the containing square. |

### gwy_cairo_draw_symbol()

    void
    gwy_cairo_draw_symbol (cairo_t *cr,
                           gdouble x,
                           gdouble y,
                           GwySymbolType symbol_type,
                           gdouble size,
                           const GwyRGBA *color);

Draws a graph symbol on a drawable.

Consider using `gwy_cairo_draw_symbols()` if you are drawing many symbols.

#### Parameters

cr | Cairo context. |
x | X coordinate of the point. |
y | Y coordinate of the point. |
symbol_type | Symbol type. |
size | Symbol size. |
color | Symbol color. If `NULL`, the color is not set. | [nullable]

### gwy_cairo_draw_symbols()

    void
    gwy_cairo_draw_symbols (cairo_t *cr,
                            const GwyXY *coords,
                            guint n,
                            GwySymbolType symbol_type,
                            gdouble size,
                            const GwyRGBA *color);

Draws multiple graph symbols.

#### Parameters

cr | Cairo context. |
coords | Point coordinates, as concatenated pairs (x, y). |
n | The number of points. |
symbol_type | Symbol type. |
size | Symbol size. |
color | Symbol color. If `NULL`, the color is not set. | [nullable]

### gwy_cairo_draw_line()

    void
    gwy_cairo_draw_line (cairo_t *cr,
                         gdouble x_from,
                         gdouble y_from,
                         gdouble x_to,
                         gdouble y_to,
                         GwyLineStyle line_style,
                         gdouble width,
                         const GwyRGBA *color);

Draws a line segment on a drawable.

#### Parameters

cr | Cairo context. |
x_from | x coordinate of the start point of the line |
y_from | y coordinate of the start point of the line |
x_to | x coordinate of the end point of the line |
y_to | y coordinate of the end point of the line |
line_style | Line style. |
width | Line width. |
color | Line color. If `NULL`, the color is not set. | [nullable]

### gwy_cairo_region_add_line()

    void
    gwy_cairo_region_add_line (cairo_region_t *region,
                               gdouble xfrom,
                               gdouble yfrom,
                               gdouble xto,
                               gdouble yto,
                               gdouble lw);

Updates a Cairo region by adding the area containing an arbitrary straight line.

#### Parameters

region | Cario region to update. |
xfrom | X-coordinate of start point of the line. |
yfrom | Y-coordinate of start point of the line. |
xto | X-coordinate of end point of the line. |
yto | Y-coordinate of end point of the line. |
lw | Line width. |

### gwy_cairo_region_add_crectangle()

    void
    gwy_cairo_region_add_crectangle (cairo_region_t *region,
                                     gdouble xc,
                                     gdouble yc,
                                     gdouble xr,
                                     gdouble yr,
                                     gdouble lw);

Updates a Cairo region by adding the area containing a rectangle given the centre and half-size.

#### Parameters

region | Cario region to update. |
xc | X-coordinate of rectangle centre. |
yc | Y-coordinate of rectangle centre. |
xr | Half of X-size of the rectangle. |
yr | Half of y-size of the rectangle. |
lw | Line width. |

### gwy_cairo_region_add_erectangle()

    void
    gwy_cairo_region_add_erectangle (cairo_region_t *region,
                                     gdouble x1,
                                     gdouble y1,
                                     gdouble x2,
                                     gdouble y2,
                                     gdouble lw);

Updates a Cairo region by adding the area containing a rectangle given two opposite corners.

#### Parameters

region | Cario region to update. |
x1 | X-coordinate of one rectangle corner. |
y1 | Y-coordinate of one rectangle corner. |
x2 | X-coordinate of the opposite rectangle corner. |
y2 | Y-coordinate of the opposite rectangle corner. |
lw | Line width. |

### gwy_cairo_region_add_ellipse()

    void
    gwy_cairo_region_add_ellipse (cairo_region_t *region,
                                  gdouble xc,
                                  gdouble yc,
                                  gdouble xr,
                                  gdouble yr,
                                  gdouble lw);

Updates a Cairo region by adding the area containing an ellipse given the centre and semi-axes.

#### Parameters

region | Cario region to update. |
xc | X-coordinate of ellipse centre. |
yc | Y-coordinate of ellipse centre. |
xr | X-semiaxis of the ellipse. |
yr | Y-semiaxis of the ellipse. |
lw | Line width. |

### gwy_cairo_region_add_layout()

    void
    gwy_cairo_region_add_layout (cairo_region_t *region,
                                 PangoLayout *layout,
                                 gdouble x,
                                 gdouble y);

Updates a Cairo region by adding the area containing a Pango layout.

The area corresponds to the text being drawn with `pango_cairo_show_layout()` after moving to (`x` , `y` ).

#### Parameters

region | Cario region to update. |
layout | Pango layout to render at context's current coordinates. |
x | Text origin x-coordinate. |
y | Text origin y-coordinate. |

### gwy_cairo_draw_or_add_thin_line()

    void
    gwy_cairo_draw_or_add_thin_line (cairo_t *cr,
                                     cairo_region_t *region,
                                     gdouble xfrom,
                                     gdouble yfrom,
                                     gdouble xto,
                                     gdouble yto);

Draws a line and/or updates a Cairo region to add the line's area.

This is a convenience function wrapping `gwy_cairo_line()` and `gwy_cairo_region_add_line()`. Either one or both are called, depending on which of `cr` and `region` are non-NULL. The line is must be thin.

#### Parameters

cr | A Cairo drawing context, or `NULL`. |
region | Cario region to update, or `NULL`. |
xfrom | X-coordinate of start point of the line. |
yfrom | Y-coordinate of start point of the line. |
xto | X-coordinate of end point of the line. |
yto | Y-coordinate of end point of the line. |

### gwy_cairo_draw_or_add_layout()

    void
    gwy_cairo_draw_or_add_layout (cairo_t *cr,
                                  cairo_region_t *region,
                                  PangoLayout *layout,
                                  gdouble x,
                                  gdouble y);

Renders a Pango layout and/or updates a Cairo region to add the text's area.

The coordinates have the effect of `cairo_move_to()` to the specified point. Normally, this function would not be called in the middle of drawing a path. Still, be aware the Cairo context position is modified.

This is a convenience function wrapping `pango_cairo_show_layout()` and `gwy_cairo_region_add_layout()`. Either one or both are called, depending on which of `cr` and `region` are non-NULL.

#### Parameters

cr | A Cairo drawing context, or `NULL`. |
region | Cario region to update, or `NULL`. |
layout | Pango layout to render at context's current coordinates. |
x | Text origin x-coordinate. |
y | Text origin y-coordinate. |

## Types and Values

### enum GwySymbolType

#### Members

GWY_SYMBOL_SQUARE |  |
GWY_SYMBOL_CROSS |  |
GWY_SYMBOL_CIRCLE |  |
GWY_SYMBOL_STAR |  |
GWY_SYMBOL_TIMES |  |
GWY_SYMBOL_TRIANGLE_UP |  |
GWY_SYMBOL_TRIANGLE_DOWN |  |
GWY_SYMBOL_DIAMOND |  |
GWY_SYMBOL_FILLED_SQUARE |  |
GWY_SYMBOL_DISC |  |
GWY_SYMBOL_FILLED_CIRCLE |  |
GWY_SYMBOL_FILLED_TRIANGLE_UP |  |
GWY_SYMBOL_FILLED_TRIANGLE_DOWN |  |
GWY_SYMBOL_FILLED_DIAMOND |  |
GWY_SYMBOL_TRIANGLE_LEFT |  |
GWY_SYMBOL_FILLED_TRIANGLE_LEFT |  |
GWY_SYMBOL_TRIANGLE_RIGHT |  |
GWY_SYMBOL_FILLED_TRIANGLE_RIGHT |  |
GWY_SYMBOL_ASTERISK |  |

### enum GwyLineStyle

#### Members

GWY_LINE_SOLID |  |
GWY_LINE_DASH |  |
GWY_LINE_DASH_SPARSE |  |
GWY_LINE_DASH_DENSE |  |
GWY_LINE_DOT |  |
GWY_LINE_DOT_SPARSE |  |
GWY_LINE_DASH_DOT |  |