## MetaCompositor

MetaCompositor — Compositor API

## Synopsis

    enum                MetaCompEffect;
                        MetaCompositor;
    MetaCompositor *    meta_compositor_new                 (MetaDisplay *display);
    void                meta_compositor_destroy             (MetaCompositor *compositor);
    void                meta_compositor_manage_screen       (MetaCompositor *compositor,
                                                             MetaScreen *screen);
    void                meta_compositor_unmanage_screen     (MetaCompositor *compositor,
                                                             MetaScreen *screen);
    void                meta_compositor_window_shape_changed
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window);
    gboolean            meta_compositor_process_event       (MetaCompositor *compositor,
                                                             XEvent *event,
                                                             MetaWindow *window);
    gboolean            meta_compositor_filter_keybinding   (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaKeyBinding *binding);
    void                meta_compositor_add_window          (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_remove_window       (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_show_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);
    void                meta_compositor_hide_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);
    void                meta_compositor_switch_workspace    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *from,
                                                             MetaWorkspace *to,
                                                             MetaMotionDirection direction);
    void                meta_compositor_maximize_window     (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);
    void                meta_compositor_unmaximize_window   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);
    void                meta_compositor_window_mapped       (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_window_unmapped     (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_sync_window_geometry
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean did_placement);
    void                meta_compositor_set_updates_frozen  (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean updates_frozen);
    void                meta_compositor_queue_frame_drawn   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean no_delay_frame);
    void                meta_compositor_sync_stack          (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             GList *stack);
    void                meta_compositor_sync_screen_size    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             guint width,
                                                             guint height);
    void                meta_compositor_flash_screen        (MetaCompositor *compositor,
                                                             MetaScreen *screen);
    ClutterActor *      meta_get_stage_for_screen           (MetaScreen *screen);
    Window              meta_get_overlay_window             (MetaScreen *screen);
    GList *             meta_get_window_actors              (MetaScreen *screen);
    ClutterActor *      meta_get_window_group_for_screen    (MetaScreen *screen);
    ClutterActor *      meta_get_top_window_group_for_screen
                                                            (MetaScreen *screen);
    void                meta_disable_unredirect_for_screen  (MetaScreen *screen);
    void                meta_enable_unredirect_for_screen   (MetaScreen *screen);
    void                meta_set_stage_input_region         (MetaScreen *screen,
                                                             XserverRegion region);
    void                meta_empty_stage_input_region       (MetaScreen *screen);

## Description

At a high-level, a window is not-visible or visible. When a window is added (with `meta_compositor_add_window()`) it is not visible. `meta_compositor_show_window()` indicates a transition from not-visible to visible. Some of the reasons for this:

- Window newly created

- Window is unminimized

- Window is moved to the current desktop

- Window was made sticky

`meta_compositor_hide_window()` indicates that the window has transitioned from visible to not-visible. Some reasons include:

- Window was destroyed

- Window is minimized

- Window is moved to a different desktop

- Window no longer sticky.

Note that combinations are possible - a window might have first been minimized and then moved to a different desktop. The 'effect' parameter to `meta_compositor_show_window()` and `meta_compositor_hide_window()` is a hint as to the appropriate effect to show the user and should not be considered to be indicative of a state change.

When the active workspace is changed, `meta_compositor_switch_workspace()` is called first, then `meta_compositor_show_window()` and `meta_compositor_hide_window()` are called individually for each window affected, with an effect of META_COMP_EFFECT_NONE. If hiding windows will affect the switch workspace animation, the compositor needs to delay hiding the windows until the switch workspace animation completes.

`meta_compositor_maximize_window()` and `meta_compositor_unmaximize_window()` are transitions within the visible state. The window is resized __before__ the call, so it may be necessary to readjust the display based on the old_rect to start the animation.

`meta_compositor_window_mapped()` and `meta_compositor_window_unmapped()` are notifications when the toplevel window (frame or client window) is mapped or unmapped. That is, when the result of `meta_window_toplevel_is_mapped()` changes. The main use of this is to drop resources when a window is unmapped. A window will always be mapped before `meta_compositor_show_window()` is called and will not be unmapped until after `meta_compositor_hide_window()` is called. If the live_hidden_windows preference is set, windows will never be unmapped.

### Containers

There's two containers in the stage that are used to place window actors, here are listed in the order in which they are painted:

- window group, accessible with `meta_get_window_group_for_screen()`

- top window group, accessible with `meta_get_top_window_group_for_screen()`

Mutter will place actors representing windows in the window group, except for override-redirect windows (ie. popups and menus) which will be placed in the top window group.

## Details

### enum MetaCompEffect

    typedef enum {
      META_COMP_EFFECT_CREATE,
      META_COMP_EFFECT_UNMINIMIZE,
      META_COMP_EFFECT_DESTROY,
      META_COMP_EFFECT_MINIMIZE,
      META_COMP_EFFECT_NONE
    } MetaCompEffect;

