MetaDisplay: Mutter Reference Manual

## MetaDisplay MetaDisplay — Mutter X display handler |

## Functions

#define | meta_XFree()
int | meta_display_get_xinput_opcode ()
gboolean | meta_display_supports_extended_barriers ()
Display * | meta_display_get_xdisplay ()
MetaCompositor * | meta_display_get_compositor ()
gboolean | meta_display_has_shape ()
MetaWindow * | meta_display_get_focus_window ()
gboolean | meta_display_xwindow_is_a_no_focus_window ()
int | meta_display_get_damage_event_base ()
int | meta_display_get_shape_event_base ()
gboolean | meta_display_xserver_time_is_before ()
guint32 | meta_display_get_last_user_time ()
guint32 | meta_display_get_current_time ()
guint32 | meta_display_get_current_time_roundtrip ()
GList * | meta_display_get_tab_list ()
MetaWindow * | meta_display_get_tab_next ()
MetaWindow * | meta_display_get_tab_current ()
gboolean | meta_display_begin_grab_op ()
void | meta_display_end_grab_op ()
MetaGrabOp | meta_display_get_grab_op ()
guint | meta_display_add_keybinding ()
gboolean | meta_display_remove_keybinding ()
guint | meta_display_get_keybinding_action ()
void | meta_display_set_input_focus_window ()
void | meta_display_focus_the_no_focus_window ()
GSList * | meta_display_sort_windows_by_stacking ()
void | meta_display_add_ignored_crossing_serial ()
void | meta_display_unmanage_screen ()
void | meta_display_clear_mouse_mode ()

## Properties

MetaWindow * | focus-window | Read

## Signals

void | accelerator-activated | Run Last
void | grab-op-begin | Run Last
void | grab-op-end | Run Last
gboolean | modifiers-accelerator-activated | Run Last
void | overlay-key | Run Last
gboolean | restart | Run Last
gboolean | show-resize-popup | Run Last
gboolean | show-restart-message | Run Last
void | window-created | Run Last
void | window-demands-attention | Run Last
void | window-marked-urgent | Run Last

## Types and Values

enum | MetaTabList
enum | MetaTabShowType
| MetaDisplay
| MetaDisplayClass

## Object Hierarchy

        GObject
        ╰── MetaDisplay

## Description

The display is represented as a MetaDisplay struct.

## Functions

### meta_XFree()

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

### meta_display_get_xinput_opcode ()

    int
    meta_display_get_xinput_opcode (MetaDisplay *display);

[skip]

#### Parameters

display | a MetaDisplay |

### meta_display_supports_extended_barriers ()

    gboolean
    meta_display_supports_extended_barriers
                                   (MetaDisplay *display);

#### Parameters

display | a MetaDisplay |

#### Returns

whether pointer barriers can be supported.

When running as an X compositor the X server needs XInput 2 version 2.3. When running as a display server it is supported when running on the native backend.

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

[skip]

#### Parameters

display | a MetaDisplay |

### meta_display_get_compositor ()

    MetaCompositor *
    meta_display_get_compositor (MetaDisplay *display);

[skip]

#### Parameters

display | a MetaDisplay |

### meta_display_has_shape ()

    gboolean
    meta_display_has_shape (MetaDisplay *display);

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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_tab_list ()

    GList *
    meta_display_get_tab_list (MetaDisplay *display,
                               MetaTabList type,
                               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.

#### Parameters

display | a MetaDisplay |
type | type of tab list |
workspace | origin workspace. | [nullable]

#### 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,
                               MetaWorkspace *workspace,
                               MetaWindow *window,
                               gboolean backward);

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

#### Parameters

display | a MetaDisplay |
type | type of tab list |
workspace | origin workspace |
window | starting window. | [nullable]
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,
                                  MetaWorkspace *workspace);

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

#### Parameters

display | a MetaDisplay |
type | type of tab list |
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.

#### Parameters

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.

Use `meta_display_remove_keybinding()` to remove the binding.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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_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.

#### Parameters

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.

#### Parameters

display | a MetaDisplay |

## Types and Values

### enum MetaTabList

#### Members

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

#### Members

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

### MetaDisplay

    typedef struct _MetaDisplay MetaDisplay;

### MetaDisplayClass

    typedef struct _MetaDisplayClass MetaDisplayClass;

## Property Details

### The `“focus-window”` property

      “focus-window”             MetaWindow *

Currently focused window.

Flags: Read

## Signal Details

### The `“accelerator-activated”` signal

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

Flags: Run Last

### The `“grab-op-begin”` signal

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

Flags: Run Last

### The `“grab-op-end”` signal

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

Flags: Run Last

### The `“modifiers-accelerator-activated”` signal

    gboolean
    user_function (MetaDisplay *display,
                   gpointer     user_data)

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

#### Parameters

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.

Flags: Run Last

### The `“overlay-key”` signal

    void
    user_function (MetaDisplay *metadisplay,
                   gpointer     user_data)

Flags: Run Last

### The `“restart”` signal

    gboolean
    user_function (MetaDisplay *display,
                   gpointer     user_data)

The ::restart signal is emitted to indicate that compositor should reexec the process. This is emitted when `meta_restart()` is called, either by Mutter internally or by the embedding compositor. See also ::show-restart-message.

#### Parameters

display | the MetaDisplay instance |
user_data | user data set when the signal handler was connected. |

#### Returns

`FALSE` to indicate that the compositor could not be restarted. When the compositor is restarted, the signal should not return.

Flags: Run Last

### The `“show-resize-popup”` signal

    gboolean
    user_function (MetaDisplay   *metadisplay,
                   gboolean       arg1,
                   MetaRectangle *arg2,
                   gint           arg3,
                   gint           arg4,
                   gpointer       user_data)

Flags: Run Last

### The `“show-restart-message”` signal

    gboolean
    user_function (MetaDisplay *display,
                   gchar       *message,
                   gpointer     user_data)

The ::show-restart-message signal will be emitted to indicate that the compositor should show a message during restart. This is emitted when `meta_restart()` is called, either by Mutter internally or by the embedding compositor. The message should be immediately added to the Clutter stage in its final form - ::restart will be emitted to exit the application and leave the stage contents frozen as soon as the the stage is painted again.

On case of failure to restart, this signal will be emitted again with `NULL` for `message` .

#### Parameters

display | the MetaDisplay instance |
message | The message to display, or `NULL` to clear a previous restart message. | [allow-none]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` means the message was added to the stage; `FALSE` indicates that the compositor did not show the message.

Flags: Run Last

### The `“window-created”` signal

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

Flags: Run Last

### The `“window-demands-attention”` signal

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

Flags: Run Last

### The `“window-marked-urgent”` signal

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

Flags: Run Last