gtk.gdk.Display
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.Display

gtk.gdk.Display — controls the keyboard/mouse pointer grabs and a set of `gtk.gdk.Screen` objects

## Synopsis

    class gtk.gdk.Display(gobject.GObject):
        gtk.gdk.Display(display_name)
        def get_name()
        def get_n_screens()
        def get_screen(screen_num)
        def get_default_screen()
        def pointer_ungrab(time_=0L)
        def keyboard_ungrab(time_=0L)
        def pointer_is_grabbed()
        def beep()
        def sync()
        def close()
        def list_devices()
        def get_event()
        def peek_event()
        def put_event(event)
        def set_double_click_time(msec)
        def get_core_pointer()
        def get_pointer()
        def get_window_at_pointer()
        def flush()
        def set_double_click_distance(distance)
        def supports_cursor_alpha()
        def supports_cursor_color()
        def get_default_cursor_size()
        def get_maximal_cursor_size()
        def get_default_group()
        def supports_selection_notification()
        def supports_clipboard_persistence()
        def request_selection_notification(selection)
        def store_clipboard(clipboard_window, time_, targets)

    Functions

        def gtk.gdk.display_get_default()

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.Display

## Signal Prototypes

"closed" | `def callback(`widget`, `is_error`, `user_param1`, `...`)`

## Description

### Note

This object is available in PyGTK 2.2 and above.

`gtk.gdk.Display` objects provide two capabilities:

- To grab/ungrab keyboard focus and mouse pointer
- To manage and provide information about the `gtk.gdk.Screen`) objects available for this `gtk.gdk.Display`

`gtk.gdk.Display` 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 `gtk.gdk.Screen` objects currently instantiated by the application. It is also used to grab and release the keyboard and the mouse pointer.

## Constructor

        gtk.gdk.Display(display_name)

`display_name` : | the name of the display to open
Returns : | a `gtk.gdk.Display`, or `None` if the display could not be opened.

### Note

This constructor is available in PyGTK 2.2 and above.

Opens the display with the name specified by `display_name` and returns a `gtk.gdk.Display` object wrapping the display..

## Methods

### gtk.gdk.Display.get_name

        def get_name()

Returns : | a string representing the display name.

### Note

This method is available in PyGTK 2.2 and above.

The `get_name`() method returns the name of the display.

### gtk.gdk.Display.get_n_screens

        def get_n_screens()

Returns : | the number of display screens.

### Note

This method is available in PyGTK 2.2 and above.

The `get_n_screens`() method returns the number of screens managed by the display.

### gtk.gdk.Display.get_screen

        def get_screen(screen_num)

`screen_num` : | the screen number
Returns : | the `gtk.gdk.Screen` object

### Note

This method is available in PyGTK 2.2 and above.

The `get_screen`() method returns a `gtk.gdk.Screen` object for one of the screens of the display.

### gtk.gdk.Display.get_default_screen

        def get_default_screen()

Returns : | the default `gtk.gdk.Screen` object for `display`

### Note

This method is available in PyGTK 2.2 and above.

The `get_default_screen`() method returns the default `gtk.gdk.Screen` for the display

### gtk.gdk.Display.pointer_ungrab

        def pointer_ungrab(time_=0L)

`time_` : | a timestamp or 0L for the current time.

### Note

This method is available in PyGTK 2.2 and above.

The `pointer_ungrab`() method releases any pointer grab held by the display.

### gtk.gdk.Display.keyboard_ungrab

        def keyboard_ungrab(time_=0L)

`time_` : | a timestamp or 0L for the current time.

### Note

This method is available in PyGTK 2.2 and above.

The `keyboard_ungrab`() method releases any keyboard grab held by the display.

### gtk.gdk.Display.pointer_is_grabbed

        def pointer_is_grabbed()

Returns : | `True` if an active X pointer grab is in effect

### Note

This method is available in PyGTK 2.2 and above.

The `pointer_is_grabbed`() method returns `True` if the pointer is grabbed.

### gtk.gdk.Display.beep

        def beep()

### Note

This method is available in PyGTK 2.2 and above.

The `beep`() method emits a short beep on the display.

### gtk.gdk.Display.sync

        def sync()

### Note

