ClutterCanvas: Clutter Reference Manual

## ClutterCanvas ClutterCanvas — Content for 2D painting |

## Functions

ClutterContent * | clutter_canvas_new ()
gboolean | clutter_canvas_set_size ()
void | clutter_canvas_set_scale_factor ()
int | clutter_canvas_get_scale_factor ()

## Properties

gint | height | Read / Write
gint | scale-factor | Read / Write
gboolean | scale-factor-set | Read
gint | width | Read / Write

## Signals

gboolean | draw | No Recursion

## Types and Values

struct | ClutterCanvas
struct | ClutterCanvasClass

## Object Hierarchy

        GObject
        ╰── ClutterCanvas

## Implemented Interfaces

ClutterCanvas implements ClutterContent.

## Description

The ClutterCanvas class is a ClutterContent implementation that allows drawing using the Cairo API on a 2D surface.

In order to draw on a ClutterCanvas, you should connect a handler to the “draw” signal; the signal will receive a cairo_t context that can be used to draw. ClutterCanvas will emit the “draw” signal when invalidated using `clutter_content_invalidate()`.

See canvas.c for an example of how to use ClutterCanvas.

ClutterCanvas is available since Clutter 1.10.

## Functions

### clutter_canvas_new ()

    ClutterContent *
    clutter_canvas_new (void);

Creates a new instance of ClutterCanvas.

You should call `clutter_canvas_set_size()` to set the size of the canvas.

You should call `clutter_content_invalidate()` every time you wish to draw the contents of the canvas.

#### Returns

The newly allocated instance of ClutterCanvas. Use `g_object_unref()` when done.

[transfer full]

Since: 1.10

### clutter_canvas_set_size ()

    gboolean
    clutter_canvas_set_size (ClutterCanvas *canvas,
                             int width,
                             int height);

Sets the size of the `canvas` , and invalidates the content.

This function will cause the `canvas` to be invalidated only if the size of the canvas surface has changed.

If you want to invalidate the contents of the `canvas` when setting the size, you can use the return value of the function to conditionally call `clutter_content_invalidate()`:

    1
    2
    if (!clutter_canvas_set_size (canvas, width, height))
      clutter_content_invalidate (CLUTTER_CONTENT (canvas));

#### Parameters

canvas | a ClutterCanvas |
width | the width of the canvas, in pixels |
height | the height of the canvas, in pixels |

#### Returns

this function returns `TRUE` if the size change caused a content invalidation, and `FALSE` otherwise

Since: 1.10

### clutter_canvas_set_scale_factor ()

    void
    clutter_canvas_set_scale_factor (ClutterCanvas *canvas,
                                     int scale);

Sets the scaling factor for the Cairo surface used by `canvas` .

This function should rarely be used.

The default scaling factor of a ClutterCanvas content uses the “window-scaling-factor” property, which is set by the windowing system. By using this function it is possible to override that setting.

Changing the scale factor will invalidate the `canvas` .

#### Parameters

canvas | a ClutterCanvas |
scale | the scale factor, or -1 for the default |

Since: 1.18

### clutter_canvas_get_scale_factor ()

    int
    clutter_canvas_get_scale_factor (ClutterCanvas *canvas);

Retrieves the scaling factor of `canvas` , as set using `clutter_canvas_set_scale_factor()`.

#### Parameters

canvas | a ClutterCanvas |

#### Returns

the scaling factor, or -1 if the `canvas` uses the default from ClutterSettings

Since: 1.18

## Types and Values

### struct ClutterCanvas

    struct ClutterCanvas;

The ClutterCanvas structure contains private data and should only be accessed using the provided API.

Since: 1.10

### struct ClutterCanvasClass

    struct ClutterCanvasClass {
      gboolean (* draw) (ClutterCanvas *canvas,
                         cairo_t       *cr,
                         int            width,
                         int            height);
    };

The ClutterCanvasClass structure contains private data.

#### Members

`draw` () | class handler for the “draw” signal |

Since: 1.10

## Property Details

### The `“height”` property

      “height”                   gint

The height of the canvas.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 1.10

### The `“scale-factor”` property

      “scale-factor”             gint

The scaling factor to be applied to the Cairo surface used for drawing.

If “scale-factor” is set to a negative value, the value of the “window-scaling-factor” property is used instead.

Use “scale-factor-set” to check if the scale factor is set.

Flags: Read / Write

Allowed values: [-1,1000]

Default value: -1

Since: 1.18

### The `“scale-factor-set”` property

      “scale-factor-set”         gboolean

Whether the “scale-factor” property is set.

If the “scale-factor-set” property is `FALSE` then ClutterCanvas will use the “window-scaling-factor” property.

Flags: Read

Default value: FALSE

Since: 1.18

### The `“width”` property

      “width”                    gint

The width of the canvas.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 1.10

## Signal Details

### The `“draw”` signal

    gboolean
    user_function (ClutterCanvas *canvas,
                   CairoContext  *cr,
                   gint           width,
                   gint           height,
                   gpointer       user_data)

The “draw” signal is emitted each time a canvas is invalidated.

It is safe to connect multiple handlers to this signal: each handler invocation will be automatically protected by `cairo_save()` and `cairo_restore()` pairs.

#### Parameters

canvas | the ClutterCanvas that emitted the signal |
cr | the Cairo context used to draw |
width | the width of the `canvas` |
height | the height of the `canvas` |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the signal emission should stop, and `FALSE` otherwise

Flags: No Recursion

Since: 1.10

## See Also

ClutterContent