Mutter Reference Manual: MetaDisplay

## MetaDisplay MetaDisplay — Mutter X display handler |

## Synopsis

    enum                MetaTabList;
    enum                MetaTabShowType;
    #define             meta_XFree                          (p)
    void                meta_display_get_compositor_version (MetaDisplay *display,
                                                             int *major,
                                                             int *minor);
    int                 meta_display_get_xinput_opcode      (MetaDisplay *display);
    gboolean            meta_display_supports_extended_barriers
                                                            (MetaDisplay *display);
    Display *           meta_display_get_xdisplay           (MetaDisplay *display);
    MetaCompositor *    meta_display_get_compositor         (MetaDisplay *display);
    GSList *            meta_display_get_screens            (MetaDisplay *display);
    gboolean            meta_display_has_shape              (MetaDisplay *display);
    MetaScreen *        meta_display_screen_for_root        (MetaDisplay *display,
                                                             Window xroot);
    MetaWindow *        meta_display_get_focus_window       (MetaDisplay *display);
    gboolean            meta_display_xwindow_is_a_no_focus_window
                                                            (MetaDisplay *display,
                                                             Window xwindow);
    int                 meta_display_get_damage_event_base  (MetaDisplay *display);
    int                 meta_display_get_shape_event_base   (MetaDisplay *display);
    gboolean            meta_display_xserver_time_is_before (MetaDisplay *display,
                                                             guint32 time1,
                                                             guint32 time2);
    guint32             meta_display_get_last_user_time     (MetaDisplay *display);
    guint32             meta_display_get_current_time       (MetaDisplay *display);
    guint32             meta_display_get_current_time_roundtrip
                                                            (MetaDisplay *display);
    unsigned int        meta_display_get_ignored_modifier_mask
                                                            (MetaDisplay *display);
    GList *             meta_display_get_tab_list           (MetaDisplay *display,
                                                             MetaTabList type,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *workspace);
    MetaWindow *        meta_display_get_tab_next           (MetaDisplay *display,
                                                             MetaTabList type,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *workspace,
                                                             MetaWindow *window,
                                                             gboolean backward);
    MetaWindow *        meta_display_get_tab_current        (MetaDisplay *display,
                                                             MetaTabList type,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *workspace);
    gboolean            meta_display_begin_grab_op          (MetaDisplay *display,
                                                             MetaScreen *screen,
                                                             MetaWindow *window,
                                                             MetaGrabOp op,
                                                             gboolean pointer_already_grabbed,
                                                             gboolean frame_action,
                                                             int button,
                                                             gulong modmask,
                                                             guint32 timestamp,
                                                             int root_x,
                                                             int root_y);
    void                meta_display_end_grab_op            (MetaDisplay *display,
                                                             guint32 timestamp);
    MetaGrabOp          meta_display_get_grab_op            (MetaDisplay *display);
    guint               meta_display_add_keybinding         (MetaDisplay *display,
                                                             const char *name,
                                                             GSettings *settings,
                                                             MetaKeyBindingFlags flags,
                                                             MetaKeyHandlerFunc handler,
                                                             gpointer user_data,
                                                             GDestroyNotify free_data);
    gboolean            meta_display_remove_keybinding      (MetaDisplay *display,
                                                             const char *name);
    guint               meta_display_get_keybinding_action  (MetaDisplay *display,
                                                             unsigned int keycode,
                                                             unsigned long  mask);
    void                meta_display_set_input_focus_window (MetaDisplay *display,
                                                             MetaWindow *window,
                                                             gboolean focus_frame,
                                                             guint32 timestamp);
    void                meta_display_focus_the_no_focus_window
                                                            (MetaDisplay *display,
                                                             MetaScreen *screen,
                                                             guint32 timestamp);
    GSList *            meta_display_sort_windows_by_stacking
                                                            (MetaDisplay *display,
                                                             GSList *windows);
    Window              meta_display_get_leader_window      (MetaDisplay *display);
    void                meta_display_add_ignored_crossing_serial
                                                            (MetaDisplay *display,
                                                             unsigned long  serial);
    void                meta_display_unmanage_screen        (MetaDisplay *display,
                                                             MetaScreen *screen,
                                                             guint32 timestamp);
    void                meta_display_clear_mouse_mode       (MetaDisplay *display);
                        MetaDisplay;
                        MetaDisplayClass;

