X11 Specific Support

X11 Specific Support — X11 specific API

Synopsis

void                clutter_x11_set_display             (Display *xdpy);
void                clutter_x11_disable_event_retrieval (void);
gboolean            clutter_x11_has_event_retrieval     (void);
ClutterStage *      clutter_x11_get_stage_from_window   (Window win);
ClutterX11FilterReturn clutter_x11_handle_event         (XEvent *xevent);
Display *           clutter_x11_get_default_display     (void);
int                 clutter_x11_get_default_screen      (void);
Window              clutter_x11_get_root_window         (void);
XVisualInfo *       clutter_x11_get_stage_visual        (ClutterStage *stage);
Window              clutter_x11_get_stage_window        (ClutterStage *stage);
gboolean            clutter_x11_set_stage_foreign       (ClutterStage *stage,
                                                         Window xwindow);
void                clutter_x11_trap_x_errors           (void);
gint                clutter_x11_untrap_x_errors         (void);
gboolean            clutter_x11_has_composite_extension (void);
Time                clutter_x11_get_current_event_time  (void);
void                clutter_x11_set_use_argb_visual     (gboolean use_argb);
gboolean            clutter_x11_get_use_argb_visual     (void);
XVisualInfo *       clutter_x11_get_visual_info         (void);

ClutterX11FilterReturn (*ClutterX11FilterFunc)          (XEvent *xev,
                                                         ClutterEvent *cev,
                                                         gpointer data);
enum                ClutterX11FilterReturn;
void                clutter_x11_add_filter              (ClutterX11FilterFunc func,
                                                         gpointer data);
void                clutter_x11_remove_filter           (ClutterX11FilterFunc func,
                                                         gpointer data);

const GSList *      clutter_x11_get_input_devices       (void);
gboolean            clutter_x11_has_xinput              (void);
void                clutter_x11_enable_xinput           (void);
gint                clutter_x11_event_get_key_group     (const ClutterEvent *event);
guint               clutter_x11_event_sequence_get_touch_detail
                                                        (const ClutterEventSequence *sequence);

Description

The X11 backend for Clutter provides some specific API, allowing integration with the Xlibs API for embedding and manipulating the stage window, or for trapping X errors.

The ClutterX11 API is available since Clutter 0.6

Details

clutter_x11_set_display ()

void                clutter_x11_set_display             (Display *xdpy);

Sets the display connection Clutter should use; must be called before clutter_init(), clutter_init_with_args() or other functions pertaining Clutter's initialization process.

If you are parsing the command line arguments by retrieving Clutter's GOptionGroup with clutter_get_option_group() and calling g_option_context_parse() yourself, you should also call clutter_x11_set_display() before g_option_context_parse().

xdpy :

 pointer to a X display connection.

Since 0.8

clutter_x11_disable_event_retrieval ()

void                clutter_x11_disable_event_retrieval (void);

Disables the internal polling of X11 events in the main loop.

Libraries or applications calling this function will be responsible of polling all X11 events.

You also must call clutter_x11_handle_event() to let Clutter process events and maintain its internal state.

Warning

This function can only be called before calling clutter_init().

Note

Even with event handling disabled, Clutter will still select all the events required to maintain its internal state on the stage Window; compositors using Clutter and input regions to pass events through to application windows should not rely on an empty input region, and should instead clear it themselves explicitly using the XFixes extension.

This function should not be normally used by applications.

Since 0.8

clutter_x11_has_event_retrieval ()

gboolean            clutter_x11_has_event_retrieval     (void);

Queries the X11 backend to check if event collection has been disabled.

Returns :

 TRUE if event retrival has been disabled. FALSE otherwise.

Since 0.8

clutter_x11_get_stage_from_window ()

ClutterStage *      clutter_x11_get_stage_from_window   (Window win);

Gets the stage for a particular X window.

win :

 an X Window ID

Returns :

 A ClutterStage, or% NULL if a stage does not exist for the window. [transfer none]

Since 0.8

clutter_x11_handle_event ()

ClutterX11FilterReturn clutter_x11_handle_event         (XEvent *xevent);

