Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Login

Gdk::Display

class Gdk::Display

Gdk::Display objects purpose are two fold:

  • To grab/ungrab keyboard focus and mouse pointer
  • To manage and provide information about the Gdk::Screen(s) available for this Gdk::Display

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 Gdk::Screen objects currently instanciated by the application. It is also used to grab and release the keyboard and the mouse pointer.

Class Methods

Gdk::Display.open(display_name)
Opens a display. You need to call Gdk::Display#close when you don't need it. Since 2.2
  • display_name: the name of the display to open
  • Returns: a Gdk::Display, or nil if the display could not be opened.
Gdk::Display.open(display_name){|display| ... }
Opens a display and invoke the block, then closes it automatically. Since 2.2
  • display_name: the name of the display to open
  • {|display| ... }: A block with opened display
  • Returns: a Gdk::Display, or nil if the display could not be opened.
Gdk::Display.default
Gets the default Gdk::Display. This is a convenience method for: Gdk::DisplayManager.get.default_display? Since 2.2
  • Returns: a Gdk::Display, or nill if there is no default display

Instance Methods

name
Gets the name of the display. Since 2.2
  • Returns: a String representing the display name
n_screens
Gets the number of screen managed by the display. Since 2.2
  • Returns: number of screens.
get_screen(screen_num)
Returns a screen object for one of the screens of the display. Since 2.2
  • screen_num: the screen number
  • Returns: the Gdk::Screen object
[screen_num]
Same as Gdk::Display#get_screen.
  • screen_num: the screen number
  • Returns: the Gdk::Screen object
default_screen
Get the default Gdk::Screen for display. Since 2.2
pointer_ungrab(time)
Release any pointer grab. Since 2.2
keyboard_ungrab(time)
Release any keyboard grab. Since 2.2
pointer_grabbed?
Test if the pointer is grabbed. Since 2.2
  • Returns: true if an active X pointer grab is in effect
beep
Emits a short beep on display. Since 2.2
  • Returns: self
sync
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 are handled synchronously, this method will do nothing. Since 2.2
  • Returns: self
flush
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 function explicitely. A common case where this function 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. Since 2.4
  • Returns: self
close
Closes the connection to the windowing system for the given display, and cleans up associated resources. Since 2.2
  • Returns: self
devices
Returns an Array of available input devices attached to display. The list is statically allocated and should not be freed. Since 2.2
event
Gets the next Gdk::Event to be processed for display, fetching events from the windowing system if necessary. Since 2.2
  • Returns: the next Gdk::Event to be processed, or nil if no events are pending.
peek_event
Gets a copy of the first Gdk::Event 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.)
  • Returns: a copy of the first Gdk::Event on the event queue, or nilL if no events are in the queue.
put_event(event)
Appends a copy of the given event onto the front of the event queue for display. Since 2.2
double_click_time=(msec)
Sets the double click time (two clicks within this time interval count as a double click and result in a Gdk::Event::BUTTON2_PRESS event). Applications should not set this, it is a global user-configured setting. Since 2.2
  • msec: double click time in milliseconds (thousandths of a second)
  • Returns: msec
set_double_click_time(msec)
Same as Gdk::Display#double_click_time=. Since 2.2
  • msec: double click time in milliseconds (thousandths of a second)
  • Returns: self
double_click_distance=(distance)
Sets the double click distance (two clicks within this distance count as a double click and result in a Gdk::Event::BUTTON2_PRESS event). See also Gdk::Display#double_click_time=. Applications should not set this, it is a global user-configured setting. Since 2.4
  • distance: distance in pixels (Integer)
  • Returns: distance
set_double_click_distance(distance)
Same as Gdk::Display#double_click_distance=. Since 2.4
  • distance: distance in pixels (Integer)
  • Returns: self
pointer
Gets the current location of the pointer and the current modifier mask for a given display. Since 2.2
  • Returns: [screen, x, y, mask]
    • screen: the Gdk::Screen that the cursor is on, or nil.
    • x: root window X coordinate of pointer.
    • y: root window Y coordinate of pointer.
    • mask: current modifier mask.
window_at_pointer
Obtains the window underneath the mouse pointer, returning the location of that window in win_x, win_y for screen. Since 2.2
  • Returns: [window, x, y]
    • window: the Gdk::Window under the mouse pointer, or nil if the window under the mouse pointer is not known to GDK (for example, belongs to another application).
    • win_x: origin of the window under the pointer
    • win_y: origin of the window under the pointer
  • Returns: self
supports_cursor_color?
Returns true if multicolored cursors are supported on display. Otherwise, cursors have only a forground and a background color. Since 2.4
  • Returns: true if cursors can have multiple colors.
supports_cursor_alpha?
Returns true if cursors can use an 8bit alpha channel on display. Otherwise, cursors are restricted to bilevel alpha (i.e. a mask). Since 2.4
  • Returns: true if cursors can have alpha channels.
supports_composite?
Returns true if Gdk::Window#composited= can be used to redirect drawing on the window using compositing. Currently this only works on X11 with XComposite and XDamage extensions available. Since 2.12
  • Returns: true if compositing is available.
