## ClutterBackend

ClutterBackend — Backend abstraction

## Synopsis

                        ClutterBackend;
    ClutterBackend *    clutter_get_default_backend         (void);
    void                clutter_backend_set_resolution      (ClutterBackend *backend,
                                                             gdouble dpi);
    gdouble             clutter_backend_get_resolution      (ClutterBackend *backend);
    void                clutter_backend_set_double_click_time
                                                            (ClutterBackend *backend,
                                                             guint msec);
    guint               clutter_backend_get_double_click_time
                                                            (ClutterBackend *backend);
    void                clutter_backend_set_double_click_distance
                                                            (ClutterBackend *backend,
                                                             guint distance);
    guint               clutter_backend_get_double_click_distance
                                                            (ClutterBackend *backend);
    void                clutter_backend_set_font_options    (ClutterBackend *backend,
                                                             const cairo_font_options_t *options);
    const cairo_font_options_t * clutter_backend_get_font_options
                                                            (ClutterBackend *backend);
    void                clutter_backend_set_font_name       (ClutterBackend *backend,
                                                             const gchar *font_name);
    const gchar *       clutter_backend_get_font_name       (ClutterBackend *backend);
    CoglContext *       clutter_backend_get_cogl_context    (ClutterBackend *backend);

    gboolean            clutter_check_windowing_backend     (const char *backend_type);
    void                clutter_set_windowing_backend       (const char *backend_type);

## Object Hierarchy

      GObject
       +----ClutterBackend

## Signals

      "font-changed"                                   : Run First
      "resolution-changed"                             : Run First
      "settings-changed"                               : Run First

## Description

Clutter can be compiled against different backends. Each backend has to implement a set of functions, in order to be used by Clutter.

ClutterBackend is the base class abstracting the various implementation; it provides a basic API to query the backend for generic information and settings.

ClutterBackend is available since Clutter 0.4

## Details

### ClutterBackend

    typedef struct _ClutterBackend ClutterBackend;

ClutterBackend is an opaque structure whose members cannot be directly accessed.

Since 0.4

### clutter_get_default_backend ()

    ClutterBackend *    clutter_get_default_backend         (void);

Retrieves the default ClutterBackend used by Clutter. The ClutterBackend holds backend-specific configuration options.

Returns : | the default backend. You should not ref or unref the returned object. Applications should rarely need to use this. [transfer none]

Since 0.4

### clutter_backend_set_resolution ()

    void                clutter_backend_set_resolution      (ClutterBackend *backend,
                                                             gdouble dpi);

### Warning

`clutter_backend_set_resolution` has been deprecated since version 1.4 and should not be used in newly-written code. Use "font-dpi" instead

Sets the resolution for font handling on the screen. This is a scale factor between points specified in a PangoFontDescription and cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3).

Applications should never need to call this function.

