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

## gtk.gdk Functions

gtk.gdk Functions — the gtk.gdk module functions

## Synopsis

### `gtk.gdk.Atom` Functions

        def gtk.gdk.atom_intern(name, only_if_exists=False)

### `gtk.gdk.Color` Functions

        def gtk.gdk.color_parse(spec)

### `gtk.gdk.Colormap` Functions

        def gtk.gdk.colormap_get_system()

### `gtk.gdk.Device` Functions

        def gtk.gdk.devices_list()
        def gtk.gdk.device_get_core_pointer()

### `gtk.gdk.Display` Functions

        def gtk.gdk.display_get_default()

### `gtk.gdk.DisplayManager` Functions

        def gtk.gdk.display_manager_get()

### `gtk.gdk.Event` Functions

        def gtk.gdk.events_pending()
        def gtk.gdk.event_peek()
        def gtk.gdk.event_get()
        def gtk.gdk.event_get_graphics_expose(window)
        def gtk.gdk.set_show_events(show_events)
        def gtk.gdk.get_show_events()
        def gtk.gdk.event_handler_set(func, data=None)

### `gtk.gdk.Keymap` Functions

        def gtk.gdk.keymap_get_default()
        def gtk.gdk.keymap_get_for_display(display)
        def gtk.gdk.keyval_name(keyval)
        def gtk.gdk.keyval_from_name(keyval_name)
        def gtk.gdk.keyval_convert_case(symbol)
        def gtk.gdk.keyval_to_upper(keyval)
        def gtk.gdk.keyval_to_lower(keyval)
        def gtk.gdk.keyval_is_upper(keyval)
        def gtk.gdk.keyval_is_lower(keyval)
        def gtk.gdk.keyval_to_unicode(keyval)
        def gtk.gdk.unicode_to_keyval(wc)

### `gtk.gdk.PangoRenderer` Functions

        def gtk.gdk.gdk_pango_renderer_get_default(screen)

### `gtk.gdk.Pixbuf` Functions

        def gtk.gdk.pixbuf_new_from_file(filename)
        def gtk.gdk.pixbuf_new_from_file_at_size(filename, width, height)
        def gtk.gdk.pixbuf_new_from_data(data, colorspace, has_alpha, bits_per_sample, width, height, rowstride)
        def gtk.gdk.pixbuf_new_from_array(array, colorspace, bits_per_sample)
        def gtk.gdk.pixbuf_new_from_xpm_data(data)
        def gtk.gdk.pixbuf_new_from_inline(data_length, data, copy_pixels)
        def gtk.gdk.pixbuf_get_formats()
        def gtk.gdk.pixbuf_get_file_info(filename)

### `gtk.gdk.PixbufLoader` Functions

        def gtk.gdk.pixbuf_loader_new_with_mime_type(mime_type)

### `gtk.gdk.Pixmap` Functions

        def gtk.gdk.bitmap_create_from_data(drawable, data, width, height)
        def gtk.gdk.pixmap_create_from_data(drawable, data, width, height, depth, fg, bg)
        def gtk.gdk.pixmap_create_from_xpm(window, transparent_color, filename)
        def gtk.gdk.pixmap_colormap_create_from_xpm(window, colormap, transparent_color, filename)
        def gtk.gdk.pixmap_create_from_xpm_d(window, transparent_color, data)
        def gtk.gdk.pixmap_colormap_create_from_xpm_d(window, colormap, transparent_color, data)
        def gtk.gdk.pixmap_foreign_new(anid)
        def gtk.gdk.pixmap_lookup(anid)
        def gtk.gdk.pixmap_foreign_new_for_display(display, anid)
        def gtk.gdk.pixmap_lookup_for_display(display, anid)

### `gtk.gdk.Region` Functions

        def gtk.gdk.region_rectangle(rectangle)

### `gtk.gdk.Screen` Functions

        def gtk.gdk.screen_width()
        def gtk.gdk.screen_height()
        def gtk.gdk.screen_width_mm()
        def gtk.gdk.screen_height_mm()
        def gtk.gdk.screen_get_default()

