Utility Functions

## Utility Functions Utility Functions — Utility functions for integrating Clutter in GTK+ |

## Synopsis

    enum                ClutterGtkInitError;
    ClutterInitError    gtk_clutter_init                    (int *argc,
                                                             char ***argv);
    ClutterInitError    gtk_clutter_init_with_args          (int *argc,
                                                             char ***argv,
                                                             const char *parameter_string,
                                                             GOptionEntry *entries,
                                                             const char *translation_domain,
                                                             GError **error);

    void                gtk_clutter_get_fg_color            (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_bg_color            (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_text_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_base_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_text_aa_color       (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_light_color         (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_mid_color           (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_dark_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

    enum                ClutterGtkTextureError;
    #define             CLUTTER_GTK_TEXTURE_ERROR
    ClutterActor *      gtk_clutter_texture_new_from_pixbuf (GdkPixbuf *pixbuf);
    ClutterActor *      gtk_clutter_texture_new_from_stock  (GtkWidget *widget,
                                                             const gchar *stock_id,
                                                             GtkIconSize size);
    ClutterActor *      gtk_clutter_texture_new_from_icon_name
                                                            (GtkWidget *widget,
                                                             const gchar *icon_name,
                                                             GtkIconSize size);
    gboolean            gtk_clutter_texture_set_from_pixbuf (ClutterTexture *texture,
                                                             GdkPixbuf *pixbuf,
                                                             GError **error);
    gboolean            gtk_clutter_texture_set_from_stock  (ClutterTexture *texture,
                                                             GtkWidget *widget,
                                                             const gchar *stock_id,
                                                             GtkIconSize size,
                                                             GError **error);
    gboolean            gtk_clutter_texture_set_from_icon_name
                                                            (ClutterTexture *texture,
                                                             GtkWidget *widget,
                                                             const gchar *icon_name,
                                                             GtkIconSize size,
                                                             GError **error);

## Description

In order to properly integrate a Clutter scene into a GTK+ applications a certain degree of state must be retrieved from GTK+ itself.

Clutter-GTK provides API for easing the process of synchronizing colors with the current GTK+ theme and for loading image sources from GdkPixbuf, GTK+ stock items and icon themes.

## Details

### enum ClutterGtkInitError

    typedef enum {
      CLUTTER_INIT_ERROR_LAST = CLUTTER_INIT_ERROR_INTERNAL,

      CLUTTER_INIT_ERROR_GTK  = (CLUTTER_INIT_ERROR_LAST - 1)
    } ClutterGtkInitError;

Extension of the ClutterInitError enumeration for the integration with GTK+

`CLUTTER_INIT_ERROR_LAST` | Placeholder
`CLUTTER_INIT_ERROR_GTK` | Unable to initialize GTK+

Since 0.8

### gtk_clutter_init ()

    ClutterInitError    gtk_clutter_init                    (int *argc,
                                                             char ***argv);

This function should be called instead of `clutter_init()` and `gtk_init()`.

`argc` : | pointer to the arguments count, or `NULL`
`argv` : | pointer to the arguments vector, or `NULL`
Returns : | `CLUTTER_INIT_SUCCESS` on success, a negative integer on failure.

Since 0.8

### gtk_clutter_init_with_args ()

    ClutterInitError    gtk_clutter_init_with_args          (int *argc,
                                                             char ***argv,
                                                             const char *parameter_string,
                                                             GOptionEntry *entries,
                                                             const char *translation_domain,
                                                             GError **error);

This function should be called instead of `clutter_init()` and `gtk_init_with_args()`.

`argc` : | a pointer to the number of command line arguments.
`argv` : | a pointer to the array of command line arguments.
`parameter_string` : | a string which is displayed in the first line of `--help` output, after ``programname` [OPTION...]`
`entries` : | a `NULL`-terminated array of GOptionEntrys describing the options of your program
`translation_domain` : | a translation domain to use for translating the `--help` output for the options in `entries` with `gettext()`, or `NULL`
`error` : | a return location for errors
Returns : | `CLUTTER_INIT_SUCCESS` on success, a negative integer on failure.

Since 0.10

### gtk_clutter_get_fg_color ()

    void                gtk_clutter_get_fg_color            (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the foreground color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_bg_color ()

    void                gtk_clutter_get_bg_color            (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the background color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_text_color ()

    void                gtk_clutter_get_text_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the text color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_base_color ()

    void                gtk_clutter_get_base_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the base color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_text_aa_color ()

    void                gtk_clutter_get_text_aa_color       (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the text-aa color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_light_color ()

    void                gtk_clutter_get_light_color         (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the light color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_mid_color ()

    void                gtk_clutter_get_mid_color           (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the mid color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### gtk_clutter_get_dark_color ()

    void                gtk_clutter_get_dark_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

Retrieves the dark color of `widget` for the given `state` and copies it into `color`.

`widget` : | a GtkWidget
`state` : | a state
`color` : | return location for a ClutterColor

Since 0.8

### enum ClutterGtkTextureError

    typedef enum {
      CLUTTER_GTK_TEXTURE_INVALID_STOCK_ID,

      CLUTTER_GTK_TEXTURE_ERROR_LAST
    } ClutterGtkTextureError;

### CLUTTER_GTK_TEXTURE_ERROR

    #define CLUTTER_GTK_TEXTURE_ERROR gtk_clutter_texture_error_quark ()

### gtk_clutter_texture_new_from_pixbuf ()

    ClutterActor *      gtk_clutter_texture_new_from_pixbuf (GdkPixbuf *pixbuf);

Creates a new ClutterTexture and sets its contents with a copy of `pixbuf`.

`pixbuf` : | a GdkPixbuf
Returns : | the newly created ClutterTexture

Since 0.8

### gtk_clutter_texture_new_from_stock ()

    ClutterActor *      gtk_clutter_texture_new_from_stock  (GtkWidget *widget,
                                                             const gchar *stock_id,
                                                             GtkIconSize size);

Creates a new ClutterTexture and sets its contents using the stock icon `stock_id` as rendered by `widget`.

`widget` : | a GtkWidget
`stock_id` : | the stock id of the icon
`size` : | the size of the icon, or -1
Returns : | the newly created ClutterTexture

Since 0.8

### gtk_clutter_texture_new_from_icon_name ()

    ClutterActor *      gtk_clutter_texture_new_from_icon_name
                                                            (GtkWidget *widget,
                                                             const gchar *icon_name,
                                                             GtkIconSize size);

Creates a new ClutterTexture and sets its contents to be the `icon_name` from the current icon theme.

`widget` : | a GtkWidget or `NULL`
`icon_name` : | the name of the icon
`size` : | the size of the icon, or -1
Returns : | the newly created texture, or `NULL` if `widget` was `NULL` and `icon_name` was not found.

Since 0.8

### gtk_clutter_texture_set_from_pixbuf ()

    gboolean            gtk_clutter_texture_set_from_pixbuf (ClutterTexture *texture,
                                                             GdkPixbuf *pixbuf,
                                                             GError **error);

Sets the contents of `texture` with a copy of `pixbuf`.

`texture` : | a ClutterTexture
`pixbuf` : | a GdkPixbuf
`error` : | a return location for errors
Returns : | `TRUE` on success, `FALSE` on failure.

Since 0.8

### gtk_clutter_texture_set_from_stock ()

    gboolean            gtk_clutter_texture_set_from_stock  (ClutterTexture *texture,
                                                             GtkWidget *widget,
                                                             const gchar *stock_id,
                                                             GtkIconSize size,
                                                             GError **error);

Sets the contents of `texture` using the stock icon `stock_id`, as rendered by `widget`.

`texture` : | a ClutterTexture
`widget` : | a GtkWidget
`stock_id` : | the stock id of the icon
`size` : | the size of the icon, or -1
`error` : | a return location for errors
Returns : | `TRUE` on success, `FALSE` on failure.

Since 0.8

### gtk_clutter_texture_set_from_icon_name ()

    gboolean            gtk_clutter_texture_set_from_icon_name
                                                            (ClutterTexture *texture,
                                                             GtkWidget *widget,
                                                             const gchar *icon_name,
                                                             GtkIconSize size,
                                                             GError **error);

Sets the contents of `texture` using the `icon_name` from the current icon theme.

`texture` : | a ClutterTexture
`widget` : | a GtkWidget or `NULL`
`icon_name` : | the name of the icon
`size` : | the icon size or -1
`error` : | a return location for errors
Returns : | `TRUE` on success, `FALSE` on failure.

Since 0.8