## Object Hierarchy

      GObject
       +----MetaDisplay

## Properties

      "focus-window"             MetaWindow*           : Read

## Signals

      "accelerator-activated"                          : Run Last
      "grab-op-begin"                                  : Run Last
      "grab-op-end"                                    : Run Last
      "modifiers-accelerator-activated"                : Run Last
      "overlay-key"                                    : Run Last
      "window-created"                                 : Run Last
      "window-demands-attention"                       : Run Last
      "window-marked-urgent"                           : Run Last

## Description

The display is represented as a MetaDisplay struct.

## Details

### enum MetaTabList

    typedef enum {
      META_TAB_LIST_NORMAL,
      META_TAB_LIST_DOCKS,
      META_TAB_LIST_GROUP,
      META_TAB_LIST_NORMAL_ALL
    } MetaTabList;

`META_TAB_LIST_NORMAL` | Normal windows
`META_TAB_LIST_DOCKS` | Dock windows
`META_TAB_LIST_GROUP` | Groups
`META_TAB_LIST_NORMAL_ALL` | All windows

### enum MetaTabShowType

    typedef enum {
      META_TAB_SHOW_ICON,      /* Alt-Tab mode */
      META_TAB_SHOW_INSTANTLY  /* Alt-Esc mode */
    } MetaTabShowType;

`META_TAB_SHOW_ICON` | Show icon (Alt-Tab mode)
`META_TAB_SHOW_INSTANTLY` | Show instantly (Alt-Esc mode)

### meta_XFree()

    #define meta_XFree(p) do { if ((p)) XFree ((p)); } while (0)

### meta_display_get_compositor_version ()

    void                meta_display_get_compositor_version (MetaDisplay *display,
                                                             int *major,
                                                             int *minor);

### meta_display_get_xinput_opcode ()

    int                 meta_display_get_xinput_opcode      (MetaDisplay *display);

`display` : | a MetaDisplay

### meta_display_supports_extended_barriers ()

    gboolean            meta_display_supports_extended_barriers
                                                            (MetaDisplay *display);

`display` : | a MetaDisplay
Returns : | whether the X server supports extended barrier features as defined in version 2.3 of the XInput 2 specification. Clients should use this method to determine whether their interfaces should depend on new barrier features.

### meta_display_get_xdisplay ()

    Display *           meta_display_get_xdisplay           (MetaDisplay *display);

`display` : | a MetaDisplay

### meta_display_get_compositor ()

    MetaCompositor *    meta_display_get_compositor         (MetaDisplay *display);

`display` : | a MetaDisplay

### meta_display_get_screens ()

    GSList *            meta_display_get_screens            (MetaDisplay *display);

`display` : | a MetaDisplay
Returns : | Screens for this display. [transfer none][element-type Meta.Screen]

### meta_display_has_shape ()

    gboolean            meta_display_has_shape              (MetaDisplay *display);

### meta_display_screen_for_root ()

    MetaScreen *        meta_display_screen_for_root        (MetaDisplay *display,
                                                             Window xroot);

Return the MetaScreen corresponding to a specified X root window ID.

`display` : | a MetaDisplay
`xroot` : | a X window
Returns : | the screen for the specified root window ID, or `NULL`. [transfer none]

### meta_display_get_focus_window ()

    MetaWindow *        meta_display_get_focus_window       (MetaDisplay *display);

Get our best guess as to the "currently" focused window (that is, the window that we expect will be focused at the point when the X server processes our next request).

