## Utility Functions

Utility Functions — Utility functions for integrating Clutter in GTK+

## Functions

ClutterInitError | gtk_clutter_init ()
ClutterInitError | gtk_clutter_init_with_args ()
GOptionGroup * | gtk_clutter_get_option_group ()

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

## Functions

### gtk_clutter_init ()

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

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

#### Parameters

argc | pointer to the arguments count, or `NULL`. | [inout][allow-none]
argv | pointer to the arguments vector, or `NULL`. | [array length=argc][inout][allow-none]

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

#### Parameters

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][array zero-terminated=1]
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.

[skip]

#### Returns

a GOptionGroup for the commandline arguments recognized by ClutterGtk.

[transfer full]