This function processes a single X event; it can be used to hook into external X11 event processing (for example, a GDK filter function).

If clutter_x11_disable_event_retrieval() has been called, you must let this function process events to update Clutter's internal state.

xevent :

 pointer to XEvent structure

Returns :

 ClutterX11FilterReturn. CLUTTER_X11_FILTER_REMOVE indicates that Clutter has internally handled the event and the caller should do no further processing. CLUTTER_X11_FILTER_CONTINUE indicates that Clutter is either not interested in the event, or has used the event to update internal state without taking any exclusive action. CLUTTER_X11_FILTER_TRANSLATE will not occur.

Since 0.8

clutter_x11_get_default_display ()

Display *           clutter_x11_get_default_display     (void);

Retrieves the pointer to the default display.

Returns :

 the default display. [transfer none]

Since 0.6

clutter_x11_get_default_screen ()

int                 clutter_x11_get_default_screen      (void);

Gets the number of the default X Screen object.

Returns :

 the number of the default screen

Since 0.6

clutter_x11_get_root_window ()

Window              clutter_x11_get_root_window         (void);

Retrieves the root window.

Returns :

 the id of the root window

Since 0.6

clutter_x11_get_stage_visual ()

XVisualInfo *       clutter_x11_get_stage_visual        (ClutterStage *stage);

Warning

clutter_x11_get_stage_visual has been deprecated since version 1.2 and should not be used in newly-written code. Use clutter_x11_get_visual_info() instead

Returns an XVisualInfo suitable for creating a foreign window for the given stage. NOTE: It doesn't do as the name may suggest, which is return the XVisualInfo that was used to create an existing window for the given stage.

XXX: It might be best to deprecate this function and replace with something along the lines of clutter_backend_x11_get_foreign_visual() or perhaps clutter_stage_x11_get_foreign_visual()

stage :

 a ClutterStage

Returns :

 An XVisualInfo suitable for creating a foreign stage. Use XFree() to free the returned value instead. [transfer full]

Since 0.4

clutter_x11_get_stage_window ()

Window              clutter_x11_get_stage_window        (ClutterStage *stage);

Gets the stages X Window.

stage :

 a ClutterStage

Returns :

 An XID for the stage window.

Since 0.4

clutter_x11_set_stage_foreign ()

gboolean            clutter_x11_set_stage_foreign       (ClutterStage *stage,
                                                         Window xwindow);

Target the ClutterStage to use an existing external X Window

stage :

 a ClutterStage

xwindow :

 an existing X Window id

Returns :

 TRUE if foreign window is valid

Since 0.4

clutter_x11_trap_x_errors ()

void                clutter_x11_trap_x_errors           (void);

Traps every X error until clutter_x11_untrap_x_errors() is called.

Since 0.6

clutter_x11_untrap_x_errors ()

gint                clutter_x11_untrap_x_errors         (void);

Removes the X error trap and returns the current status.

Returns :

 the trapped error code, or 0 for success

Since 0.4

clutter_x11_has_composite_extension ()

gboolean            clutter_x11_has_composite_extension (void);

Retrieves whether Clutter is running on an X11 server with the XComposite extension

Returns :

 TRUE if the XComposite extension is available

clutter_x11_get_current_event_time ()

Time                clutter_x11_get_current_event_time  (void);

Retrieves the timestamp of the last X11 event processed by Clutter. This might be different from the timestamp returned by clutter_get_current_event_time(), as Clutter may synthesize or throttle events.

Returns :

 a timestamp, in milliseconds

Since 1.0

clutter_x11_set_use_argb_visual ()

void                clutter_x11_set_use_argb_visual     (gboolean use_argb);

Sets whether the Clutter X11 backend should request ARGB visuals by default or not.

By default, Clutter requests RGB visuals.

Note

If no ARGB visuals are found, the X11 backend will fall back to requesting a RGB visual instead.

ARGB visuals are required for the "use-alpha" property to work.

Note

This function can only be called once, and before clutter_init() is called.

use_argb :

 TRUE if ARGB visuals should be requested by default

Since 1.2

clutter_x11_get_use_argb_visual ()