`display` : | a MetaDisplay
Returns : | The current focus window. [transfer none]

### meta_display_xwindow_is_a_no_focus_window ()

    gboolean            meta_display_xwindow_is_a_no_focus_window
                                                            (MetaDisplay *display,
                                                             Window xwindow);

`display` : | A MetaDisplay
`xwindow` : | An X11 window
Returns : | `TRUE` iff window is one of mutter's internal "no focus" windows (there is one per screen) which will have the focus when there is no actual client window focused.

### meta_display_get_damage_event_base ()

    int                 meta_display_get_damage_event_base  (MetaDisplay *display);

### meta_display_get_shape_event_base ()

    int                 meta_display_get_shape_event_base   (MetaDisplay *display);

### meta_display_xserver_time_is_before ()

    gboolean            meta_display_xserver_time_is_before (MetaDisplay *display,
                                                             guint32 time1,
                                                             guint32 time2);

Xserver time can wraparound, thus comparing two timestamps needs to take this into account. If no wraparound has occurred, this is equivalent to time1 < time2 Otherwise, we need to account for the fact that wraparound can occur and the fact that a timestamp of 0 must be special-cased since it means "older than anything else".

Note that this is NOT an equivalent for time1 <= time2; if that's what you need then you'll need to swap the order of the arguments and negate the result.

`display` : | a MetaDisplay
`time1` : | An event timestamp
`time2` : | An event timestamp

### meta_display_get_last_user_time ()

    guint32             meta_display_get_last_user_time     (MetaDisplay *display);

`display` : | a MetaDisplay
Returns : | Timestamp of the last user interaction event with a window

### meta_display_get_current_time ()

    guint32             meta_display_get_current_time       (MetaDisplay *display);

### meta_display_get_current_time_roundtrip ()

    guint32             meta_display_get_current_time_roundtrip
                                                            (MetaDisplay *display);

### meta_display_get_ignored_modifier_mask ()

    unsigned int        meta_display_get_ignored_modifier_mask
                                                            (MetaDisplay *display);

`display` : | a MetaDisplay
Returns : | a mask of modifiers that should be ignored when matching keybindings to events

### meta_display_get_tab_list ()

    GList *             meta_display_get_tab_list           (MetaDisplay *display,
                                                             MetaTabList type,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *workspace);

Determine the list of windows that should be displayed for Alt-TAB functionality. The windows are returned in most recently used order. If `workspace` is not `NULL`, the list only conains windows that are on `workspace` or have the demands-attention hint set; otherwise it contains all windows on `screen`.

`display` : | a MetaDisplay
`type` : | type of tab list
`screen` : | a MetaScreen
`workspace` : | origin workspace. [allow-none]
Returns : | List of windows. [transfer container][element-type Meta.Window]

### meta_display_get_tab_next ()

    MetaWindow *        meta_display_get_tab_next           (MetaDisplay *display,
                                                             MetaTabList type,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *workspace,
                                                             MetaWindow *window,
                                                             gboolean backward);

Determine the next window that should be displayed for Alt-TAB functionality.

`display` : | a MetaDisplay
`type` : | type of tab list
`screen` : | a MetaScreen
`workspace` : | origin workspace
`window` : | starting window. [allow-none]
`backward` : | If `TRUE`, look for the previous window.
Returns : | Next window. [transfer none]

### meta_display_get_tab_current ()

    MetaWindow *        meta_display_get_tab_current        (MetaDisplay *display,
                                                             MetaTabList type,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *workspace);

Determine the active window that should be displayed for Alt-TAB.

`display` : | a MetaDisplay
`type` : | type of tab list
`screen` : | a MetaScreen
`workspace` : | origin workspace
Returns : | Current window. [transfer none]

