Event handling with GtkClutterEmbed

Due to re-entrancy concerns, you should not use GTK event-related API from within event handling signals emitted by Clutter actors inside a GtkClutterEmbed.

Event-related API, like the GTK drag and drop functions, or the GTK grab ones, cause events to be processed inside the GDK event loop; GtkClutterEmbed and the Clutter event loop may use those events to generate Clutter events, and thus emit signals on ClutterActors. If you use the event-related signals of a ClutterActor to call the GTK API, one of the two event loops will try to re-enter into each other, and either cause a crash or simply block your application.

To avoid this behavior, you can either:

You should also make sure you're not using GTK widgets that call event-related GTK API, like the grab functions in a GtkMenu, in response to Clutter actor events.

Using GtkClutterEmbed as a container

Though GtkClutterEmbed is a GtkContainer subclass, it is not a real GTK+ container; GtkClutterEmbed is required to implement the GtkContainer virtual functions in order to embed a GtkWidget through the GtkClutterActor class. Calling gtk_container_add() on a GtkClutterEmbed will trigger an assertion. It is strongly advised not to override the GtkContainer implementation when subclassing GtkClutterEmbed, to avoid breaking internal state.

gtk_clutter_embed_new ()

GtkWidget *
gtk_clutter_embed_new (void);

Creates a new GtkClutterEmbed widget. This widget can be used to build a scene using Clutter API into a GTK+ application.

gtk_clutter_embed_get_stage ()

ClutterActor *
gtk_clutter_embed_get_stage (GtkClutterEmbed *embed);

Retrieves the ClutterStage from embed . The returned stage can be used to add actors to the Clutter scene.

gtk_clutter_embed_set_use_layout_size ()

void
gtk_clutter_embed_set_use_layout_size (GtkClutterEmbed *embed,
                                       gboolean use_layout_size);

Changes the way embed requests size. If use_layout_size is TRUE, the embed widget will request the size that the LayoutManager reports as the preferred size. This means that a Gtk+ window will automatically get the natural and minimum toplevel window sizes. This is useful when the contents of the clutter stage is similar to a traditional UI.

If use_layout_size is FALSE (which is the default) then embed will not request any size and its up to the embedder to make sure there is some size (by setting a custom size on the widget or a default size on the toplevel. This makes more sense when using the embed as a viewport into a potentially unlimited clutter space.

Since: 1.4

gtk_clutter_embed_get_use_layout_size ()

gboolean
gtk_clutter_embed_get_use_layout_size (GtkClutterEmbed *embed);

Retrieves whether the embedding uses the layout size, see gtk_clutter_embed_set_use_layout_size() for details.

Since: 1.4

struct GtkClutterEmbed

struct GtkClutterEmbed;

A GtkWidget containing the default Clutter stage.

The GtkClutterEmbed structure contains only private data and should be accessed using the provided API.

struct GtkClutterEmbedClass

struct GtkClutterEmbedClass {
};

Base class for GtkClutterEmbed.

The GtkClutterEmbedClass contains only private data.

The “use-layout-size” property

  “use-layout-size”          gboolean

The GtkWidget to be embedded into the GtkClutterActor

Flags: Read / Write / Construct

Default value: FALSE

Since: 1.4