`backend` : | a ClutterBackend
`dpi` : | the resolution in "dots per inch" (Physical inches aren't actually involved; the terminology is conventional).

Since 0.4

### clutter_backend_get_resolution ()

    gdouble             clutter_backend_get_resolution      (ClutterBackend *backend);

Gets the resolution for font handling on the screen.

The resolution is a scale factor between points specified in a PangoFontDescription and cairo units. The default value is 96.0, meaning that a 10 point font will be 13 units high (10 * 96. / 72. = 13.3).

Clutter will set the resolution using the current backend when initializing; the resolution is also stored in the "font-dpi" property.

`backend` : | a ClutterBackend
Returns : | the current resolution, or -1 if no resolution has been set.

Since 0.4

### clutter_backend_set_double_click_time ()

    void                clutter_backend_set_double_click_time
                                                            (ClutterBackend *backend,
                                                             guint msec);

### Warning

`clutter_backend_set_double_click_time` has been deprecated since version 1.4 and should not be used in newly-written code. Use "double-click-time" instead

Sets the maximum time between two button press events, used to verify whether it's a double click event or not.

`backend` : | a ClutterBackend
`msec` : | milliseconds between two button press events

Since 0.4

### clutter_backend_get_double_click_time ()

    guint               clutter_backend_get_double_click_time
                                                            (ClutterBackend *backend);

### Warning

`clutter_backend_get_double_click_time` has been deprecated since version 1.4 and should not be used in newly-written code. Use "double-click-time" instead

Gets the maximum time between two button press events, as set by `clutter_backend_set_double_click_time()`.

`backend` : | a ClutterBackend
Returns : | a time in milliseconds

Since 0.4

### clutter_backend_set_double_click_distance ()

    void                clutter_backend_set_double_click_distance
                                                            (ClutterBackend *backend,
                                                             guint distance);

### Warning

`clutter_backend_set_double_click_distance` has been deprecated since version 1.4 and should not be used in newly-written code. Use "double-click-distance" instead

Sets the maximum distance used to verify a double click event.

`backend` : | a ClutterBackend
`distance` : | a distance, in pixels

Since 0.4

### clutter_backend_get_double_click_distance ()

    guint               clutter_backend_get_double_click_distance
                                                            (ClutterBackend *backend);

### Warning

`clutter_backend_get_double_click_distance` has been deprecated since version 1.4 and should not be used in newly-written code. Use "double-click-distance" instead

Retrieves the distance used to verify a double click event

`backend` : | a ClutterBackend
Returns : | a distance, in pixels.

Since 0.4

### clutter_backend_set_font_options ()

    void                clutter_backend_set_font_options    (ClutterBackend *backend,
                                                             const cairo_font_options_t *options);

Sets the new font options for `backend`. The ClutterBackend will copy the cairo_font_options_t.

If `options` is `NULL`, the first following call to `clutter_backend_get_font_options()` will return the default font options for `backend`.

This function is intended for actors creating a Pango layout using the PangoCairo API.

`backend` : | a ClutterBackend
`options` : | Cairo font options for the backend, or `NULL`

Since 0.8

### clutter_backend_get_font_options ()

    const cairo_font_options_t * clutter_backend_get_font_options
                                                            (ClutterBackend *backend);

Retrieves the font options for `backend`.

`backend` : | a ClutterBackend
Returns : | the font options of the ClutterBackend. The returned cairo_font_options_t is owned by the backend and should not be modified or freed. [transfer none]

Since 0.8

### clutter_backend_set_font_name ()

    void                clutter_backend_set_font_name       (ClutterBackend *backend,
                                                             const gchar *font_name);

### Warning

`clutter_backend_set_font_name` has been deprecated since version 1.4 and should not be used in newly-written code. Use "font-name" instead

Sets the default font to be used by Clutter. The `font_name` string must either be `NULL`, which means that the font name from the default ClutterBackend will be used; or be something that can be parsed by the `pango_font_description_from_string()` function.

`backend` : | a ClutterBackend
`font_name` : | the name of the font

Since 1.0

### clutter_backend_get_font_name ()

    const gchar *       clutter_backend_get_font_name       (ClutterBackend *backend);

### Warning

`clutter_backend_get_font_name` has been deprecated since version 1.4 and should not be used in newly-written code. Use "font-name" instead

Retrieves the default font name as set by `clutter_backend_set_font_name()`.

`backend` : | a ClutterBackend
Returns : | the font name for the backend. The returned string is owned by the ClutterBackend and should never be modified or freed

Since 1.0

### clutter_backend_get_cogl_context ()

    CoglContext *       clutter_backend_get_cogl_context    (ClutterBackend *backend);

Retrieves the CoglContext associated with the given clutter `backend`. A CoglContext is required when using some of the experimental 2.0 Cogl API.

### Note

Since CoglContext is itself experimental API this API should be considered experimental too.

### Note

This API is not yet supported on OSX because OSX still uses the stub Cogl winsys and the Clutter backend doesn't explicitly create a CoglContext.

`backend` : | a ClutterBackend
Returns : | The CoglContext associated with `backend`. [transfer none]

Since 1.8

Stability Level: Unstable

### clutter_check_windowing_backend ()

    gboolean            clutter_check_windowing_backend     (const char *backend_type);

Checks the run-time name of the Clutter windowing system backend, using the symbolic macros like `CLUTTER_WINDOWING_WIN32` or `CLUTTER_WINDOWING_X11`.

This function should be used in conjuction with the compile-time macros inside applications and libraries that are using the platform-specific windowing system API, to ensure that they are running on the correct windowing system; for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15

    #ifdef CLUTTER_WINDOWING_X11
      if (clutter_check_windowing_backend (CLUTTER_WINDOWING_X11))
        {
          /* it is safe to use the clutter_x11_* API */
        }
      else
    #endif
    #ifdef CLUTTER_WINDOWING_WIN32
      if (clutter_check_windowing_backend (CLUTTER_WINDOWING_WIN32))
        {
          /* it is safe to use the clutter_win32_* API */
        }
      else
    #endif
        g_error ("Unknown Clutter backend.");

`backend_type` : | the name of the backend to check
Returns : | `TRUE` if the current Clutter windowing system backend is the one checked, and `FALSE` otherwise

Since 1.10

### clutter_set_windowing_backend ()

    void                clutter_set_windowing_backend       (const char *backend_type);

Restricts clutter to only use the specified backend. This must be called before the first API call to clutter, including `clutter_get_option_context()`

`backend_type` : | the name of a clutter window backend

Since 1.16

## Signal Details

### The `"font-changed"` signal

    void                user_function                      (ClutterBackend *backend,
                                                            gpointer        user_data)      : Run First

The ::font-changed signal is emitted each time the font options have been changed through ClutterSettings.

`backend` : | the ClutterBackend that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.0

### The `"resolution-changed"` signal

    void                user_function                      (ClutterBackend *backend,
                                                            gpointer        user_data)      : Run First

The ::resolution-changed signal is emitted each time the font resolutions has been changed through ClutterSettings.

`backend` : | the ClutterBackend that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.0

### The `"settings-changed"` signal

    void                user_function                      (ClutterBackend *backend,
                                                            gpointer        user_data)      : Run First

The ::settings-changed signal is emitted each time the ClutterSettings properties have been changed.

`backend` : | the ClutterBackend that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.4