Cairo Interaction: GDK 2 Reference Manual

## Cairo Interaction Cairo Interaction — Functions to support using Cairo |

## Functions

cairo_surface_t * | gdk_window_create_similar_surface ()
cairo_t * | gdk_cairo_create ()
void | gdk_cairo_set_source_color ()
void | gdk_cairo_set_source_pixbuf ()
void | gdk_cairo_set_source_pixmap ()
void | gdk_cairo_set_source_window ()
void | gdk_cairo_rectangle ()
void | gdk_cairo_region ()
void | gdk_cairo_reset_clip ()

## Includes

    #include <gdk/gdk.h>

## Description

Cairo is a graphics library that supports vector graphics and image compositing that can be used with GDK. Since 2.8, GTK+ does most 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 GDK drawables. Additional functions allow to convert GDK's rectangles and regions into Cairo paths and to use pixbufs as sources for drawing operations.

## Functions

### 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.)

#### Parameters

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 that due to double-buffering, Cairo contexts created in a GTK+ expose event handler cannot be cached and reused between different expose events.

#### Parameters

drawable | a GdkDrawable |

#### Returns

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

Since 2.8

### 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` .

#### Parameters

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`

#### Parameters

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_pixmap ()

    void
    gdk_cairo_set_source_pixmap (cairo_t *cr,
                                 GdkPixmap *pixmap,
                                 double pixmap_x,
                                 double pixmap_y);

`gdk_cairo_set_source_pixmap` has been deprecated since version 2.24 and should not be used in newly-written code.

This function is being removed in GTK+ 3 (together with GdkPixmap). Instead, use `gdk_cairo_set_source_window()` where appropriate.

Sets the given pixmap 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 `pixmap` is `pixmap_x` , `pixmap_y`

#### Parameters

cr | a Cairo context |
pixmap | a GdkPixmap |
pixmap_x | X coordinate of location to place upper left corner of `pixmap` |
pixmap_y | Y coordinate of location to place upper left corner of `pixmap` |

Since 2.10

### 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.

#### Parameters

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` .

#### Parameters

cr | a cairo_t |
rectangle | a GdkRectangle |

Since 2.8

### gdk_cairo_region ()

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

Adds the given region to the current path of `cr` .

#### Parameters

cr | a cairo_t |
region | a GdkRegion |

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.

#### Parameters

cr | a cairo_t |
drawable | a GdkDrawable |

Since 2.18

## Types and Values