MetaDisplay: Muffin Reference Manual

## MetaDisplay MetaDisplay — Handles operations on an X display. |

## Functions

#define | meta_XFree()
void | meta_display_get_compositor_version ()
Display * | meta_display_get_xdisplay ()
MetaCompositor * | meta_display_get_compositor ()
GSList * | meta_display_get_screens ()
gboolean | meta_display_has_shape ()
MetaScreen * | meta_display_screen_for_root ()
MetaWindow * | meta_display_get_focus_window ()
GSList * | meta_display_list_windows ()
gboolean | meta_display_xwindow_is_a_no_focus_window ()
int | meta_display_get_damage_event_base ()
int | meta_display_get_shape_event_base ()
Atom | meta_display_get_atom ()
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 ()
unsigned int | meta_display_get_ignored_modifier_mask ()
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 ()
gboolean | meta_display_add_keybinding ()
gboolean | meta_display_remove_keybinding ()
void | meta_display_rebuild_keybindings ()
gboolean | meta_display_add_custom_keybinding ()
gboolean | meta_display_remove_custom_keybinding ()
MetaKeyBindingAction | 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 ()
Window | meta_display_get_leader_window ()
void | meta_display_add_ignored_crossing_serial ()
void | meta_display_unmanage_screen ()
void | meta_display_keybinding_action_invoke_by_code ()

## Types and Values

enum | MetaTabList
enum | MetaTabShowType
enum | MetaAtom
enum | MetaListWindowsFlags

## 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_compositor_version ()

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

### meta_display_get_xdisplay ()

    Display *
    meta_display_get_xdisplay (MetaDisplay *display);

[skip]

### meta_display_get_compositor ()

    MetaCompositor *
    meta_display_get_compositor (MetaDisplay *display);

[skip]

### meta_display_get_screens ()

    GSList *
    meta_display_get_screens (MetaDisplay *display);

#### Parameters

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.

#### Parameters

display | a MetaDisplay |

#### 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 the window that, according to events received from X server, currently has the input focus. We may have already sent a request to the X server to move the focus window elsewhere. (The expected_focus_window records where we've last set the input focus.)

#### Parameters

display | a MetaDisplay |

#### Returns

The current focus window.

[transfer none]

### meta_display_list_windows ()

    GSList *
    meta_display_list_windows (MetaDisplay *display,
                               MetaListWindowsFlags flags);

Lists windows for the display, the `flags` parameter for now determines whether override-redirect windows will be included.

#### Parameters

display | a MetaDisplay |
flags | options for listing |

#### Returns

the list of windows.

[transfer container][element-type MetaWindow]

### meta_display_xwindow_is_a_no_focus_window ()

    gboolean
    meta_display_xwindow_is_a_no_focus_window
                                   (MetaDisplay *display,
                                    Window xwindow);

Returns `TRUE` iff window is one of muffin's internal "no focus" windows (there is one per screen) which will have the focus when there is no actual client window focused.

#### Parameters

display | A MetaDisplay |
xwindow | An X11 window |

### 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_get_atom ()

    Atom
    meta_display_get_atom (MetaDisplay *display,
                           MetaAtom meta_atom);

Gets up an X atom that Muffin prefetched at startup.

[skip]

#### Returns

the X atom corresponding to the given atom enumeration

### 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_ignored_modifier_mask ()

    unsigned int
    meta_display_get_ignored_modifier_mask
                                   (MetaDisplay *display);

#### Parameters

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.

#### Parameters

display | a MetaDisplay |
type | type of tab list |
screen | a MetaScreen |
workspace | origin workspace |

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

#### Parameters

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.

#### Parameters

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

#### Returns

the current grab operation, or `META_GRAB_OP_NONE` if Muffin doesn't currently have a grab. `META_GRAB_OP_COMPOSITOR` will be returned if a compositor-plugin modal operation is in effect (See `muffin_begin_modal_for_plugin()`)

### meta_display_add_keybinding ()

    gboolean
    meta_display_add_keybinding (MetaDisplay *display,
                                 const char *name,
                                 const char *schema,
                                 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.

#### Parameters

display | a MetaDisplay |
name | the binding's name |
schema | the GSettings schema 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

`TRUE` if the keybinding was added successfully, otherwise `FALSE`

### 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_rebuild_keybindings ()

    void
    meta_display_rebuild_keybindings (MetaDisplay *display);

Rebuild all keybindings (typically done after adding, removing, or changing one or more keybindings)

#### Parameters

display | the MetaDisplay |

### meta_display_add_custom_keybinding ()

    gboolean
    meta_display_add_custom_keybinding (MetaDisplay *display,
                                        const char *name,
                                        const char **bindings,
                                        MetaKeyHandlerFunc callback,
                                        gpointer user_data,
                                        GDestroyNotify free_data);

Use `meta_display_remove_custom_keybinding()` to remove the binding.

#### Parameters

display | a MetaDisplay |
name | the binding's unique name |
bindings | array of parseable keystrokes. | [allow-none][array zero-terminated=1]
callback | function to run when the keybinding is invoked |
user_data | the data to pass to `handler` |
free_data | function to free `user_data` |

#### Returns

`TRUE` if the keybinding was added successfully, otherwise `FALSE`

### meta_display_remove_custom_keybinding ()

    gboolean
    meta_display_remove_custom_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_custom_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 ()

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

Get the MetaKeyBindingAction bound to `keycode`. Only builtin keybindings have an associated MetaKeyBindingAction, for bindings added dynamically with `meta_display_add_keybinding()` the function will always return `META_KEYBINDING_ACTION_NONE`.

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

#### Parameters

display | a MetaDisplay |

#### Returns

xid of the leader window.

### 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_keybinding_action_invoke_by_code ()

    void
    meta_display_keybinding_action_invoke_by_code
                                   (MetaDisplay *display,
                                    unsigned int keycode,
                                    unsigned long  mask);

## Types and Values

### enum MetaTabList

#### Members

META_TAB_LIST_NORMAL |  |
META_TAB_LIST_DOCKS |  |
META_TAB_LIST_GROUP |  |
META_TAB_LIST_NORMAL_ALL |  |

### enum MetaTabShowType

#### Members

META_TAB_SHOW_ICON |  |
META_TAB_SHOW_INSTANTLY |  |

### enum MetaAtom

#### Members

META_ATOM_FIRST |  |

### enum MetaListWindowsFlags

#### Members

META_LIST_DEFAULT |  |
META_LIST_INCLUDE_OVERRIDE_REDIRECT |  |