gboolean            clutter_x11_get_use_argb_visual     (void);

Retrieves whether the Clutter X11 backend is using ARGB visuals by default

Returns :

 TRUE if ARGB visuals are queried by default

Since 1.2

clutter_x11_get_visual_info ()

XVisualInfo *       clutter_x11_get_visual_info         (void);

Retrieves the XVisualInfo used by the Clutter X11 backend.

Returns :

 a XVisualInfo, or None. The returned value should be freed using XFree() when done. [transfer full]

Since 1.2

ClutterX11FilterFunc ()

ClutterX11FilterReturn (*ClutterX11FilterFunc)          (XEvent *xev,
                                                         ClutterEvent *cev,
                                                         gpointer data);

Filter function for X11 native events.

xev :

 Native X11 event structure

cev :

 Clutter event structure

data :

 user data passed to the filter function

Returns :

 the result of the filtering

Since 0.6

enum ClutterX11FilterReturn

typedef enum {
  CLUTTER_X11_FILTER_CONTINUE,
  CLUTTER_X11_FILTER_TRANSLATE,
  CLUTTER_X11_FILTER_REMOVE
} ClutterX11FilterReturn;

Return values for the ClutterX11FilterFunc function.

CLUTTER_X11_FILTER_CONTINUE

 The event was not handled, continues the processing

CLUTTER_X11_FILTER_TRANSLATE

 Native event translated into a Clutter event, stops the processing

CLUTTER_X11_FILTER_REMOVE

 Remove the event, stops the processing

Since 0.6

clutter_x11_add_filter ()

void                clutter_x11_add_filter              (ClutterX11FilterFunc func,
                                                         gpointer data);

Adds an event filter function.

func :

 a filter function

data :

 user data to be passed to the filter function, or NULL

Since 0.6

clutter_x11_remove_filter ()

void                clutter_x11_remove_filter           (ClutterX11FilterFunc func,
                                                         gpointer data);

Removes the given filter function.

func :

 a filter function

data :

 user data to be passed to the filter function, or NULL

Since 0.6

clutter_x11_get_input_devices ()

const GSList *      clutter_x11_get_input_devices       (void);

Warning

clutter_x11_get_input_devices has been deprecated since version 1.2 and should not be used in newly-written code. Use clutter_device_manager_peek_devices() instead

Retrieves a pointer to the list of input devices

Returns :

 a pointer to the internal list of input devices; the returned list is owned by Clutter and should not be modified or freed. [transfer none][element-type Clutter.InputDevice]

Since 0.8

clutter_x11_has_xinput ()

gboolean            clutter_x11_has_xinput              (void);

Gets whether Clutter has XInput support.

Returns :

 TRUE if Clutter was compiled with XInput support and XInput support is available at run time.

Since 0.8

clutter_x11_enable_xinput ()

void                clutter_x11_enable_xinput           (void);

Warning

clutter_x11_enable_xinput has been deprecated since version 1.14 and should not be used in newly-written code. This function does not do anything; XInput support is enabled by default in Clutter. Use the CLUTTER_DISABLE_XINPUT environment variable to disable XInput support and use Xlib core events instead.

Enables the use of the XInput extension if present on connected XServer and support built into Clutter. XInput allows for multiple pointing devices to be used.

This function must be called before clutter_init().

Since XInput might not be supported by the X server, you might want to use clutter_x11_has_xinput() to see if support was enabled.

Since 0.8

clutter_x11_event_get_key_group ()

gint                clutter_x11_event_get_key_group     (const ClutterEvent *event);

Retrieves the group for the modifiers set in event

event :

 a ClutterEvent of type CLUTTER_KEY_PRESS or CLUTTER_KEY_RELEASE

Returns :

 the group id

Since 1.4

clutter_x11_event_sequence_get_touch_detail ()

guint               clutter_x11_event_sequence_get_touch_detail
                                                        (const ClutterEventSequence *sequence);

Retrieves the touch detail froma ClutterEventSequence.

sequence :

 a ClutterEventSequence

Returns :

 the touch detail

Since 1.12

Generated by GTK-Doc V1.19.1