Utility Functions

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

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

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

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