gtk Functions

gtk Functions — miscellaneous functions


gtk.AccelGroup Functions

    def gtk.accelerator_valid(keyval, modifiers)

def gtk.accelerator_parse(accelerator)

def gtk.accelerator_name(accelerator_key, accelerator_mods)

def gtk.accelerator_set_default_mod_mask(default_mod_mask)

def gtk.accelerator_get_default_mod_mask()

def gtk.accelerator_get_label(accelerator_key, accelerator_mods)

def gtk.accel_groups_from_object(object)

gtk.AccelMap Functions

    def gtk.accel_map_add_entry(accel_path, accel_key, accel_mods)

def gtk.accel_map_lookup_entry(accel_path)

def gtk.accel_map_change_entry(accel_path, accel_key, accel_mods, replace)

def gtk.accel_map_foreach(foreach_func, data=None)

def gtk.accel_map_foreach_unfiltered(foreach_func, data=None)

def gtk.accel_map_get()

def gtk.accel_map_load(file_name)

def gtk.accel_map_save(file_name)

def gtk.accel_map_load_fd(fd)

def gtk.accel_map_save_fd(fd)

def gtk.accel_map_lock_path(accel_path)

def gtk.accel_map_unlock_path(accel_path)

def gtk.accel_map_add_filter(filter_pattern)

gtk.IconSource Functions

    def gtk.icon_size_lookup(icon_size)

def gtk.icon_size_lookup_for_settings(settings, icon_size)

def gtk.icon_size_register(name, width, height)

def gtk.icon_size_register_alias(alias, target)

def gtk.icon_size_from_name(name)

def gtk.icon_size_get_name(size)

gtk.Image Functions

    def gtk.image_new_from_stock(stock_id, size)

def gtk.image_new_from_icon_set(icon_set, size)

def gtk.image_new_from_animation(animation)

def gtk.image_new_from_icon_name(icon_name, size)

gtk.LinkButton Functions

    def gtk.link_button_set_uri_hook(func, data=None)

gtk.Object Functions

    def gtk.bindings_activate(object, keyval, modifiers)

def gtk.bindings_activate_event(object, event)

def gtk.binding_entry_add_signal(object, keyval, modifiers, signal_name, ...)

def gtk.binding_entry_remove(class_type, keyval, modifiers)

gtk.PaperSize Functions

    def gtk.paper_size_new_from_ppd(ppd_name, ppd_display_name, width, height)

def gtk.paper_size_new_cutom(name, display_name, width, height, unit)

def gtk.paper_size_get_default()

gtk.Plug Functions

    def gtk.plug_new_for_display(display, socket_id)

gtk.RcStyle Functions

    def gtk.rc_add_default_file(filename)

def gtk.rc_set_default_files(filenames)

def gtk.rc_get_default_files()

def gtk.rc_get_style_by_paths(settings, widget_path, class_path, type)

def gtk.rc_reparse_all_for_settings(settings, force_load)

def gtk.rc_reset_styles(settings)

def gtk.rc_parse(filename)

def gtk.rc_parse_string(rc_string)

def gtk.rc_reparse_all()

def gtk.rc_find_module_in_path(module_file)

def gtk.rc_get_theme_dir()

def gtk.rc_get_module_dir()

def gtk.rc_get_im_module_path()

def gtk.rc_get_im_module_file()

gtk.SelectionData Functions

    def gtk.selection_owner_set_for_display(display, widget, selection, time=0)

def gtk.target_list_add_image_targets(list=None, info=0, writable=False)

def gtk.target_list_add_text_targets(list=None, info=0)

def gtk.target_list_add_uri_targets(list=None, info=0)

gtk.Tooltips Functions

    def gtk.tooltips_data_get(widget)

Stock Item Functions

    def gtk.stock_add(items)

def gtk.stock_lookup(stock_id)

def gtk.stock_list_ids()

Miscellaneous Functions

    def gtk.check_version(required_major, required_minor, required_micro)

def gtk.draw_insertion_cursor(widget, drawable, area, location, is_primary, direction, draw_arrow)

def gtk.get_default_language()

def gtk.events_pending()

