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

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.