Cairo Interaction

Cairo Interaction — Functions to support using Cairo

Synopsis

#include <gdk/gdk.h>

cairo_surface_t *   gdk_window_create_similar_surface   (GdkWindow *window,
                                                         cairo_content_t content,
                                                         int width,
                                                         int height);
cairo_t *           gdk_cairo_create                    (GdkDrawable *drawable);
gboolean            gdk_cairo_get_clip_rectangle        (cairo_t *cr,
                                                         GdkRectangle *rect);
void                gdk_cairo_set_source_color          (cairo_t *cr,
                                                         const GdkColor *color);
void                gdk_cairo_set_source_pixbuf         (cairo_t *cr,
                                                         const GdkPixbuf *pixbuf,
                                                         double pixbuf_x,
                                                         double pixbuf_y);
void                gdk_cairo_set_source_window         (cairo_t *cr,
                                                         GdkWindow *window,
                                                         double x,
                                                         double y);
void                gdk_cairo_rectangle                 (cairo_t *cr,
                                                         const GdkRectangle *rectangle);
void                gdk_cairo_region                    (cairo_t *cr,
                                                         const cairo_region_t *region);
void                gdk_cairo_reset_clip                (cairo_t *cr,
                                                         GdkDrawable *drawable);
cairo_region_t *    gdk_cairo_region_create_from_surface
                                                        (cairo_surface_t *surface);

Description

Cairo is a graphics library that supports vector graphics and image compositing that can be used with GDK. GTK+ does all of its drawing using Cairo.

GDK does not wrap the Cairo API, instead it allows to create Cairo contexts which can be used to draw on GdkWindows. Additional functions allow use GdkRectangles with cairo and to use GdkColors, GdkPixbufs and GdkWindows as sources for drawing operations.

Details

gdk_window_create_similar_surface ()

cairo_surface_t *   gdk_window_create_similar_surface   (GdkWindow *window,
                                                         cairo_content_t content,
                                                         int width,
                                                         int height);

Create a new surface that is as compatible as possible with the given window. For example the new surface will have the same fallback resolution and font options as window. Generally, the new surface will also use the same backend as window, unless that is not possible for some reason. The type of the returned surface may be examined with cairo_surface_get_type().

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

window :

window to make new surface similar to

content :

the content for the new surface

width :

width of the new surface

height :

height of the new surface

Returns :

a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if other is already in an error state or any other error occurs.

Since 2.22


gdk_cairo_create ()

cairo_t *           gdk_cairo_create                    (GdkDrawable *drawable);

Creates a Cairo context for drawing to drawable.

Note

Note that due to double-buffering, Cairo contexts created in a GTK+ expose event handler cannot be cached and reused between different expose events.

drawable :

a GdkDrawable

Returns :

A newly created Cairo context. Free with cairo_destroy() when you are done drawing.

Since 2.8


gdk_cairo_get_clip_rectangle ()

gboolean            gdk_cairo_get_clip_rectangle        (cairo_t *cr,
                                                         GdkRectangle *rect);

This is a convenience function around cairo_clip_extents(). It rounds the clip extents to integer coordinates and returns a boolean indicating if a clip area exists.

cr :

a cairo context

rect :

return location for the clip, or NULL. [out][allow-none]

Returns :

TRUE if a clip rectangle exists, FALSE if all of cr is clipped and all drawing can be skipped.

gdk_cairo_set_source_color ()

void                gdk_cairo_set_source_color          (cairo_t *cr,
                                                         const GdkColor *color);

Sets the specified GdkColor as the source color of cr.

cr :

a cairo_t

color :

a GdkColor

Since 2.8


gdk_cairo_set_source_pixbuf ()

void                gdk_cairo_set_source_pixbuf         (cairo_t *cr,
                                                         const GdkPixbuf *pixbuf,
                                                         double pixbuf_x,
                                                         double pixbuf_y);

Sets the given pixbuf as the source pattern for the Cairo context. The pattern has an extend mode of CAIRO_EXTEND_NONE and is aligned so that the origin of pixbuf is pixbuf_x, pixbuf_y

cr :

a Cairo context

pixbuf :

a GdkPixbuf

pixbuf_x :

X coordinate of location to place upper left corner of pixbuf

pixbuf_y :

Y coordinate of location to place upper left corner of pixbuf

Since 2.8


gdk_cairo_set_source_window ()

void                gdk_cairo_set_source_window         (cairo_t *cr,
                                                         GdkWindow *window,
                                                         double x,
                                                         double y);

Sets the given window as the source pattern for the Cairo context. The pattern has an extend mode of CAIRO_EXTEND_NONE and is aligned so that the origin of window is x, y. The window contains all its subwindows when rendering.

Note that the contents of window are undefined outside of the visible part of window, so use this function with care.

cr :

a Cairo context

window :

a GdkWindow

x :

X coordinate of location to place upper left corner of window

y :

Y coordinate of location to place upper left corner of window

Since 2.24


gdk_cairo_rectangle ()

void                gdk_cairo_rectangle                 (cairo_t *cr,
                                                         const GdkRectangle *rectangle);

Adds the given rectangle to the current path of cr.

cr :

a cairo_t

rectangle :

a GdkRectangle

Since 2.8


gdk_cairo_region ()

void                gdk_cairo_region                    (cairo_t *cr,
                                                         const cairo_region_t *region);

Adds the given region to the current path of cr.

cr :

a cairo_t

region :

a cairo_region_t

Since 2.8


gdk_cairo_reset_clip ()

void                gdk_cairo_reset_clip                (cairo_t *cr,
                                                         GdkDrawable *drawable);

Resets the clip region for a Cairo context created by gdk_cairo_create().

This resets the clip region to the "empty" state for the given drawable. This is required for non-native windows since a direct call to cairo_reset_clip() would unset the clip region inherited from the drawable (i.e. the window clip region), and thus let you e.g. draw outside your window.

This is rarely needed though, since most code just create a new cairo_t using gdk_cairo_create() each time they want to draw something.

cr :

a cairo_t

drawable :

a GdkDrawable

Since 2.18


gdk_cairo_region_create_from_surface ()

cairo_region_t *    gdk_cairo_region_create_from_surface
                                                        (cairo_surface_t *surface);

Creates region that describes covers the area where the given surface is more than 50% opaque. This function takes into account device offsets that might be set with cairo_surface_set_device_offset().

surface :

A surface

Returns :

A cairo_region_t. This must be freed with cairo_region_destroy() when you are done.