gtk Functions
Prev | The gtk Class Reference | Next

## gtk Functions

gtk Functions — miscellaneous functions

## Synopsis

### `gtk.AboutDialog` Functions

        def gtk.about_dialog_set_email_hook(func, data)
        def gtk.about_dialog_set_url_hook(func, data)

### `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.CellView` Functions

        def gtk.cell_view_new_with_text(text)
        def gtk.cell_view_new_with_markup(markup)
        def gtk.cell_view_new_with_pixbuf(pixbuf)

### `gtk.Clipboard` Functions

        def gtk.clipboard_get()

### `gtk.ColorSelection` Functions

        def gtk.color_selection_palette_from_string(str)
        def gtk.color_selection_palette_to_string(colors)

### `gtk.ComboBox` Functions

        def gtk.combo_box_new_text()

### `gtk.ComboBoxEntry` Functions

        def gtk.combo_box_entry_new_text()

### `gtk.ComboBoxText` Functions

        def gtk.combo_box_text_new_with_entry()

### `gtk.Container` Functions

        def gtk.container_class_install_child_property(klass, property_id, pspec)
        def gtk.container_class_list_child_properties(klass)

### `gtk.Dialog` Functions

        def gtk.alternative_dialog_button_order(screen=None)

### `gtk.Expander` Functions

        def gtk.expander_new_with_mnemonic(label)

### `gtk.IconFactory` Functions

        def gtk.icon_factory_lookup_default(stock_id)

### `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.IconTheme` Functions

        def gtk.icon_theme_get_default()
        def gtk.icon_theme_get_for_screen(screen)
        def gtk.icon_theme_add_builtin_icon(icon_name, size, pixbuf)

### `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.ItemFactory` Functions

        def gtk.item_factory_from_widget(widget)
        def gtk.item_factory_path_from_widget(widget)

### `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.RecentManager` Functions

        def gtk.recent_manager_get_default()
        def gtk.recent_manager_get_for_screen(screen)

### `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.Settings` Functions

        def gtk.settings_get_default()
        def gtk.settings_get_for_screen(screen)

### `gtk.StatusIcon` Functions

        def gtk.status_icon_new_from_pixbuf(pixbuf)
        def gtk.status_icon_new_from_file(filename)
        def gtk.status_icon_new_from_stock(stock_id)
        def gtk.status_icon_new_from_icon_name(icon_name)
        def gtk.status_icon_position_menu(menu, statusicon)

### `gtk.Tooltips` Functions

        def gtk.tooltips_data_get(widget)

### `gtk.TreeModel` Functions

        def gtk.tree_row_reference_inserted(proxy, path)
        def gtk.tree_row_reference_deleted(proxy, path)

### `gtk.Widget` Functions

        def gtk.widget_push_colormap(cmap)
        def gtk.widget_push_composite_child()
        def gtk.widget_pop_composite_child()
        def gtk.widget_pop_colormap()
        def gtk.widget_get_default_style()
        def gtk.widget_set_default_colormap(colormap)
        def gtk.widget_get_default_colormap()
        def gtk.widget_get_default_visual()
        def gtk.widget_set_default_direction(dir)
        def gtk.widget_get_default_direction()
        def gtk.widget_class_list_style_properties(widget)
        def gtk.widget_class_install_style_property(widget, pspec)

### `gtk.Window` Functions

        def gtk.window_set_default_icon(icon)
        def gtk.window_set_default_icon_from_file(filename)
        def gtk.window_set_default_icon_list(...)
        def gtk.window_get_default_icon_list()
        def gtk.window_set_auto_startup_notification(setting)
        def gtk.window_list_toplevels()
        def gtk.window_set_default_icon_name(name)

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

## Description

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.

## Functions

### gtk.check_version

        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.

### gtk.draw_insertion_cursor

        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.

### Note

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.

### gtk.get_default_language

        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.

### gtk.events_pending

        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.

### gtk.main_do_event

        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.

### gtk.main

        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.

### gtk.main_level

        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.

### gtk.main_quit

        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.

### gtk.main_iteration

        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.

### gtk.main_iteration_do

        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.

### gtk.grab_get_current

        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.

### gtk.quit_add

        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.

### gtk.quit_remove

        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.

### gtk.get_current_event

        def gtk.get_current_event()

Returns : | a copy of the current event or `None`

### Note

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

### gtk.get_current_event_state

        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

### Note

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.

### gtk.get_current_event_time

        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.

### gtk.init_check

        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.

### gtk.remove_log_handlers

        def gtk.remove_log_handlers()

### Note

This function is available in PyGTK 2.10 and above.

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

### gtk.add_log_handlers

        def gtk.add_log_handlers()

### Note

This function is available in PyGTK 2.10 and above.

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

### gtk.set_interactive

        def gtk.set_interactive(interactive)

`interactive` : | If `True` interactive usage is enabled

### Note

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

### gtk.show_uri

        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.

### Note

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:

    file:///home/gnome/pict.jpg
    http://www.gnome.org
    mailto:me@gnome.org

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

Prev | Up | Next
gtk.WindowGroup | Home | Stock Items