MetaDisplay

MetaDisplay — Handles operations on an X display.

Synopsis

enum                MetaTabList;
enum                MetaTabShowType;
#define             meta_XFree                          (p)
enum                MetaAtom;
enum                MetaListWindowsFlags;
void                meta_display_get_compositor_version (MetaDisplay *display,
                                                         int *major,
                                                         int *minor);
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);
GSList *            meta_display_list_windows           (MetaDisplay *display,
                                                         MetaListWindowsFlags flags);
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);
Atom                meta_display_get_atom               (MetaDisplay *display,
                                                         MetaAtom meta_atom);
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);
gboolean            meta_display_add_keybinding         (MetaDisplay *display,
                                                         const char *name,
                                                         const char *schema,
                                                         MetaKeyBindingFlags flags,
                                                         MetaKeyHandlerFunc handler,
                                                         gpointer user_data,
                                                         GDestroyNotify free_data);
gboolean            meta_display_remove_keybinding      (MetaDisplay *display,
                                                         const char *name);
void                meta_display_rebuild_keybindings    (MetaDisplay *display);
gboolean            meta_display_add_custom_keybinding  (MetaDisplay *display,
                                                         const char *name,
                                                         const char **bindings,
                                                         MetaKeyHandlerFunc callback,
                                                         gpointer user_data,
                                                         GDestroyNotify free_data);
gboolean            meta_display_remove_custom_keybinding
                                                        (MetaDisplay *display,
                                                         const char *name);
MetaKeyBindingAction 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_keybinding_action_invoke_by_code
                                                        (MetaDisplay *display,
                                                         unsigned int keycode,
                                                         unsigned long  mask);
                    MetaDisplayClass;

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

META_TAB_LIST_DOCKS

META_TAB_LIST_GROUP

META_TAB_LIST_NORMAL_ALL


enum MetaTabShowType

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

META_TAB_SHOW_ICON

META_TAB_SHOW_INSTANTLY


meta_XFree()

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

enum MetaAtom

typedef enum {
  META_ATOM_FIRST = 0,
#define item(x) META_ATOM_##x,
#include "atomnames.h"
#undef item
} MetaAtom;

META_ATOM_FIRST


enum MetaListWindowsFlags

typedef enum {
  META_LIST_DEFAULT                   = 0,      /* normal windows */
  META_LIST_INCLUDE_OVERRIDE_REDIRECT = 1 << 0, /* normal and O-R */
} MetaListWindowsFlags;

META_LIST_DEFAULT

META_LIST_INCLUDE_OVERRIDE_REDIRECT


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

meta_display_get_compositor ()

MetaCompositor *    meta_display_get_compositor         (MetaDisplay *display);

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

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

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.

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

display :

A MetaDisplay

xwindow :

An X11 window

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.

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.

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.

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.

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.

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

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.

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

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

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.

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

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.

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

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

MetaDisplayClass

typedef struct _MetaDisplayClass MetaDisplayClass;