### meta_display_begin_grab_op ()

    gboolean            meta_display_begin_grab_op          (MetaDisplay *display,
                                                             MetaScreen *screen,
                                                             MetaWindow *window,
                                                             MetaGrabOp op,
                                                             gboolean pointer_already_grabbed,
                                                             gboolean frame_action,
                                                             int button,
                                                             gulong modmask,
                                                             guint32 timestamp,
                                                             int root_x,
                                                             int root_y);

### meta_display_end_grab_op ()

    void                meta_display_end_grab_op            (MetaDisplay *display,
                                                             guint32 timestamp);

### meta_display_get_grab_op ()

    MetaGrabOp          meta_display_get_grab_op            (MetaDisplay *display);

Gets the current grab operation, if any.

`display` : | The MetaDisplay that the window is on
Returns : | the current grab operation, or `META_GRAB_OP_NONE` if Mutter doesn't currently have a grab. `META_GRAB_OP_COMPOSITOR` will be returned if a compositor-plugin modal operation is in effect (See `mutter_begin_modal_for_plugin()`)

### meta_display_add_keybinding ()

    guint               meta_display_add_keybinding         (MetaDisplay *display,
                                                             const char *name,
                                                             GSettings *settings,
                                                             MetaKeyBindingFlags flags,
                                                             MetaKeyHandlerFunc handler,
                                                             gpointer user_data,
                                                             GDestroyNotify free_data);

Add a keybinding at runtime. The key `name` in `schema` needs to be of type `G_VARIANT_TYPE_STRING_ARRAY`, with each string describing a keybinding in the form of "<Control>a" or "<Shift><Alt>F1". The parser is fairly liberal and allows lower or upper case, and also abbreviations such as "<Ctl>" and "<Ctrl>". If the key is set to the empty list or a list with a single element of either "" or "disabled", the keybinding is disabled. If `META_KEY_BINDING_REVERSES` is specified in `flags`, the binding may be reversed by holding down the "shift" key; therefore, "<Shift>" cannot be one of the keys used. `handler` is expected to check for the "shift" modifier in this case and reverse its action.

Use `meta_display_remove_keybinding()` to remove the binding.

`display` : | a MetaDisplay
`name` : | the binding's name
`settings` : | the GSettings object where `name` is stored
`flags` : | flags to specify binding details
`handler` : | function to run when the keybinding is invoked
`user_data` : | the data to pass to `handler`
`free_data` : | function to free `user_data`
Returns : | the corresponding keybinding action if the keybinding was added successfully, otherwise `META_KEYBINDING_ACTION_NONE`

### meta_display_remove_keybinding ()

    gboolean            meta_display_remove_keybinding      (MetaDisplay *display,
                                                             const char *name);

Remove keybinding `name`; the function will fail if `name` is not a known keybinding or has not been added with `meta_display_add_keybinding()`.

`display` : | the MetaDisplay
`name` : | name of the keybinding to remove
Returns : | `TRUE` if the binding has been removed sucessfully, otherwise `FALSE`

### meta_display_get_keybinding_action ()

    guint               meta_display_get_keybinding_action  (MetaDisplay *display,
                                                             unsigned int keycode,
                                                             unsigned long  mask);

Get the keybinding action bound to `keycode`. Builtin keybindings have a fixed associated MetaKeyBindingAction, for bindings added dynamically the function will return the keybinding action `meta_display_add_keybinding()` returns on registration.

`display` : | A MetaDisplay
`keycode` : | Raw keycode
`mask` : | Event mask
Returns : | The action that should be taken for the given key, or `META_KEYBINDING_ACTION_NONE`.

### meta_display_set_input_focus_window ()

    void                meta_display_set_input_focus_window (MetaDisplay *display,
                                                             MetaWindow *window,
                                                             gboolean focus_frame,
                                                             guint32 timestamp);

### meta_display_focus_the_no_focus_window ()

    void                meta_display_focus_the_no_focus_window
                                                            (MetaDisplay *display,
                                                             MetaScreen *screen,
                                                             guint32 timestamp);