Indicates the appropriate effect to show the user for `meta_compositor_show_window()` and `meta_compositor_hide_window()`

`META_COMP_EFFECT_CREATE` | The window is newly created (also used for a window that was previously on a different workspace and is changed to become visible on the active workspace.)
`META_COMP_EFFECT_UNMINIMIZE` | The window should be shown as unminimizing from its icon geometry.
`META_COMP_EFFECT_DESTROY` | The window is being destroyed
`META_COMP_EFFECT_MINIMIZE` | The window should be shown as minimizing to its icon geometry.
`META_COMP_EFFECT_NONE` | No effect, the window should be shown or hidden immediately.

### MetaCompositor

    typedef struct _MetaCompositor MetaCompositor;

### meta_compositor_new ()

    MetaCompositor *    meta_compositor_new                 (MetaDisplay *display);

### meta_compositor_destroy ()

    void                meta_compositor_destroy             (MetaCompositor *compositor);

### meta_compositor_manage_screen ()

    void                meta_compositor_manage_screen       (MetaCompositor *compositor,
                                                             MetaScreen *screen);

### meta_compositor_unmanage_screen ()

    void                meta_compositor_unmanage_screen     (MetaCompositor *compositor,
                                                             MetaScreen *screen);

### meta_compositor_window_shape_changed ()

    void                meta_compositor_window_shape_changed
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_process_event ()

    gboolean            meta_compositor_process_event       (MetaCompositor *compositor,
                                                             XEvent *event,
                                                             MetaWindow *window);

### meta_compositor_filter_keybinding ()

    gboolean            meta_compositor_filter_keybinding   (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaKeyBinding *binding);

### meta_compositor_add_window ()

    void                meta_compositor_add_window          (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_remove_window ()

    void                meta_compositor_remove_window       (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_show_window ()

    void                meta_compositor_show_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);

### meta_compositor_hide_window ()

    void                meta_compositor_hide_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);

### meta_compositor_switch_workspace ()

    void                meta_compositor_switch_workspace    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *from,
                                                             MetaWorkspace *to,
                                                             MetaMotionDirection direction);

### meta_compositor_maximize_window ()

    void                meta_compositor_maximize_window     (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);

### meta_compositor_unmaximize_window ()

    void                meta_compositor_unmaximize_window   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);

### meta_compositor_window_mapped ()

    void                meta_compositor_window_mapped       (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_window_unmapped ()

    void                meta_compositor_window_unmapped     (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_sync_window_geometry ()

    void                meta_compositor_sync_window_geometry
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean did_placement);

### meta_compositor_set_updates_frozen ()

    void                meta_compositor_set_updates_frozen  (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean updates_frozen);

### meta_compositor_queue_frame_drawn ()

    void                meta_compositor_queue_frame_drawn   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean no_delay_frame);

### meta_compositor_sync_stack ()

    void                meta_compositor_sync_stack          (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             GList *stack);

### meta_compositor_sync_screen_size ()

    void                meta_compositor_sync_screen_size    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             guint width,
                                                             guint height);

### meta_compositor_flash_screen ()

    void                meta_compositor_flash_screen        (MetaCompositor *compositor,
                                                             MetaScreen *screen);

### meta_get_stage_for_screen ()

    ClutterActor *      meta_get_stage_for_screen           (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The ClutterStage for the screen. [transfer none]

### meta_get_overlay_window ()

    Window              meta_get_overlay_window             (MetaScreen *screen);

`screen` : | a MetaScreen

### meta_get_window_actors ()

    GList *             meta_get_window_actors              (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The set of MetaWindowActor on `screen`. [transfer none][element-type Clutter.Actor]

### meta_get_window_group_for_screen ()

    ClutterActor *      meta_get_window_group_for_screen    (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The window group corresponding to `screen`. [transfer none]

### meta_get_top_window_group_for_screen ()

    ClutterActor *      meta_get_top_window_group_for_screen
                                                            (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The top window group corresponding to `screen`. [transfer none]

### meta_disable_unredirect_for_screen ()

    void                meta_disable_unredirect_for_screen  (MetaScreen *screen);

Disables unredirection, can be usefull in situations where having unredirected windows is undesireable like when recording a video.

`screen` : | a MetaScreen

### meta_enable_unredirect_for_screen ()

    void                meta_enable_unredirect_for_screen   (MetaScreen *screen);

Enables unredirection which reduces the overhead for apps like games.

`screen` : | a MetaScreen

### meta_set_stage_input_region ()

    void                meta_set_stage_input_region         (MetaScreen *screen,
                                                             XserverRegion region);

### meta_empty_stage_input_region ()

    void                meta_empty_stage_input_region       (MetaScreen *screen);