### `gtk.gdk.Visual` Functions

        def gtk.gdk.list_visuals()
        def gtk.gdk.visual_get_best()
        def gtk.gdk.visual_get_best_depth()
        def gtk.gdk.visual_get_best_type()
        def gtk.gdk.visual_get_best_with_depth(depth)
        def gtk.gdk.visual_get_best_with_type(type)
        def gtk.gdk.visual_get_system()
        def gtk.gdk.query_depths()
        def gtk.gdk.query_visual_types()

### `gtk.gdk.Window` Functions

        def gtk.gdk.window_foreign_new(anid)
        def gtk.gdk.window_foreign_new_for_display(display, anid)
        def gtk.gdk.get_default_root_window()
        def gtk.gdk.window_get_toplevels()
        def gtk.gdk.window_lookup(anid)
        def gtk.gdkwindow_lookup_for_display.(display, anid)
        def gtk.gdk.window_process_all_updates()
        def gtk.gdk.gdk_window_set_debug_updates()
        def gtk.gdk.window_at_pointer()

### Miscellaneous Functions

        def gtk.gdk.pointer_grab(window, owner_events=False, event_mask=0, confine_to=None, cursor=None, time=0L)
        def gtk.gdk.pointer_ungrab(time=0L)
        def gtk.gdk.keyboard_grab(window, owner_events=False, time=0L)
        def gtk.gdk.keyboard_ungrab(time=0L)
        def gtk.gdk.pointer_is_grabbed()
        def gtk.gdk.flush()
        def gtk.gdk.beep()
        def gtk.gdk.set_double_click_time(msec)
        def gtk.gdk.threads_enter()
        def gtk.gdk.threads_leave()

    	  gtk.gdk.lock
          def gtk.gdk.threads_init()
        def gtk.gdk.rgb_ditherable()
        def gtk.gdk.rgb_get_colormap()
        def gtk.gdk.rgb_set_verbose(verbose)
        def gtk.gdk.rgb_set_install(install)
        def gtk.gdk.rgb_set_min_colors(min_colors)
        def gtk.gdk.rgb_get_visual()
        def gtk.gdk.selection_owner_get(selection)

          def gtk.gdk.selection_owner_get_for_display(display, selection)

          def gtk.gdk.selection_owner_set_for_display(display, owner, selection, time, send_event)

          def gtk.gdk.selection_send_notify(requestor, selection, target, property, time)
        def gtk.gdk.set_sm_client_id(sm_client_id)
        def gtk.gdk.notify_startup_complete()
        def gtk.gdk.get_program_class()
        def gtk.gdk.set_program_class(program_class)
        def gtk.gdk.get_display()
        def gtk.gdk.get_display_arg_name()
        def gtk.gdk.pango_context_get_for_screen(screen)
        def gtk.gdk.pango_context_get()
        def gtk.gdk.x11_display_get_startup_notification_id(display)

## Description

These functions are part of the `PyGTK` gtk.gdk module. All the functions are listed above with links to the function description. Most functions are associated with a specific object class and their descriptions are part of the class reference. Those functions that are not directly associated with a specific class have their descriptions below.

## Functions

### gtk.gdk.pointer_grab

        def gtk.gdk.pointer_grab(window, owner_events=False, event_mask=0, confine_to=None, cursor=None, time=0L)

`window` : | the `gtk.gdk.Window` that will own the grab (the grab window).
`owner_events` : | if `False` then all pointer events are reported with respect to `window` and are only reported if selected by `event_mask`. If `True` then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to `window` and only if selected by `event_mask`. In either mode, unreported events are discarded.
`event_mask` : | specifies the event mask, that is used in accordance with `owner_events`.
`confine_to` : | If not `None`, the pointer will be confined to this `gtk.gdk.Window` during the grab. If the pointer is outside `confine_to`, it will automatically be moved to the closest edge of `confine_to` and enter and leave events will be generated as necessary.
`cursor` : | the `gtk.gdk.Cursor` to display while the grab is active. If this is None then the normal cursors are used for `window` and its descendants, and the cursor for `window` is used for all other windows.
`time` : | the timestamp of the event that led to this pointer grab. This usually comes from a `gtk.gdk.Event`, though 0L can be used to use the current time if the time isn't known.
Returns : | a grab status value