### meta_display_sort_windows_by_stacking ()

    GSList *            meta_display_sort_windows_by_stacking
                                                            (MetaDisplay *display,
                                                             GSList *windows);

Sorts a set of windows according to their current stacking order. If windows from multiple screens are present in the set of input windows, then all the windows on screen 0 are sorted below all the windows on screen 1, and so forth. Since the stacking order of override-redirect windows isn't controlled by Metacity, if override-redirect windows are in the input, the result may not correspond to the actual stacking order in the X server.

An example of using this would be to sort the list of transient dialogs for a window into their current stacking order.

`display` : | a MetaDisplay
`windows` : | Set of windows. [element-type MetaWindow]
Returns : | Input windows sorted by stacking order, from lowest to highest. [transfer container][element-type MetaWindow]

### meta_display_get_leader_window ()

    Window              meta_display_get_leader_window      (MetaDisplay *display);

Returns the window manager's leader window (as defined by the _NET_SUPPORTING_WM_CHECK mechanism of EWMH). For use by plugins that wish to attach additional custom properties to this window.

`display` : | a MetaDisplay
Returns : | xid of the leader window. [transfer none]

### meta_display_add_ignored_crossing_serial ()

    void                meta_display_add_ignored_crossing_serial
                                                            (MetaDisplay *display,
                                                             unsigned long  serial);

Save the specified serial and ignore crossing events with that serial for the purpose of focus-follows-mouse. This can be used for certain changes to the window hierarchy that we don't want to change the focus window, even if they cause the pointer to end up in a new window.

`display` : | a MetaDisplay
`serial` : | the serial to ignore

### meta_display_unmanage_screen ()

    void                meta_display_unmanage_screen        (MetaDisplay *display,
                                                             MetaScreen *screen,
                                                             guint32 timestamp);

### meta_display_clear_mouse_mode ()

    void                meta_display_clear_mouse_mode       (MetaDisplay *display);

Sets the mouse-mode flag to `FALSE`, which means that motion events are no longer ignored in mouse or sloppy focus. This is an internal function. It should be used only for reimplementing keybindings, and only in a manner compatible with core code.

`display` : | a MetaDisplay

### MetaDisplay

    typedef struct _MetaDisplay MetaDisplay;

### MetaDisplayClass

    typedef struct _MetaDisplayClass MetaDisplayClass;

## Property Details

### The `"focus-window"` property

      "focus-window"             MetaWindow*           : Read

Currently focused window.

## Signal Details

### The `"accelerator-activated"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            guint        arg1,
                                                            guint        arg2,
                                                            guint        arg3,
                                                            gpointer     user_data)        : Run Last

### The `"grab-op-begin"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            MetaScreen  *arg1,
                                                            MetaWindow  *arg2,
                                                            MetaGrabOp   arg3,
                                                            gpointer     user_data)        : Run Last

### The `"grab-op-end"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            MetaScreen  *arg1,
                                                            MetaWindow  *arg2,
                                                            MetaGrabOp   arg3,
                                                            gpointer     user_data)        : Run Last

### The `"modifiers-accelerator-activated"` signal

    gboolean            user_function                      (MetaDisplay *display,
                                                            gpointer     user_data)      : Run Last

The ::modifiers-accelerator-activated signal will be emitted when a special modifiers-only keybinding is activated.

`display` : | the MetaDisplay instance
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` means that the keyboard device should remain frozen and `FALSE` for the default behavior of unfreezing the keyboard.

### The `"overlay-key"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            gpointer     user_data)        : Run Last

### The `"window-created"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            MetaWindow  *arg1,
                                                            gpointer     user_data)        : Run Last

### The `"window-demands-attention"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            MetaWindow  *arg1,
                                                            gpointer     user_data)        : Run Last

### The `"window-marked-urgent"` signal

    void                user_function                      (MetaDisplay *metadisplay,
                                                            MetaWindow  *arg1,
                                                            gpointer     user_data)        : Run Last