def gtk.main_do_event(event)

def gtk.main()

def gtk.main_level()

def gtk.main_quit()

def gtk.main_iteration(block)

def gtk.main_iteration_do(block)

def gtk.grab_get_current()

def gtk.quit_add(level, func, ...)

def gtk.quit_remove(quit_handler_id)

def gtk.get_current_event()

def gtk.get_current_event_state()

def gtk.get_current_event_time()

def gtk.init_check()

def gtk.remove_log_handlers()

def gtk.add_log_handlers()

def gtk.set_interactive(interactive)

def gtk.show_uri(screen, uri, timestamp)


All PyGTK functions for the gtk module are listed above categorized by class. Those functions associated with a class have their descriptions included with the class reference. Those functions that are not associated with a specific class are described below.



    def gtk.check_version(required_major, required_minor, required_micro)

required_major :

the required major version number

required_minor :

the required minor version number

required_micro :

the required micro version number

Returns :

None if the underlying GTK+ library is compatible or a string describing the mismatch

The gtk.check_version() function checks the underlying GTK+ library version against the version specified by required_major, required_minor and required_micro. If the library is compatible this function returns None; otherwise it returns a string describing the mismatch.


    def gtk.draw_insertion_cursor(widget, drawable, area, location, is_primary, direction, draw_arrow)

widget :

a gtk.Widget

drawable :

a gtk.gdk.Drawable

area :

the rectangle to which the output is clipped, or None if the output should not be clipped

location :

the location to draw the cursor (location.width is ignored)

is_primary :

if True the cursor should be the primary cursor color.

direction :

the direction of the cursor; either gtk.TEXT_DIR_LTR or gtk.TEXT_DIR_RTL

draw_arrow :

if True draw a directional arrow on the cursor. Should be False unless the cursor is split.


This function is available in PyGTK 2.4 and above.

The gtk.draw_insertion_cursor() function draws a text caret on the gtk.gdk.Drawable specified by drawable at the position specified by location. area specifies a clipping rectangle or is None if the output should not be clipped. If is_primary is True the cursor should be the primary cursor color. direction specifies whether the cursor is right-to-left or left-to-right. This is a convenience function for drawing the standard cursor shape.


    def gtk.get_default_language()

Returns :

a pango.Language object for the default language

The gtk.get_default_language() function returns a pango.Language describing the default language.


    def gtk.events_pending()

Returns :

True if any events are pending

The gtk.events_pending() function returns True if any events are pending. This can be used to update the user interface and invoke timeouts etc. while doing some time intensive computation.


    def gtk.main_do_event()

event :

a gtk.gdk.Event to process

The gtk.main_do_event() function processes a single gtk.gdk.Event. This function is public only to allow filtering of events between GDK and GTK+. You will not usually need to call this function directly. While you should not call this function directly, you might want to know how exactly events are handled. So here is what this function does with the event:

  1. Compress enter/leave notify events. If the event passed builds an enter-leave pair together with the next event (peeked from GDK) both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer.
  2. Find the widget which got the event. If the widget can't be determined the event is thrown away unless it belongs to a INCR transaction. In that case it is passed to gtk_selection_incr_event().
  3. Then the event is passed on a stack so you can query the currently handled event with gtk.get_current_event().
  4. The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the grab widget are sent to the latter with a few exceptions:

    • Deletion and destruction events are still sent to the event widget for obvious reasons.
    • Events which directly relate to the visual representation of the event widget.
    • Leave events are delivered to the event widget if there was an enter event delivered to it before without the paired leave event.
    • Drag events are not redirected because it is unclear what the semantics of that would be.

    Another point of interest might be that all key events are first passed through the key snooper functions if there are any. Read the description of gtk_key_snooper_install() if you need this feature.

  5. After finishing the delivery the event is popped from the event stack.


    def gtk.main()

The gtk.main() function runs the main loop until the gtk.main_quit() function is called. You can nest calls to gtk.main(). In that case the call to the gtk.main_quit() function will make the innermost invocation of the main loop return.


    def gtk.main_level()

Returns :

the nesting level of the current invocation of the main loop