The `gtk.gdk.pointer_grab`() function grabs the pointer (usually a mouse) so that all events are passed to this application until the pointer is ungrabbed with the `gtk.gdk.pointer_ungrab`(), or the grab window becomes unviewable. This overrides any previous pointer grab by this client. This function returns a grab status value:

`gtk.gdk.GRAB_SUCCESS` | The resource was successfully grabbed.
`gtk.gdk.GRAB_ALREADY_GRABBED` | The resource is actively grabbed by another client.
`gtk.gdk.GRAB_INVALID_TIME` | The resource was grabbed more recently than the specified time.
`gtk.gdk.GRAB_NOT_VIEWABLE` | The grab window or the `confine_to` window are not viewable.
`gtk.gdk.GRAB_FROZEN` | The resource is frozen by an active grab of another client.

Pointer grabs are used for operations that need complete control over mouse events, even if the mouse leaves the application. For example it is used for drag and drop, for dragging the handle in the `gtk.HPaned` and `gtk.VPaned` widgets. Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with `owner_events` set to `True`.

### gtk.gdk.pointer_ungrab

        def gtk.gdk.pointer_ungrab(time=0L)

`time` : | a timestamp from a `gtk.gdk.Event` or 0L to use the current time

The `gtk.gdk.pointer_ungrab`() function ungrabs the pointer if it is grabbed by this application.

### gtk.gdk.keyboard_grab

        def gtk.gdk.keyboard_grab(window, owner_events=False, time=0L)

`window` : | the `gtk.gdk.Window` that will own the grab (the grab window).
`owner_events` : | if `False` then all keyboard events are reported with respect to `window`. If `True` then keyboard events for this application are reported as normal, but keyboard events outside this application are reported with respect to `window`. Both key press and key release events are always reported, independent of the event mask set by the application.
`time` : | a timestamp from a `gtk.gdk.Event` or 0L to use the current time
Returns : | a grab status value

The `gtk.gdk.keyboard_grab`() function grabs the keyboard so that all events are passed to this application until the keyboard is ungrabbed with the `gtk.gdk.keyboard_ungrab`()) function. This overrides any previous keyboard grab by this client.

### gtk.gdk.keyboard_ungrab

        def gtk.gdk.keyboard_ungrab(time=0L)

`time` : | a timestamp from a `gtk.gdk.Event` or 0L to use the current time

The `gtk.gdk.keyboard_ungrab`() function ungrabs the keyboard if it is grabbed by this application.

### gtk.gdk.pointer_is_grabbed

        def gtk.gdk.pointer_is_grabbed()

Returns : | `True` if the pointer is currently grabbed by this application.

The `gtk.gdk.pointer_is_grabbed`() function returns `True` if the pointer is currently grabbed by this application. Note that this does not take the implicit pointer grab on button presses into account.

### gtk.gdk.flush

        def gtk.gdk.flush()

The `gtk.gdk.flush`() function flushes the X output buffer and waits until all requests have been processed by the server. This is rarely needed by applications.

### gtk.gdk.beep

        def gtk.gdk.beep()

The `gtk.gdk.beep`() function emits a short beep.

### gtk.gdk.set_double_click_time

        def gtk.gdk.set_double_click_time(msec)

`msec` : | the double click time in milliseconds

The `gtk.gdk.set_double_click_time`() function set the double click time for the default display. Applications should NOT set this, it is a global user-configured setting.

### gtk.gdk.threads_enter

        def gtk.gdk.threads_enter()

The `gtk.gdk.threads_enter`() function marks the beginning of a critical section that only one thread can operate within at a time. The critical section is guarded by a `GDK` mutual exclusion lock. Python threads are enabled while waiting for the `GDK` lock. See the `gtk.gtk.threads_init`() function for more information about threading.

### gtk.gdk.threads_leave

        def gtk.gdk.threads_leave()

The `gtk.gdk.threads_leave`() function marks the end of a critical section started by the `gtk.gdk.threads_enter`() function. See the `gtk.gtk.threads_init`() function for more information about threading.

### gtk.gdk.lock

    	  gtk.gdk.lock

The `gtk.gdk.lock` constant is a context manager that calls `gtk.gdk.threads_enter` and `gtk.gdk.threads_leave` in its `__enter__` and `__exit__` methods correspondingly. It is intended to be used in `with` statement, new in Python 2.5. Read statement description for details.