default_cursor_size
Returns the default size to use for cursors on display. Since 2.4
  • Returns: the default cursor size.
maximal_cursor_size
Gets the maximal size to use for cursors on display. Since 2.4
  • Returns: [width, height]
    • width: the return location for the maximal cursor width
    • height: the return location for the maximal cursor height
default_group
Returns the default group leader window for all toplevel windows on display. This window is implicitly created by GDK. See Gdk::Window#group=. Since 2.4
  • Returns: The default group leader Gdk::Window for display
supports_selection_notification?
Returns whether Gdk::EventOwnerChange events will be sent when the owner of a selection changes. Since 2.6
request_selection_notification?
Request Gdk::EventOwnerChange events for ownership changes of the selection named by the given atom. Since 2.6
  • selection: the Gdk::Atom naming the selection for which ownership change notification is requested
  • Returns: true if Gdk::EventOwnerChange events will be sent.
supports_clipboard_persistence?
Returns whether the speicifed display supports clipboard persistance; 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. Since 2.6
  • Returns: true if the display supports clipboard persistance.
store_clipboard(clipboard_window, time, targets)
Issues a request to 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 <URL:http://www.freedesktop.org/Standards/clipboard-manager-spec>. Since 2.6
  • clipboard_window: a Gdk::Window belonging to the clipboard owner
  • time: a timestamp (Integer)
  • targets: an Array of targets that should be saved, or nil if all available targets should be saved.
  • Returns: self
core_pointer
Returns the core pointer device for the given display. Since 2.2
warp_pointer(screen, x, y)
Warps the pointer of display to the point x,y on the specified screen, unless the pointer is confined to a window by a grab, in which case it will be moved as far as allowed by the grab. Warping the pointer creates events as if the user had moved the mouse instantaneously to the destination. Note that the pointer should normally be under the control of the user. This function was added to cover some rare use cases like keyboard navigation support for the color picker in the Gtk::ColorSelectionDialog. Since 2.8
  • screen: the screen of display to warp the pointer to (Gdk::Screen)
  • x: the x coordinate of the destination (Fixnum)
  • y: the y coordinate of the destination (Fixnum)
  • Returns: self
grab
Call XGrabServer() on display. To ungrab the display again, use Gdk::Display#ungrab(). Gdk::Display#grab/Gdk::Display#ungrab calls can be nested. X11 only Since 2.2
  • Returns: self
ungrab
Ungrab display after it has been grabbed with Gdk::Display#grab. X11 only Since 2.2
  • Returns: self
register_standard_event_type(event_base, n_events)
Registers interest in receiving extension events with type codes between event_base and event_base + n_events - 1. The registered events must have the window field in the same place as core X events (this is not the case for e.g. XKB extension events). If an event type is registered, events of this type will go through global and window-specific filters. Unregistered events will only go through global filters. GDK may register the events of some X extensions on its own. This method should only be needed in unusual circumstances, e.g. when filtering XInput extension events on the root window. X11 only Since 2.2
  • event_base: first event type code to register (Integer)
  • n_events: number of event type codes to register (Integer)
  • Returns: self
user_time
Returns the timestamp of the last user interaction on self. The timestamp is taken from events caused by user interaction such as key presses or pointer movements. See Gdk::Window#user_time=. X11 only Since 2.8
  • Returns: the timestamp of the last user interaction
set_cursor_theme(theme, size)
Sets the cursor theme from which the images for cursor should be taken. If the windowing system supports it, existing cursors created with Gdk::Cursor.new (specifying nothing, a display or a name) are updated to reflect the theme change. Custom cursors constructed with Gdk::Cursor.new specifying a Gdk::Pixmap or a Gdk::Pixbuf will have to be handled by the application (GTK+ applications can learn about cursor theme changes by listening for change notification for the corresponding Gtk::Setting?). X11 only Since 2.8
  • theme: the name of the cursor theme to use (String), or nil to unset a previously set value
  • size: the cursor size to use (Fixnum)
  • Returns: self
trigger_tooltip_query
Triggers a new tooltip query on this display, in order to update the current visible tooltip, or to show/hide the current tooltip. This function is useful to call when, for example, the state of the widget changed by a key press. Since 2.12
  • Returns: self
button_click_time
  • Returns: self: FIXME
button_number
  • Returns: self: FIXME
button_window
  • Returns: self: FIXME
button_x
  • Returns: self: FIXME
button_y
  • Returns: self: FIXME
closed?
  • Returns: self: FIXME
double_click_distance
  • Returns: self: FIXME
double_click_time
  • Returns: self: FIXME
supports_input_shapes?
  • Returns: self: FIXME
supports_shapes?
  • Returns: self: FIXME
startup_notification_id
  • Returns: self: FIXME

Signals

closed: self, is_error
The ::closed signal is emitted when the connection to the windowing system for display is closed. Since 2.2
  • self: Gdk::Display
  • is_error: true if the display was closed due to an error, otherwise false

ChangeLog

  • 2005-09-20 Documented 2.8 additions - gc?
  • 2005-05-07 Added. - Masao