GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GdkDisplay

## Name

GdkDisplay -- controls the keyboard/mouse pointer grabs and a set of GdkScreens

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkDisplay;
    GdkDisplay* gdk_open_display                (const gchar *display_name);
    G_CONST_RETURN gchar* gdk_display_get_name  (GdkDisplay *display);
    gint        gdk_display_get_n_screens       (GdkDisplay *display);
    GdkScreen*  gdk_display_get_screen          (GdkDisplay *display,
                                                 gint screen_num);
    GdkScreen*  gdk_display_get_default_screen  (GdkDisplay *display);
    void        gdk_display_pointer_ungrab      (GdkDisplay *display,
                                                 guint32 time);
    void        gdk_display_keyboard_ungrab     (GdkDisplay *display,
                                                 guint32 time);
    gboolean    gdk_display_pointer_is_grabbed  (GdkDisplay *display);
    void        gdk_display_beep                (GdkDisplay *display);
    void        gdk_display_sync                (GdkDisplay *display);
    void        gdk_display_close               (GdkDisplay *display);
    GList*      gdk_display_list_devices        (GdkDisplay *display);
    GdkEvent*   gdk_display_get_event           (GdkDisplay *display);
    GdkEvent*   gdk_display_peek_event          (GdkDisplay *display);
    void        gdk_display_put_event           (GdkDisplay *display,
                                                 GdkEvent *event);
    void        gdk_display_add_client_message_filter
                                                (GdkDisplay *display,
                                                 GdkAtom message_type,
                                                 GdkFilterFunc func,
                                                 gpointer data);
    void        gdk_display_set_double_click_time
                                                (GdkDisplay *display,
                                                 guint msec);
    void        gdk_display_set_sm_client_id    (GdkDisplay *display,
                                                 const gchar *sm_client_id);
    void        gdk_set_default_display         (GdkDisplay *display);
    GdkDisplay* gdk_get_default_display         (void);

## Object Hierarchy

      GObject
       +----GdkDisplay

## Description

GdkDisplay objects purpose are two fold:

- To grab/ungrab keyboard focus and mouse pointer

- To manage and provide information about the GdkScreen(s) available for this GdkDisplay

GdkDisplay objects are the GDK representation of the X Display which can be described as a workstation consisting of a keyboard a pointing device (such as a mouse) and one or more screens. It is used to open and keep track of various GdkScreen objects currently instanciated by the application. It is also used to grab and release the keyboard and the mouse pointer.

## Details

### struct GdkDisplay

    struct GdkDisplay;

The GdkDisplay struct is the GDK representation of an X display. All its fields are private and should not be accessed directly.

### gdk_open_display ()

    GdkDisplay* gdk_open_display                (const gchar *display_name);

Opens a display.

`display_name` : | the name of the display to open
Returns : | a GdkDisplay, or `NULL` if the display could not be opened.

### gdk_display_get_name ()

    G_CONST_RETURN gchar* gdk_display_get_name  (GdkDisplay *display);

Gets the name of the display.

`display` : | a GdkDisplay
Returns : | a string representing the display name.

### gdk_display_get_n_screens ()

    gint        gdk_display_get_n_screens       (GdkDisplay *display);

Gets the number of screen managed by the `display`.

`display` : | a GdkDisplay
Returns : | number of screens.

### gdk_display_get_screen ()

    GdkScreen*  gdk_display_get_screen          (GdkDisplay *display,
                                                 gint screen_num);

Returns a screen object for one of the screens of the display.

`display` : | a GdkDisplay
`screen_num` : | the screen number
Returns : | the GdkScreen object

### gdk_display_get_default_screen ()

    GdkScreen*  gdk_display_get_default_screen  (GdkDisplay *display);

Get the default GdkScreen for `display`.

`display` : | a GdkDisplay
Returns : | the default GdkScreen object for `display`

### gdk_display_pointer_ungrab ()

    void        gdk_display_pointer_ungrab      (GdkDisplay *display,
                                                 guint32 time);

Release any pointer grab.

`display` : | a GdkDisplay.
`time` : | a timestap (e.g. GDK_CURRENT_TIME).

### gdk_display_keyboard_ungrab ()

    void        gdk_display_keyboard_ungrab     (GdkDisplay *display,
                                                 guint32 time);

Release any keyboard grab

`display` : | a GdkDisplay.
`time` : | a timestap (e.g GDK_CURRENT_TIME).