This method is available in PyGTK 2.2 and above.

The `sync`() method 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. This is most useful for X11. On windowing systems where requests are handled synchronously, this method will do nothing.

### gtk.gdk.Display.close

        def close()

### Note

This method is available in PyGTK 2.2 and above.

The `close`() method closes the connection to the windowing system for the given display, and cleans up associated resources.

### gtk.gdk.Display.list_devices

        def list_devices()

Returns : | a list of `gtk.gdk.Device` objects.

### Note

This method is available in PyGTK 2.2 and above.

The `list_devices`() method returns the list of available input devices attached to the display.

### gtk.gdk.Display.get_event

        def get_event()

Returns : | the next `gtk.gdk.Event` to be processed, or `None` if no events are pending..

### Note

This method is available in PyGTK 2.2 and above.

The `get_event`() method returns the next `gtk.gdk.Event` to be processed for the display, fetching events from the windowing system if necessary. The returned `gtk.gdk.Event` should be freed with the `gtk.gdk.Event.free()` method

### gtk.gdk.Display.peek_event

        def peek_event()

Returns : | a copy of the first `gtk.gdk.Event` on the event queue, or `None` if no events are in the queue.

### Note

This method is available in PyGTK 2.2 and above.

The `peek_event`() method returns a copy of the first `gtk.gdk.Event` in the the display's event queue, without removing the event from the queue. (Note that this method will not get more events from the windowing system. It only checks the events that have already been moved to the `GDK` event queue.) The returned `gtk.gdk.Event` should be freed with `gtk.gdk.Event.free()`.

### gtk.gdk.Display.put_event

        def put_event(event)

`event` : | a `gtk.gdk.Event`.

### Note

This method is available in PyGTK 2.2 and above.

The `put_event`() method appends a copy of the given event onto the front of the event queue for the display.

### gtk.gdk.Display.set_double_click_time

        def set_double_click_time(msec)

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

### Note

This method is available in PyGTK 2.2 and above.

The `set_double_click_time`() method sets the double click time (two clicks within this time interval count as a double click and result in a `gtk.gdk._2BUTTON_PRESS` event). Applications should not set this, it is a global user-configured setting.

### gtk.gdk.Display.get_core_pointer

        def get_core_pointer()

Returns : | the core pointer device

### Note

This method is available in PyGTK 2.2 and above.

The `get_core_pointer`() method returns the core pointer device for the given display

### gtk.gdk.Display.get_pointer

        def get_pointer()

Returns : | a 4-tuple containing the screen that the cursor is on, the root window X and Y coordinates of the pointer and the current modifier mask

### Note

This method is available in PyGTK 2.2 and above.

The `get_pointer`() method returns a 4-tuple containing the `gtk.gdk.Screen` that the pointer is on, the current location coordinates of the pointer and the current modifier mask for the display. The returned modifier mask is a combination of the GDK Modifier Constants.

### gtk.gdk.Display.get_window_at_pointer

        def get_window_at_pointer()

Returns : | a 3-tuple containing the `gtk.gdk.Window` under the mouse pointer and the x and y coordinates of the window origin

### Note

This method is available in PyGTK 2.2 and above.

The `get_window_at_pointer`() method returns a 3-tuple containing the `gtk.gdk.Window` underneath the mouse pointer and the location of that window's origin. Returns `None` if the window under the mouse pointer is not known to `GDK` (for example, belongs to another application).

### gtk.gdk.Display.flush

        def flush()

### Note

This method is available in PyGTK 2.4 and above.

The `flush`() method flushes any requests queued for the windowing system; this happens automatically when the main loop blocks waiting for new events, but if your application is drawing without returning control to the main loop, you may need to call this method explicitly. A common case where this method needs to be called is when an application is executing drawing commands from a thread other than the thread where the main loop is running.

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

### gtk.gdk.Display.set_double_click_distance

        def set_double_click_distance(distance)

`distance` : | the distance in pixels

### Note

This method is available in PyGTK 2.4 and above.

The `set_double_click_distance`() method sets the double click distance (two clicks within this distance count as a double click and result in a `gtk.gdk.2BUTTON_PRESS` event). See the `set_double_click_time()` method for more information. Applications should not set this, it is a global user-configured setting.