### gtk.gdk.threads_init

        def gtk.gdk.threads_init()

The `gtk.gdk.threads_init`() function initializes `PyGTK` to use the Python macros that allow multiple threads to serialize access to the Python interpreter (using the Python Global Interpreter Lock (GIL)). In addition, the `gtk.gdk.threads_init`() function initializes the `GDK` global lock (mutex) that serializes thread access to the `GTK` and `GDK` libraries. Thus there are two different global locking mechanisms at work that are initialized by the `gtk.gdk.threads_init`() function: Python and `GDK`.

The `gtk.gdk.threads_init`() function must be called before the `gtk.main`() function. At this point in the application the Python GIL is held by the main application thread. (Usually the main thread calls the `gtk.gdk.threads_init`() function though any thread could call it instead.) When the `gtk.main`() function is called the GIL is released and other threads may use the Python interpreter. When `PyGTK` signal handlers are invoked in the main thread the GIL is reacquired so that the Python interpreter can run the handler code.

### gtk.gdk.rgb_ditherable

        def gtk.gdk.rgb_ditherable()

Returns : | `True` if the `gtk.gdk.Visual` is ditherable

The `gtk.gdk.rgb_ditherable`() function returns `True` if the `gtk.gdk.Visual` is ditherable. This function may be useful for presenting a user interface choice to the user about which dither mode is desired; if the display is not ditherable, it may make sense to gray out or hide the corresponding UI widget.

### gtk.gdk.rgb_get_colormap

        def gtk.gdk.rgb_get_colormap()

Returns : | the preferred `gtk.gdk.Colormap` for rendering image data.

The `gtk.gdk.rgb_get_colormap`() function returns the preferred `gtk.gdk.Colormap`.

### gtk.gdk.rgb_set_verbose

        def gtk.gdk.rgb_set_verbose(verbose)

`verbose` : | If `True` messages should be verbose

The `gtk.gdk.rgb_set_verbose`() function sets the "verbose" flag to the value specified by `verbose`. If `verbose` is `True` messages will be verbose. This is generally only useful for debugging.

### gtk.gdk.rgb_set_install

        def gtk.gdk.rgb_set_install(install)

`install` : | if `True` set install mode

The `gtk.gdk.rgb_set_install`() function sets the "install" mode to the value of `install`. If `install` is `True`, a new "private" colormap is always installed rather than trying to find a best fit with the colors already allocated. Ordinarily, a colormap only be installed if a sufficient cube cannot be allocated. A private colormap has more colors, leading to better quality display, but also leads to the dreaded "colormap flashing" effect.

### gtk.gdk.rgb_set_min_colors

        def gtk.gdk.rgb_set_min_colors(min_colors)

`min_colors` : | the minimum number of colors.

The `gtk.gdk.rgb_set_min_colors`() function sets the minimum number of colors for the color cube to the value specified by `min_colors`. Generally, the largest color cube is allocated. If a color cube at least as large as `min_colors` can't be allocated, a private colormap is installed.

### gtk.gdk.rgb_get_visual

        def gtk.gdk.rgb_get_visual()

Returns : | the `gtk.gdk.Visual` being used

The `gtk.gdk.rgb_get_visual`() function returns the `gtk.gdk.Visual` being used to render image data on the default screen.

### gtk.gdk.selection_owner_get

        def gtk.gdk.selection_owner_get(selection)

`selection` : | an atom indentifying a selection.
Returns : | the `gtk.gdk.Window` that owns the selection or None.

The `gtk.gdk.selection_owner_get`() function returns the `gtk.gdk.Window` that owns the selection specified by `selection` if there is a selection owner for this window, and if it is a window known to the current application. Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call.

### gtk.gdk.selection_owner_get_for_display

        def gtk.gdk.selection_owner_get_for_display(display, selection)

`display` : | A `gtk.gdk.Display`.
`selection` : | an atom indentifying a selection.
Returns : | If there is a selection owner for this window, and it is a window known to the current process, the `gtk.gdk.Window` that owns the selection or `None`.

The `gtk.gdk.selection_owner_get_for_display`() function determine the owner of the given selection.

Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call.