### gdk_display_pointer_is_grabbed ()

    gboolean    gdk_display_pointer_is_grabbed  (GdkDisplay *display);

Test if the pointer is grabbed.

`display` : | a GdkDisplay
Returns : | : TRUE if an active X pointer grab is in effect

### gdk_display_beep ()

    void        gdk_display_beep                (GdkDisplay *display);

Emits a short beep on `display`

`display` : | a GdkDisplay

### gdk_display_sync ()

    void        gdk_display_sync                (GdkDisplay *display);

Flushes any requests queued for the windowing system and waits until all requests have been handled. This is often used for making sure that the display is synchronized with the current state of the program. Calling gdk_display_sync() before gdk_error_trap_pop() makes sure that any errors generated from earlier requests are handled before the error trap is removed.

This is most useful for X11. On windowing systems where requests handled synchronously, this function will do nothing.

`display` : | a GdkDisplay

### gdk_display_close ()

    void        gdk_display_close               (GdkDisplay *display);

Closes and cleanup the resources used by the `display`

`display` : | a GdkDisplay

### gdk_display_list_devices ()

    GList*      gdk_display_list_devices        (GdkDisplay *display);

Returns the list of available input devices attached to `display`. The list is statically allocated and should not be freed.

`display` : | a GdkDisplay
Returns : | a list of GdkDevice

### gdk_display_get_event ()

    GdkEvent*   gdk_display_get_event           (GdkDisplay *display);

Gets the next GdkEvent to be processed for `display`, fetching events from the windowing system if necessary.

`display` : | a GdkDisplay
Returns : | the next GdkEvent to be processed, or `NULL` if no events are pending. The returned GdkEvent should be freed with gdk_event_free().

### gdk_display_peek_event ()

    GdkEvent*   gdk_display_peek_event          (GdkDisplay *display);

Gets a copy of the first GdkEvent in the `display`'s event queue, without removing the event from the queue. (Note that this function will not get more events from the windowing system. It only checks the events that have already been moved to the GDK event queue.)

`display` : | a GdkDisplay
Returns : | a copy of the first GdkEvent on the event queue, or `NULL` if no events are in the queue. The returned GdkEvent should be freed with gdk_event_free().

### gdk_display_put_event ()

    void        gdk_display_put_event           (GdkDisplay *display,
                                                 GdkEvent *event);

Appends a copy of the given event onto the front of the event queue for `display`.

`display` : | a GdkDisplay
`event` : | a GdkEvent.

### gdk_display_add_client_message_filter ()

    void        gdk_display_add_client_message_filter
                                                (GdkDisplay *display,
                                                 GdkAtom message_type,
                                                 GdkFilterFunc func,
                                                 gpointer data);

Adds a filter to be called when X ClientMessage events are received.

`display` : | a GdkDisplay for which this message filter applies
`message_type` : | the type of ClientMessage events to receive. This will be checked against the `message_type` field of the XClientMessage event struct.
`func` : | the function to call to process the event.
`data` : | user data to pass to `func`.

### gdk_display_set_double_click_time ()

    void        gdk_display_set_double_click_time
                                                (GdkDisplay *display,
                                                 guint msec);

Sets the double click time (two clicks within this time interval count as a double click and result in a GDK_2BUTTON_PRESS event). Applications should NOT set this, it is a global user-configured setting.

`display` : | a GdkDisplay
`msec` : | double click time in milliseconds (thousandths of a second)

### gdk_display_set_sm_client_id ()

    void        gdk_display_set_sm_client_id    (GdkDisplay *display,
                                                 const gchar *sm_client_id);

Sets the `SM_CLIENT_ID` property on the application's leader window so that the window manager can save the application's state using the X11R6 ICCCM session management protocol.

See the X Session Management Library documentation for more information on session management and the Inter-Client Communication Conventions Manual (ICCCM) for information on the `WM_CLIENT_LEADER` property. (Both documents are part of the X Window System distribution.)

`display` : | a GdkDisplay
`sm_client_id` : | the client id assigned by the session manager when the connection was opened, or `NULL` to remove the property.

### gdk_set_default_display ()

    void        gdk_set_default_display         (GdkDisplay *display);

Sets `display` as the default display.

`display` : | a GdkDisplay

### gdk_get_default_display ()

    GdkDisplay* gdk_get_default_display         (void);

Gets the default GdkDisplay.

Returns : | a GdkDisplay, or `NULL` if there is no default display.

<<< Previous Page | Home | Up | Next Page >>>
Multi-head Support Overview | GdkScreen