ClutterBackend: Clutter Reference Manual

## ClutterBackend ClutterBackend — Backend abstraction |

## Functions

ClutterBackend * | clutter_get_default_backend ()
void | clutter_backend_set_resolution ()
gdouble | clutter_backend_get_resolution ()
void | clutter_backend_set_double_click_time ()
guint | clutter_backend_get_double_click_time ()
void | clutter_backend_set_double_click_distance ()
guint | clutter_backend_get_double_click_distance ()
void | clutter_backend_set_font_options ()
const cairo_font_options_t * | clutter_backend_get_font_options ()
void | clutter_backend_set_font_name ()
const gchar * | clutter_backend_get_font_name ()
CoglContext * | clutter_backend_get_cogl_context ()
gboolean | clutter_check_windowing_backend ()
void | clutter_set_windowing_backend ()

## Signals

void | font-changed | Run First
void | resolution-changed | Run First
void | settings-changed | Run First

## Types and Values

| ClutterBackend

## Object Hierarchy

        GObject
        ╰── ClutterBackend

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

## Functions

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

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

#### Parameters

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.

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

`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

#### Parameters

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.

#### Parameters

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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.

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

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.

#### Parameters

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.");

#### Parameters

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

#### Parameters

backend_type | the name of a clutter window backend |

Since 1.16

## Types and Values

### ClutterBackend

    typedef struct _ClutterBackend ClutterBackend;

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

Since 0.4

## Signal Details

### The `“font-changed”` signal

    void
    user_function (ClutterBackend *backend,
                   gpointer        user_data)

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

#### Parameters

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

Flags: Run First

Since 1.0

### The `“resolution-changed”` signal

    void
    user_function (ClutterBackend *backend,
                   gpointer        user_data)

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

#### Parameters

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

Flags: Run First

Since 1.0

### The `“settings-changed”` signal

    void
    user_function (ClutterBackend *backend,
                   gpointer        user_data)

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

#### Parameters

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

Flags: Run First

Since 1.4