### gtk.gdk.selection_owner_set_for_display

        def gtk.gdk.selection_owner_set_for_display(display, owner, selection, timw, send_event)

`display` : | A `gtk.gdk.Display`.
`owner` : | A `gtk.gdk.Window` or `None` to indicate that the owner for the given should be unset.
`selection` : | an atom indentifying a selection.
`time` : | timestamp to use when setting the selection. If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored.
`send_event` : | if `True`, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event.
Returns : | `True` if the selection owner was successfully changed to owner, otherwise `False`.

The `gtk.gdk.selection_owner_set_for_display`() function sets the `gtk.gdk.Window` owner as the current owner of the selection selection.

### gtk.gdk.selection_send_notify

        def gtk.gdk.selection_send_notify(requestor, selection, target, property, time)

`requestor` : | the integer ID of the window to deliver the response to.
`selection` : | an atom representing the selection that was requested.
`target` : | an atom representing the target that was selected.
`property` : | an atom representing the property in which the selection owner stored the data.
`time` : | a timestamp

The `gtk.gdk.selection_send_notify`() function sends a response to a SelectionRequest event.

### gtk.gdk.set_sm_client_id

        def gtk.gdk.set_sm_client_id(sm_client_id)

`sm_client_id` : | the client id string assigned by the session manager when the connection was opened

The `gtk.gdk.set_sm_client_id`() function 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.)

### gtk.gdk.notify_startup_complete

        def gtk.gdk.notify_startup_complete()

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.notify_startup_complete`() function indicates to the GUI environment that the application has finished loading. If the applications opens windows, this function is normally called after opening the application's initial set of windows.

GTK+ will call this function automatically after opening the first `gtk.Window` unless the `gtk.window_set_auto_startup_notification`() function is called to disable that feature.

### gtk.gdk.get_program_class

        def gtk.gdk.get_program_class()

Returns : | the program class

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.get_program_class`() function returns the program class. Unless the program class has explicitly been set with the `gtk.gdk.set_program_class`() function or with the `--class` commandline option, the default value is the program name with the first character converted to uppercase.

### gtk.gdk.set_program_class

        def gtk.gdk.set_program_class(program_class)

`program_class` : | a string containing the program class

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.set_program_class`() function sets the program class to the string contained in `program_class`. The `X11` backend uses the program class to set the class name part of the `WM_CLASS` property on toplevel windows.

### gtk.gdk.get_display

        def gtk.gdk.get_display()

Returns : | the name of the display

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.get_display`() function returns the name of the display, which is usually derived from the `DISPLAY` environment variable or the `--display` command line option.

### gtk.gdk.get_display_arg_name

        def gtk.gdk.get_display_arg_name()

Returns : | the display name, if specified explicitly, or `None`.

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.get_display_arg_name`() function returns the display name specified in the command line arguments, if any or `None` if the display name was not explicitly set.

### gtk.gdk.pango_context_get_for_screen

        def gtk.gdk.pango_context_get_for_screen(screen)

`screen` : | a `gtk.gdk.Screen`
Returns : | a new `pango.Context` object

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.pango_context_get_for_screen`() function creates a new `pango.Context` object for the `gtk.gdk.Screen` specified by `screen`. Normally you should use the `get_pango_context`() method instead of this function, to get the appropriate Pango context for the widget you intend to render text onto.

### gtk.gdk.pango_context_get

        def gtk.gdk.pango_context_get()

Returns : | a new `pango.Context` for the default display.

### Note

This function is available in PyGTK 2.8 and above

The `gtk.gdk.pango_context_get`() function creates a new `pango.Context` for the default display. Normally you should use the `get_pango_context`() method instead of this function, to get the appropriate Pango context for the widget you intend to render text onto.

### gtk.gdk.x11_display_get_startup_notification_id

        def gtk.gdk.x11_display_get_startup_notification_id(display)

`display` : | a `gtk.gdk.Display`
Returns : | the startup notification ID for `display`

### Note

This function is available in PyGTK 2.12 and above

The `gtk.gdk.x11_display_get_startup_notification_id`() function gets the startup notification ID for a display.

Prev | Up | Next
gtk.gdk.Window | Home | gtk.gdk Constants