### gtk.gdk.Display.supports_cursor_alpha

        def supports_cursor_alpha()

Returns : | `True` if cursors can have alpha channels.

### Note

This method is available in PyGTK 2.4 and above.

The `supports_cursor_alpha`() method returns `True` if cursors can use an 8bit alpha channel on the display. Otherwise, cursors are restricted to bilevel alpha (i.e. a mask).

### gtk.gdk.Display.supports_cursor_color

        def supports_cursor_color()

Returns : | `True` if cursors can have multiple colors.

### Note

This method is available in PyGTK 2.4 and above.

The `supports_cursor_color`() method returns `True` if multicolored cursors are supported on the display. Otherwise, cursors have only a foreground and a background color.

### gtk.gdk.Display.get_default_cursor_size

        def get_default_cursor_size()

Returns : | the default cursor size.

### Note

This method is available in PyGTK 2.4 and above.

The `get_default_cursor_size`() method returns the default size to use for cursors on the display.

### gtk.gdk.Display.get_maximal_cursor_size

        def get_maximal_cursor_size()

Returns : | a 2-tuple containing the maximal cursor width and height

### Note

This method is available in PyGTK 2.4 and above.

The `get_maximal_cursor_size`() method returns a 2-tuple containing the maximum width and height to use for cursors on the display.

### gtk.gdk.Display.get_default_group

        def get_default_group()

Returns : | The default group leader window for the display

### Note

This method is available in PyGTK 2.4 and above.

The `get_default_group`() method returns the default group leader window for all toplevel windows on the display. This window is implicitly created by `GDK`. See the `gtk.gdk.Window.set_group()` method for more information.

### gtk.gdk.Display.supports_selection_notification

        def get_default_group()

Returns : | `True` if `gtk.gdk.EventOwnerChange` events will be sent.

### Note

This method is available in PyGTK 2.6 and above.

The `supports_selection_notification`() method returns `True` if `gtk.gdk.EventOwnerChange` events will be sent when the owner of a selection changes.

### gtk.gdk.Display.supports_clipboard_persistence

        def supports_clipboard_persistence()

Returns : | `True` if the display supports clipboard persistence.

### Note

This method is available in PyGTK 2.6 and above.

The `supports_clipboard_persistence`() method Returns whether the specified display supports clipboard persistence; i.e. if it's possible to store the clipboard data after an application has quit. On X11 this checks if a clipboard daemon is running.

### gtk.gdk.Display.request_selection_notification

        def request_selection_notification(selection)

`selection` : | The string (or `gtk.gdk.Atom`) naming the selection for which ownership change notification is requested

### Note

This method is available in PyGTK 2.6 and above.

The `request_selection_notification`() method requests that `gtk.gdk.EventOwnerChange` events will be sent for changes in ownership of the atom specified by `selection`.

### gtk.gdk.Display.store_clipboard

        def store_clipboard(clipboard_window, time, targets)

`clipboard_window` : | a `gtk.gdk.Window` belonging to the clipboard owner
`time` : | a timestamp
`targets` : | a list of targets that should be saved, or `None` if all available targets should be saved.

### Note

This method is available in PyGTK 2.6 and above.

The `store_clipboard`() method issues a request to the the clipboard manager to store the clipboard data. On X11, this is a special program that works according to the freedesktop clipboard specification, available at http://www.freedesktop.org/Standards/clipboard-manager-spec.

## Functions

### gtk.gdk.display_get_default

        def gtk.gdk.display_get_default()

Returns : | a `gtk.gdk.Display`, or `None` if there is no default display.

### Note

This function is available in PyGTK 2.2 and above.

The `gtk.gdk.display_get_default`() function returns the default `gtk.gdk.Display`. This is a convenience function for:

      display_manager = gtk.gdk.display_manager_get()
      display = display.manager.get_default_display()

## Signals

### The "closed" gtk.gdk.Display Signal

        def callback(display, is_error, user_param1, ...)

`display` : | the display that received the signal
`is_error` : | `True` if the display was closed due to an error
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "closed" signal is emitted when the connection to the windowing system for `display` is closed.

Prev | Up | Next
gtk.gdk.Device | Home | gtk.gdk.DisplayManager