## Utility Functions

Utility Functions — Utility functions for integrating Clutter in GTK+

## Synopsis

    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);
    GOptionGroup *      gtk_clutter_get_option_group        (void);

    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_text_aa_color       (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_base_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_light_color         (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_dark_color          (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);
    void                gtk_clutter_get_mid_color           (GtkWidget *widget,
                                                             GtkStateType state,
                                                             ClutterColor *color);

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

### 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`. [inout][allow-none]
`argv` : | pointer to the arguments vector, or `NULL`. [array length=argc][inout length=argc][allow-none length=argc]
Returns : | `CLUTTER_INIT_SUCCESS` on success, a negative integer on failure.

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

### gtk_clutter_get_option_group ()

    GOptionGroup *      gtk_clutter_get_option_group        (void);

Returns a GOptionGroup for the command line arguments recognized by Clutter. You should add this group to your GOptionContext with `g_option_context_add_group()`, if you are using `g_option_context_parse()` to parse your commandline arguments instead of using `gtk_clutter_init()` or `gtk_clutter_init_with_args()`.

You should add this option group to your GOptionContext after the GTK option group created with `gtk_get_option_group()`, and after the clutter option group obtained from `clutter_get_option_group_without_init()`. You should not use `clutter_get_option_group()` together with this function.

You must pass `TRUE` to `gtk_get_option_group()` since gtk-clutter's option group relies on it.

Parsing options using `g_option_context_parse()` with a GOptionContext containing the returned GOptionGroupwith will result in Clutter's and GTK-Clutter's initialisation. That is, the following code:

    1
    2
    3
    4
    5

    g_option_context_add_group (context, gtk_get_option_group (TRUE));
    g_option_context_add_group (context, cogl_get_option_group ());
    g_option_context_add_group (context, clutter_get_option_group_without_init ());
    g_option_context_add_group (context, gtk_clutter_get_option_group ());
    res = g_option_context_parse (context, &argc, &argc, NULL);

is functionally equivalent to:

    1

    gtk_clutter_init (&argc, &argv);

After `g_option_context_parse()` on a GOptionContext containing the the returned GOptionGroup has returned `TRUE`, Clutter and GTK-Clutter are guaranteed to be initialized.

Returns : | a GOptionGroup for the commandline arguments recognized by ClutterGtk. [transfer full]

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

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