The gtk.main_level() function returns the current nesting level of the main loop. The nesting level is increased by calling the gtk.main() function and reduced by calling the gtk.main_quit() function.


    def gtk.main_quit()

The gtk.main_quit() function terminates the current main loop level started by the most recent call to the gtk.main() function. The nesting level of the main loop is reduced by calling this function.


    def gtk.main_iteration(block=True)

block :

if True block if no events are pending

Returns :

True if the gtk.main_quit() function has been called for the innermost main loop.

The gtk.main_iteration() function runs a single iteration of the mainloop. If no events are waiting to be processed PyGTK will block until the next event is noticed if block is True. This function is identical to the gtk.main_iteration_do() function.


    def gtk.main_iteration_do(block=True)

block :

if True block if no events are pending

Returns :

True if the gtk.main_quit() function has been called for the innermost main loop.

The gtk.main_iteration_do() function runs a single iteration of the main loop. If block is True block until an event occurs. This function is identical to the gtk.main_iteration() function.


    def gtk.grab_get_current()

Returns :

the gtk.Widget that has the grab currently or None if no grab is active

The gtk.grab_get_current() function returns the gtk.Widget that has the grab or None if no grab is active.


    def gtk.quit_add(level, func, ...)

level :

the level at which termination func shall be called. You can pass 0 here to have func run at the termination of the current main loop.

func :

the function to call - it should return 0 to be removed from the list of quit handlers

... :

optional parameter(s) to be passed to func

Returns :

a handle for this quit handler (you need this for the gtk.quit_remove() function).

The gtk.quit_add() function registers a function specified by func to be called when the specified main loop level is exited. func should return 0 to be removed from the list of quit handlers. This function returns a handler ID that is used when removing the handler with the gtk.quit_remove() function.


    def gtk.quit_remove(quit_handler_id)

quit_handler_id :

the ID of a quit handler

The gtk.quit_remove() function removes the quit handler specified by quit_handler_id from the list of quit handlers.


    def gtk.get_current_event()

Returns :

a copy of the current event or None


This function is available in PyGTK 2.6 and above.

The gtk.get_current_event() function returns a copy of the event currently being processed by GTK+. For example, if you get a "clicked" signal from gtk.Button, the current event will be the GdkEventButton that triggered the "clicked" signal. If there is no current event, the function returns None.


    def gtk.get_current_event_state()

Returns :

the state of the current event if any or None if there is no current event or state


This function is available in PyGTK 2.6 and above.

The gtk.get_current_event_state() function returns the state of the current event or None if there is no current event or state.


    def gtk.get_current_event_time()

Returns :

the timestamp of the current event or 0L

The gtk.get_current_event_time() function returns the timestamp from the current event or 0L if there is no current event.


    def gtk.init_check()

Returns :

True if GTK has been successfully initialized

The gtk.init_check() function tries to initialize GTK and returns True if successful.


    def gtk.remove_log_handlers()


This function is available in PyGTK 2.10 and above.

The gtk.remove_log_handlers() function removes the default PyGTK log handlers,


    def gtk.add_log_handlers()


This function is available in PyGTK 2.10 and above.

The gtk.add_log_handlers() function installs the default PyGTK log handlers,


    def gtk.set_interactive(interactive)

interactive :

If True interactive usage is enabled


This function is available in PyGTK 2.16 and above.

The gtk.set_interactive() function can be used to enable or disable interactive usage of PyGTK. By default, interactive usage is switched on when importing gtk. You can then use PyGTK from the Python command prompt and see the results immediately without having to call gtk.main().


    def show_uri(screen, uri, timestamp)

screen :

A gtk.gdk.Screen to show the uri on or None for the default screen.

uri :

the uri to show.

timestamp :

a timestamp to prevent focus stealing.


This function is available in PyGTK 2.14 and above.

The show_uri() function is a convenience function for launching the default application to show the uri. The uri must be of a form understood by GIO. Typical examples are:


Ideally the timestamp is taken from the event triggering the gtk.show_uri() call. If timestamp is not known you can take gtk.gdk.CURRENT_TIME.

This function can be used as a replacement for gnome_vfs_url_show() and gnome_url_show().