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

                        ClutterX11TexturePixmap;
                        ClutterX11TexturePixmapClass;
    ClutterActor *      clutter_x11_texture_pixmap_new      (void);
    ClutterActor *      clutter_x11_texture_pixmap_new_with_pixmap
                                                            (Pixmap pixmap);
    ClutterActor *      clutter_x11_texture_pixmap_new_with_window
                                                            (Window window);
    void                clutter_x11_texture_pixmap_set_pixmap
                                                            (ClutterX11TexturePixmap *texture,
                                                             Pixmap pixmap);
    void                clutter_x11_texture_pixmap_set_window
                                                            (ClutterX11TexturePixmap *texture,
                                                             Window window,
                                                             gboolean automatic);
    void                clutter_x11_texture_pixmap_sync_window
                                                            (ClutterX11TexturePixmap *texture);
    void                clutter_x11_texture_pixmap_update_area
                                                            (ClutterX11TexturePixmap *texture,
                                                             gint x,
                                                             gint y,
                                                             gint width,
                                                             gint height);
    void                clutter_x11_texture_pixmap_set_automatic
                                                            (ClutterX11TexturePixmap *texture,
                                                             gboolean setting);

## 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 retrieval of X events in the main loop. Use to create event-less canvas or in conjunction with clutter_x11_handle_event.

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

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 : | The stage or NULL if a stage does not exist for the window.

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 X event retrieval (for example that done by GDK).

`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

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

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

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

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

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

### ClutterX11TexturePixmap

    typedef struct {
    } ClutterX11TexturePixmap;

The ClutterX11TexturePixmap structure contains only private data

Since 0.8

### ClutterX11TexturePixmapClass

    typedef struct {
      void                  (*update_area)    (ClutterX11TexturePixmap *texture,
                                               gint                     x,
                                               gint                     y,
                                               gint                     width,
                                               gint                     height);
    } ClutterX11TexturePixmapClass;

The ClutterX11TexturePixmapClass structure contains only private data

`update_area` () | virtual function for updating the area of the texture

Since 0.8

### clutter_x11_texture_pixmap_new ()

    ClutterActor *      clutter_x11_texture_pixmap_new      (void);

Creates a new ClutterX11TexturePixmap which can be used to display the contents of an X11 Pixmap inside a Clutter scene graph

Returns : | A new ClutterX11TexturePixmap

Since 0.8

### clutter_x11_texture_pixmap_new_with_pixmap ()

    ClutterActor *      clutter_x11_texture_pixmap_new_with_pixmap
                                                            (Pixmap pixmap);

Creates a new ClutterX11TexturePixmap for `pixmap`

`pixmap` : | the X Pixmap to which this texture should be bound
Returns : | A new ClutterX11TexturePixmap bound to the given X Pixmap

Since 0.8

### clutter_x11_texture_pixmap_new_with_window ()

    ClutterActor *      clutter_x11_texture_pixmap_new_with_window
                                                            (Window window);

Creates a new ClutterX11TexturePixmap for `window`

`window` : | the X window to which this texture should be bound
Returns : | A new ClutterX11TexturePixmap bound to the given X window.

Since 0.8

### clutter_x11_texture_pixmap_set_pixmap ()

    void                clutter_x11_texture_pixmap_set_pixmap
                                                            (ClutterX11TexturePixmap *texture,
                                                             Pixmap pixmap);

Sets the X Pixmap to which the texture should be bound.

`texture` : | the texture to bind
`pixmap` : | the X Pixmap to which the texture should be bound

Since 0.8

### clutter_x11_texture_pixmap_set_window ()

    void                clutter_x11_texture_pixmap_set_window
                                                            (ClutterX11TexturePixmap *texture,
                                                             Window window,
                                                             gboolean automatic);

Sets up a suitable pixmap for the window, using the composite and damage extensions if possible, and then calls `clutter_x11_texture_pixmap_set_pixmap()`.

If you want to display a window in a ClutterTexture, you probably want this function, or its older sister, `clutter_glx_texture_pixmap_set_window()`

`texture` : | the texture to bind
`window` : | the X window to which the texture should be bound
`automatic` : | `TRUE` for automatic window updates, `FALSE` for manual.

Since 0.8

### clutter_x11_texture_pixmap_sync_window ()

    void                clutter_x11_texture_pixmap_sync_window
                                                            (ClutterX11TexturePixmap *texture);

Resets the texture's pixmap from its window, perhaps in response to the pixmap's invalidation as the window changed size.

`texture` : | the texture to bind

Since 0.8

### clutter_x11_texture_pixmap_update_area ()

    void                clutter_x11_texture_pixmap_update_area
                                                            (ClutterX11TexturePixmap *texture,
                                                             gint x,
                                                             gint y,
                                                             gint width,
                                                             gint height);

Performs the actual binding of texture to the current content of the pixmap. Can be called to update the texture if the pixmap content has changed.

`texture` : | The texture whose content shall be updated.
`x` : | the X coordinate of the area to update
`y` : | the Y coordinate of the area to update
`width` : | the width of the area to update
`height` : | the height of the area to update

Since 0.8

### clutter_x11_texture_pixmap_set_automatic ()

    void                clutter_x11_texture_pixmap_set_automatic
                                                            (ClutterX11TexturePixmap *texture,
                                                             gboolean setting);

Enables or disables the automatic updates ot `texture` in case the backing pixmap or window is damaged

`texture` : | a ClutterX11TexturePixmap
`setting` : | `TRUE` to enable automatic updates

Since 0.8