gtk.Widget
Prev | The gtk Class Reference | Next

## gtk.Widget

gtk.Widget — the base class for all `PyGTK` widgets

## Synopsis

    class gtk.Widget(gtk.Object):
        def get_allocation()
        def drag_check_threshold(start_x, start_y, current_x, current_y)
        def drag_get_data(context, target, time=0L)
        def drag_highlight()
        def drag_unhighlight()
        def drag_dest_set(flags, targets, actions)
        def drag_dest_set_proxy(proxy_window, protocol, use_coordinates)
        def drag_dest_unset()
        def drag_dest_find_target(context, target_list)
        def drag_dest_get_target_list()
        def drag_dest_set_target_list(target_list)
        def drag_dest_add_image_targets()
        def drag_dest_add_text_targets()
        def drag_dest_add_uri_targets()
        def drag_source_set(start_button_mask, targets, actions)
        def drag_source_unset()
        def drag_source_set_icon(colormap, pixmap, mask)
        def drag_source_set_icon_pixbuf(pixbuf)
        def drag_source_set_icon_stock(stock_id)
        def drag_source_set_icon_name(icon_name)
        def drag_source_add_text_targets()
        def drag_source_add_image_targets()
        def drag_source_add_uri_targets()
        def drag_begin(targets, actions, button, event)
        def grab_add()
        def grab_remove()
        def rc_get_style()
        def selection_owner_set(selection, time=0L)
        def selection_add_target(selection, target, info)
        def selection_add_targets(selection, targets)
        def selection_clear_targets(selection)
        def selection_convert(selection, target, time=0L)
        def selection_remove_all()
        def destroy()
        def unparent()
        def show()
        def show_now()
        def hide()
        def show_all()
        def hide_all()
        def set_no_show_all(no_show_all)
        def get_no_show_all()
        def map()
        def unmap()
        def realize()
        def unrealize()
        def queue_draw()
        def queue_draw_area(x, y, width, height)
        def queue_resize()
        def queue_resize_no_redraw()
        def size_request()
        def size_allocate(allocation)
        def get_child_requisition()
        def add_accelerator(accel_signal, accel_group, accel_key, accel_mods, accel_flags)
        def remove_accelerator(accel_group, accel_key, accel_mods)
        def set_accel_path(accel_path, accel_group)
        def can_activate_accel(signal_id)
        def mnemonic_activate(group_cycling)
        def event(event)
        def send_expose(event)
        def activate()
        def set_scroll_adjustments(hadjustment, vadjustment)
        def reparent(new_parent)
        def intersect(area)
        def region_intersect(region)
        def freeze_child_notify()
        def child_notify(child_property)
        def thaw_child_notify()
        def is_focus()
        def grab_focus()
        def grab_default()
        def set_name(name)
        def get_name()
        def set_state(state)
        def set_sensitive(sensitive)
        def set_app_paintable(app_paintable)
        def set_double_buffered(double_buffered)
        def set_redraw_on_allocate(redraw_on_allocate)
        def set_parent(parent)
        def set_parent_window(parent_window)
        def set_child_visible(is_visible)
        def get_child_visible()
        def get_parent()
        def get_parent_window()
        def child_focus(direction)
        def set_size_request(width, height)
        def get_size_request()
        def set_events(events)
        def add_events(events)
        def set_extension_events(mode)
        def get_extension_events()
        def get_toplevel()
        def get_ancestor(widget_type)
        def get_colormap()
        def get_visual()
        def get_screen()
        def has_screen()
        def get_display()
        def get_root_window()
        def get_settings()
        def get_clipboard(selection)
        def get_accessible()
        def set_colormap(colormap)
        def get_events()
        def get_pointer()
        def is_ancestor(ancestor)
        def translate_coordinates(dest_widget, src_x, src_y)
        def hide_on_delete()
        def set_style(style)
        def ensure_style()
        def get_style()
        def modify_style(style)
        def get_modifier_style()
        def modify_fg(state, color)
        def modify_bg(state, color)
        def modify_text(state, color)
        def modify_base(state, color)
        def modify_font(font_desc)
        def create_pango_context()
        def get_pango_context()
        def create_pango_layout(text)
        def render_icon(stock_id, size, detail=None)
        def set_composite_name(name)
        def get_composite_name()
        def reset_rc_styles()
        def style_get_property(property_name)
        def set_direction(dir)
        def get_direction()
        def shape_combine_mask(shape_mask, offset_x, offset_y)
        def reset_shapes()
        def path()
        def class_path()
        def list_mnemonic_labels()
        def add_mnemonic_label(label)
        def remove_mnemonic_label(label)
        def menu_get_for_attach_widget()
        def set_activate_signal(signal_name)
        def set_set_scroll_adjustments_signal(signal_name)
        def get_action()
        def drag_dest_set_track_motion(track_motion)
        def drag_dest_get_track_motion()
        def is_composited()
        def input_shape_combine_mask(shape_mask, offset_x, offset_y)
        def get_activate_signal()
        def error_bell()
        def get_has_tooltip()
        def get_tooltip_markup()
        def get_tooltip_text()
        def get_tooltip_window()
        def keynav_failed(direction)
        def modify_cursor(primary, secondary)
        def set_has_tooltip(has_tooltip)
        def set_tooltip_markup(markup)
        def set_tooltip_text(text)
        def set_tooltip_window(window)
        def trigger_tooltip_query()
        def get_snapshot(clip_rect)
        def get_window()

    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_find_style_property(widget, property_name)
        def gtk.widget_class_list_style_properties(widget)
        def gtk.widget_class_install_style_property(widget, pspec)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget

## Implemented Interfaces

`gtk.Widget` implements `gtk.Buildable`

## gtk.Widget Properties

gtk.Object Properties

"app-paintable" | Read-Write | If `True`, the application will paint directly on the widget
"can-default" | Read-Write | If `True`, the widget can be the default widget
"can-focus" | Read-Write | If `True`, the widget can accept the input focus
"composite-child" | Read-Write | If `True`, the widget is part of a composite widget
"events" | Read-Write | The event mask that decides what kind of `gtk.gdk.Event` this widget gets.
"extension-events" | Read-Write | The mask that decides what kind of extension events this widget gets.
"has-default" | Read-Write | If `True`, the widget is the default widget
"has-focus" | Read-Write | If `True`, the widget has the input focus
"has-tooltip" | Read-Write | Enables or disables the emission of GtkWidget::query-tooltip on widget. A value of `True` indicates that widget can have a tooltip, in this case the widget will be queried using GtkWidget::query-tooltip to determine whether it will provide a tooltip or not. Note that setting this property to `True` for the first time will change the event masks of the GdkWindows of this widget to include leave-notify and motion-notify events. This cannot and will not be undone when the property is set to `False` again. Default value: `False`. This property is available in GTK+ 2.12 and above.
"height-request" | Read-Write | The height request of the widget, or -1 if natural request should be used.
"is-focus" | Read-Write | If `True`, the widget is the focus widget within the toplevel
"name" | Read-Write | The name of the widget
"no-show-all" | Read-Write | If `True` `show_all`() should not affect this widget. Available in GTK+ 2.4 and above.
"parent" | Read-Write | The parent widget of this widget. Must be a `gtk.Container` widget.
"receives-default" | Read-Write | If `True`, the widget will receive the default action when it is focused.
"sensitive" | Read-Write | If `True`, the widget responds to input
"style" | Read-Write | The style of the widget, which contains information about how it will look (colors etc).
"tooltip-markup" | Read-Write | Sets the text of tooltip to be the given string, which is marked up with the Pango text markup language. Also see `gtk.Tooltip.set_markup().` This is a convenience property which will take care of getting the tooltip shown if the given string is not `None`: GtkWidget:has-tooltip will automatically be set to `True` and there will be taken care of GtkWidget::query-tooltip in the default signal handler. Default value: `None` This property is available in GTK+ 2.12 and above.
"tooltip-text" | Read-Write | Sets the text of tooltip to be the given string. Also see `gtk.Tooltip.set_text().` This is a convenience property which will take care of getting the tooltip shown if the given string is not `None`: GtkWidget:has-tooltip will automatically be set to `None` and there will be taken care of GtkWidget::query-tooltip in the default signal handler. Default value: `None`. This property is available in GTK+ 2.12 and above.
"visible" | Read-Write | If `True`, the widget is visible
"width-request" | Read-Write | The width request of the widget, or -1 if natural request should be used.

## gtk.Widget Style Properties

"cursor-aspect-ratio" | Read | The aspect ratio with which to draw the insertion cursor
"cursor-color" | Read | The `gtk.gdk.Color` with which to draw insertion cursor
"draw-border" | Read | The "draw-border" property defines the size of areas outside the widget's allocation to draw. This property is available in GTK+ 2.8 and above.
"focus-line-pattern" | Read-Write | The dash pattern used to draw the focus indicator.
"focus-line-width" | Read-Write | The width, in pixels, of the focus indicator line.
"focus-padding" | Read-Write | The width, in pixels, between the focus indicator and the widget 'box'.
"interior-focus" | Read | If `True`, draw the focus indicator inside widgets.
"link-color" | Read | The "link-color" property defines the color of unvisited links. This property is available in GTK+ 2.10 and above.
"scroll-arrow-hlength" | Read | The "scroll-arrow-hlength" property defines the length of horizontal scroll arrows. This property is available in GTK+ 2.10 and above.
"scroll-arrow-vlength" | Read | The "scroll-arrow-vlength" property defines the length of vertical scroll arrows. This property is available in GTK+ 2.10 and above.
"secondary-cursor-color" | Read | The `gtk.gdk.Color` with which to draw the secondary insertion cursor when editing mixed right-to-left and left-to-right text.
"separator-height" | Read | The "separator-height" property defines the height of separators. This property only takes effect if "wide-separators" is `True`. This property is available in GTK+ 2.10 and above.
"separator-width" | Read | The "separator-width" property defines the width of separators. This property only takes effect if "wide-separators" is `True`. This property is available in GTK+ 2.10 and above.
"visited-link-color" | Read | The "visited-link-color" property defines the color of visited links. This property is available in GTK+ 2.10 and above.
"wide-separators" | Read | The "wide-separators" property defines whether separators have configurable width and should be drawn using a box instead of a line. This property is available in GTK+ 2.10 and above.
"window" | Read | The "window" property is the widget's window if it is realized, `None` otherwise. This property is available in GTK+ 2.14 and above.

## Attributes

"allocation" | Read-Write | The `gtk.gdk.Rectangle` specifying the widget's space allocation. This attribute is writeable in PyGTK 2.4.
"name" | Read | The name of the widget
"parent" | Read | The parent widget of this widget. Must be a `gtk.Container` widget.
"saved_state" | Read | The widget's saved state.
"state" | Read | The widget state: `gtk.STATE_NORMAL`, `gtk.STATE_ACTIVE`, `gtk.STATE_PRELIGHT`, `gtk.STATE_SELECTED` or `gtk.STATE_INSENSITIVE`
"style" | Read | The style of the widget.
"window" | Read-Write | The `gtk.gdk.Window` used by the widget. This attribute is writeable in PyGTK 2.4.

## gtk.Widget Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

"accel-closures-changed" | `def callback(`widget`, `user_param1`, `...`)`
"button-press-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"button-release-event" | `def callback(`widget`, `signal_id`, `user_param1`, `...`)`
"can-activate-accel" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"child-notify" | `def callback(`widget`, `child_property`, `user_param1`, `...`)`
"composited-changed | `def callback(`widget`, `user_param1`, `...`)`
"client-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"configure-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"delete-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"delete-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"destroy-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"direction-changed" | `def callback(`widget`, `direction`, `user_param1`, `...`)`
"drag-begin" | `def callback(`widget`, `drag_context`, `user_param1`, `...`)`
"drag-data-delete" | `def callback(`widget`, `drag_context`, `user_param1`, `...`)`
"drag-data-get" | `def callback(`widget`, `drag_context`, `selection_data`, `info`, `timestamp`, `user_param1`, `...`)`
"drag-data-received" | `def callback(`widget`, `drag_context`, `x`, `y`, `selection_data`, `info`, `timestamp`, `user_param1`, `...`)`
"drag-drop" | `def callback(`widget`, `drag_context`, `x`, `y`, `timestamp`, `user_param1`, `...`)`
"drag-end" | `def callback(`widget`, `drag_context`, `user_param1`, `...`)`
"drag-failed" | `def callback(`widget`, `drag_context`, `result`, `user_param1`, `...`)`
"drag-leave" | `def callback(`widget`, `drag_context`, `timestamp`, `user_param1`, `...`)`
"drag-motion" | `def callback(`widget`, `drag_context`, `x`, `y`, `timestamp`, `user_param1`, `...`)`
"enter-notify-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"event-after" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"expose-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"focus" | `def callback(`widget`, `direction`, `user_param1`, `...`)`
"focus-in-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"focus-out-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"grab-broken-event | `def callback(`widget`, `event`, `user_param1`, `...`)`
"grab-focus" | `def callback(`widget`, `user_param1`, `...`)`
"grab-notify" | `def callback(`widget`, `was_grabbed`, `user_param1`, `...`)`
"hide" | `def callback(`widget`, `user_param1`, `...`)`
"hierarchy-changed" | `def callback(`widget`, `previous_toplevel`, `user_param1`, `...`)`
"key-press-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"key-release-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"keynav-failed" | `def callback(`widget`, `direction`, `user_param1`, `...`)`
"leave-notify-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"map" | `def callback(`widget`, `user_param1`, `...`)`
"map-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"mnemonic-activate" | `def callback(`widget`, `group_cycling`, `user_param1`, `...`)`
"motion-notify-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"no-expose-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"parent-set" | `def callback(`widget`, `old_parent`, `user_param1`, `...`)`
"popup-menu" | `def callback(`widget`, `user_param1`, `...`)`
"property-notify-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"proximity-in-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"proximity-out-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"query-tooltip" | `def callback(`widget`, `x`, `y`, `keyboard_mode`, `tooltip`, `user_param1`, `...`)`
"realize" | `def callback(`widget`, `user_param1`, `...`)`
"screen-changed" | `def callback(`widget`, `screen`, `user_param1`, `...`)`
"scroll-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"selection-clear-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"selection-get" | `def callback(`widget`, `selection_data`, `info`, `timestamp`, `user_param1`, `...`)`
"selection-notify-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"selection-received" | `def callback(`widget`, `selection_data`, `timestamp`, `user_param1`, `...`)`
"selection-request-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"show" | `def callback(`widget`, `user_param1`, `...`)`
"show-help" | `def callback(`widget`, `help_type`, `user_param1`, `...`)`
"size-allocate" | `def callback(`widget`, `allocation`, `user_param1`, `...`)`
"size-request" | `def callback(`widget`, `requisition`, `user_param1`, `...`)`
"state-changed" | `def callback(`widget`, `state`, `user_param1`, `...`)`
"style-set" | `def callback(`widget`, `previous_style`, `user_param1`, `...`)`
"unmap" | `def callback(`widget`, `user_param1`, `...`)`
"unmap-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"unrealize" | `def callback(`widget`, `user_param1`, `...`)`
"visibility-notify-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`
"window-state-event" | `def callback(`widget`, `event`, `user_param1`, `...`)`

## Description

The `gtk.Widget` class is the base class for all `PyGTK` widgets. It provides the common set of method and signals for the widgets including:

- drag and drop setting and management methods
- selection methods
- methods to realize, map and show widgets
- methods to manage size allocation and requests
- methods to initiate widget redrawing
- methods to deal with the widget's place in the widget hierarchy
- event management methods
- methods to modify the style settings
- methods to access the default resources

`gtk.Widget` introduces style properties - these are basically object properties that are stored not on the object, but in the style object associated to the widget. Style properties are set in resource files. This mechanism is used for configuring such things as the location of the scrollbar arrows through the theme, giving theme authors more control over the look of applications without the need to write a theme engine in C.

Use the `gtk.widget_class_install_style_property`() function to install style properties for a widget class, the `gtk.widget_class_find_style_property`() function or the `gtk.widget_class_list_style_properties`() function to get information about existing style properties and the `style_get_property`() method to obtain the value of a style property.

## Methods

### gtk.Widget.get_allocation

        def get_allocation()

Returns : | a `gtk.gdk.Rectangle`

The `get_allocation`() method returns a `gtk.gdk.Rectangle` containing the bounds of the widget's allocation.

### gtk.Widget.drag_check_threshold

        def drag_check_threshold(start_x, start_y, current_x, current_y)

`start_x` : | the X coordinate of start of drag
`start_y` : | the Y coordinate of start of drag
`current_x` : | the current X coordinate
`current_y` : | the current Y coordinate
Returns : | `True` if the drag threshold has been passed.

The check_drag_threshold() method checks to see if a mouse drag starting at (`start_x`, `start_y`) and ending at (`current_x`, `current_y`) has passed the+ drag threshhold distance, and thus should trigger the beginning of a drag-and-drop operation.

### gtk.Widget.drag_get_data

        def drag_get_data(context, target, time=0L)

`context` : | a `gtk.gdk.DragContext`
`target` : | an atom
`time` : | a timestamp or 0L to specify the current time

The `drag_get_data`() method gets the data associated with a drag specified by `drag_context` and `target`. When the data is received or the retrieval fails, a "drag_data_received" signal will be emitted. Failure of the retrieval is indicated by the length field of the `gtk.SelectionData` being negative. However, when the `drag_get_data`() method is called implicitly because `gtk.DRAG_DEFAULT_DROP` was set, the widget will not receive notification of failed drops.

### gtk.Widget.drag_highlight

        def drag_highlight()

The `drag_highlight`() method draws a highlight around a widget. This will attach handlers to "expose_event" and "draw", so the highlight will continue to be displayed until the `drag_unhighlight`() method is called.

### gtk.Widget.drag_unhighlight

        def drag_unhighlight()

The `drag_unhighlight`() method removes the highlight that was set by the `drag_highlight`() method.

### gtk.Widget.drag_dest_set

        def drag_dest_set(flags, targets, actions)

`flags` : | the flags that specify what actions should be taken on behalf of a widget for drops onto that widget. The targets and actions fields only are used if `gtk.DEST_DEFAULT_MOTION` or `gtk.DEST_DEFAULT_DROP` are given.
`targets` : | a sequence of target tuples
`actions` : | a bitmask of possible actions for a drop onto this widget.

The `drag_dest_set`() method sets up a widget as a potential drag drop destination. The value of `flags` is a combination of the GTK Dest Defaults Constants.

`targets` is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

The value of `actions` is one of the GDK Drag Action Constants.

### gtk.Widget.drag_dest_set_proxy

        def drag_dest_set_proxy(proxy_window, protocol, use_coordinates)

`proxy_window` : | the `gtk.gdk.Window` to forward drag events to
`protocol` : | the drag protocol that `proxy_window` accepts
`use_coordinates` : | if `True`, send the same coordinates to the destination, because it is an embedded subwindow.

The `drag_dest_set_proxy`() method sets a proxy `gtk.gdk.Window` specified by `proxy_window` that drag events are forwarded to on behalf of the widget. The value of `protocol` is one of the GDK Drag Protocol Constants.

If `use_coordinates` is `True`, the same coordinates are sent to the destination because the widget's an embedded subwindow.

### gtk.Widget.drag_dest_unset

        def drag_dest_unset()

The `drag_dest_unset`() method clears the information about a drop destination set with the `drag_dest_set`() method. The widget will no longer receive notification of drags.

### gtk.Widget.drag_dest_find_target

        def drag_dest_find_target(context, target_list)

`context` : | the drag context
`target_list` : | a list of droppable targets, or `None`.
Returns : | the first target that the source offers and the dest can accept, or `None`

The `dest_find_target`() method looks for a match between the targets in the `gtk.gdk.DragContext` specified by `context` and the `target_list`, returning the first matching target, or `NONE` if no match is found. The list specified by `target_list` should usually be the return value from the `drag_dest_get_target_list`() method, but some widgets may have different valid targets for different parts of the widget; in that case, they will have to implement a "drag-motion" handler that passes the correct target list to this method. `target_list` is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

### gtk.Widget.drag_dest_get_target_list

        def drag_dest_get_target_list()

Returns : | the list of targets or `None` if no targets are set

The `drag_dest_get_target_list`() method returns the list of targets this widget can accept from drag-and-drop. The returned value is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

### gtk.Widget.drag_dest_set_target_list

        def drag_dest_set_target_list(target_list)

`target_list` : | a list of droppable targets, or `None`

The `drag_dest_set_target_list`() method sets the target types (that this widget can accept from drag-and-drop) to the list specified by `target_list`. The widget must first be made into a drag destination with the `drag_dest_set()` method. `target_list` is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

### gtk.Widget.drag_dest_add_image_targets

        def drag_dest_add_image_targets()

### Note

This method is available in PyGTK 2.6 and above.

The `drag_dest_add_image_targets`() method adds the image targets supported by `gtk.SelectionData` to the target list of the widget's drag destination using an info value of 0.

### gtk.Widget.drag_dest_add_text_targets

        def drag_dest_add_text_targets()

### Note

This method is available in PyGTK 2.6 and above.

The `drag_dest_add_text_targets`() method adds the text targets supported by `gtk.SelectionData` to the target list of the widget's drag destination using an info value of 0.

### gtk.Widget.drag_dest_add_uri_targets

        def drag_dest_add_uri_targets()

### Note

This method is available in PyGTK 2.6 and above.

The `drag_dest_add_uri_targets`() method adds the URI targets supported by `gtk.SelectionData` to the target list of the widget's drag destination using an info value of 0.

### gtk.Widget.drag_source_set

        def drag_source_set(start_button_mask, targets, actions)

`start_button_mask` : | the bitmask of buttons that can start the drag
`targets` : | a list of targets that the drag will support
`actions` : | the possible actions for a drag from this widget.

The `drag_source_set`() method sets up the widget to start a drag operation when the user clicks and drags on the widget. The widget must have a window. The value of start_button_mask is a combination of the GDK Modifier Constants.

`targets` is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

The value of `actions` is one of the GDK Drag Action Constants:

### gtk.Widget.drag_source_unset

        def drag_source_unset()

The `drag_source_unset`() method unsets the drag source for the widget that was set up by the `drag_source_set`() method.

### gtk.Widget.drag_source_set_icon

        def drag_source_set_icon(colormap, pixmap, mask=None)

`colormap` : | the colormap of the icon
`pixmap` : | the image data for the icon
`mask` : | the transparency mask for an image.

The `drag_source_set_icon`() method sets the icon that will be used for drags from the widget using the specified `pixmap` and `mask`. `colormap` specifies the colormap to be used to create the icon. The `drag_source_set_icon_pixbuf`() method should be used instead of this method.

### gtk.Widget.drag_source_set_icon_pixbuf

        def drag_source_set_icon_pixbuf(pixbuf)

`pixbuf` : | the `gtk.gdk.Pixbuf` for the drag icon

The `drag_source_set_icon_pixbuf`() method sets the icon that will be used for drags from the widget from the `gtk.gdk.Pixbuf` specified by `pixbuf`.

### gtk.Widget.drag_source_set_icon_stock

        def drag_source_set_icon_stock(stock_id)

`stock_id` : | the ID of the stock icon to use

The `drag_source_set_icon_stock`() method sets the icon that will be used for drags from a particular source using the stock icon specified by `stock_id`.

### gtk.Widget.drag_source_set_icon_name

        def drag_source_set_icon_name(icon_name)

`icon_name` : | the name of a themed icon use

### Note

This method is available in PyGTK 2.10 and above.

The `drag_source_set_icon_name`() method sets the icon that will be used for drags from a particular source using the themed icon specified by `icon_name`. See the `gtk.IconTheme` docs for more information.

### gtk.Widget.drag_source_get_target_list

        def drag_source_get_target_list()

Returns : | the list of targets or `None` if no targets are set

### Note

This method is available in PyGTK 2.6 and above.

The `drag_source_get_target_list`() method returns the list of targets this widget can provide for drag-and-drop. The returned value is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

### gtk.Widget.drag_source_set_target_list

        def drag_source_set_target_list(target_list)

`target_list` : | a list of droppable targets, or `None`

### Note

This method is available in PyGTK 2.6 and above.

The `drag_source_set_target_list`() method sets the target types (that this widget can provide for drag-and-drop) to the list specified by `target_list`. The widget must first be made into a drag source with the `drag_source_set()` method. `target_list` is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

### gtk.Widget.drag_source_add_text_targets

        def drag_source_add_text_targets()

### Note

This method is available in PyGTK 2.6 and above.

The `drag_source_add_text_targets`() method adds the text targets supported by `gtk.SelectionData` to the target list of the widget's drag source using an info value of 0. If you need another value for info, use the `gtk.target_list_add_text_targets`() function and the `drag_source_set_target_list`() method.

### gtk.Widget.drag_source_add_image_targets

        def drag_source_add_image_targets()

### Note

This method is available in PyGTK 2.10 and above.

The `drag_source_add_image_targets`() method adds the image targets supported by `gtk.SelectionData` to the target list of the widget's drag source using an info value of 0. If you need another value for info, use the `gtk.target_list_add_image_targets`() function and the `drag_source_set_target_list`() method.

### gtk.Widget.drag_source_add_uri_targets

        def drag_source_add_uri_targets()

### Note

This method is available in PyGTK 2.10 and above.

The `drag_source_add_uri_targets`() method adds the URI targets supported by `gtk.SelectionData` to the target list of the widget's drag source using an info value of 0. If you need another value for info, use the `gtk.target_list_add_image_targets`() function and the `drag_source_set_target_list`() method.

### gtk.Widget.drag_begin

        def drag_begin(targets, actions, button, event)

`targets` : | the list of targets supported by the widget drag
`actions` : | the allowed drag operations for the drag
`button` : | the button the user pressed to start the drag
`event` : | the `gtk.gdk.Event` that triggered the drag
Returns : | a new `gtk.gdk.DragContext`

The `drag_begin`() method starts a drag on the source side. The method only needs to be used when the application is starting drags itself, and is not needed when the `drag_source_set`() method is used. `targets` is a sequence (list or tuple) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

The value of `actions` is one of the GDK Drag Action Constants.

`button` is the button that the user pressed to start the drag operation. `event` is the `gtk.gdk.Event` that triggered the start of the drag operation (the button press). This method returns the `gtk.gdk.DragContext` for the drag operation.

### gtk.Widget.grab_add

        def grab_add()

The `grab_add`() method makes the widget the current grabbed widget. This means that interaction with other widgets in the same application is blocked and mouse as well as keyboard events are delivered to this widget.

### gtk.Widget.grab_remove

        def grab_remove()

The `grab_remove`() method removes the grab from the widget. You have to pair calls to the `grab_add`() and `grab_remove`() methods.

### gtk.Widget.rc_get_style

        def rc_get_style()

Returns : | the resulting style.

The `rc_get_style`() method finds all matching RC styles for the widget, composites them together, and then creates a `gtk.Style` representing the composite appearance.

### gtk.Widget.selection_owner_set

        def selection_owner_set(selection, time=0L)

`selection` : | an atom representing the selection to claim
`time` : | a timestamp or 0L to use the current time
Returns : | `True` if successful

The `selection_owner_set`() method claims the ownership of the selection specified by `selection` for the widget.

### gtk.Widget.selection_add_target

        def selection_add_target(selection, target, info)

`selection` : | an atom representing the selection
`target` : | an atom representing the target for the selection
`info` : | an integer ID that will be passed to the application

The `selection_add_target`() method adds the specified `target` to the list of supported targets for the specified `selection`. `info` is an integer ID that will be passed to the application when the "selection-get" handler is called.

### gtk.Widget.selection_add_targets

        def selection_add_targets(selection, targets)

`selection` : | an atom representing the selection
`targets` : | a sequence of 3-tuples containing target data

The `selection_add_targets`() method adds the list of targets (specified by `targets`) to the list of supported targets for the specified `selection`. targets is a sequence (Python tuple or list) of 3-tuples that contain information about the targets. The target data contains a string representing the drag type, target flags (a combination of `gtk.TARGET_SAME_APP` and `gtk.TARGET_SAME_WIDGET` or neither) and an application assigned integer ID used for identification purposes.

### gtk.Widget.selection_clear_targets

        def selection_clear_targets(selection)

`selection` : | an atom representing a selection

The `selection_clear_targets`() method remove all targets registered for the specified `selection` for the widget.

### gtk.Widget.selection_convert

        def selection_convert(selection, target, time=0L)

`selection` : | an atom specifying the selection
`target` : | an atom specifying the target type
`time` : | a timestamp for the request or 0L to use the current time
Returns : | `True` if the request succeeded

The `selection_convert`() method requests the contents of the specified `selection` for the specified `target` type. When received, a "selection_received" signal will be generated.

### gtk.Widget.selection_remove_all

        def selection_remove_all()

The `selection_remove_all`() method removes all handlers and unsets ownership of all selections for a widget. This method is called when widget is being destroyed and not usually by applications.

### gtk.Widget.destroy

        def destroy()

The `destroy`() method destroys the widget. When a widget is destroyed, it will break any references it holds to other objects. If the widget is inside a container, the widget will be removed from the container. If the widget is a toplevel (derived from `gtk.Window`), it will be removed from the list of toplevels, and the reference `PyGTK` holds to it will be removed. Removing a widget from its container or the list of toplevels results in the widget being finalized. In most cases, only toplevel widgets (windows) require explicit destruction, because when you destroy a toplevel its children will be destroyed as well.

### gtk.Widget.unparent

        def unparent()

The `unparent`() method is only for use in widget implementations. It should be called by implementations of the remove method on a `gtk.Container`, to dissociate a child widget from the container.

### gtk.Widget.show

        def show()

The `show`() method causes a widget to be displayed as soon as practical. Any widget that isn't shown will not appear on the screen. If you want to show all the widgets in a container, it's easier to call the `show_all`() on the container, instead of individually showing the widgets. Of course you have to show the containers containing a widget, as well as the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped.

### gtk.Widget.show_now

        def show_now()

The `show_now`() method is the same as the `show`() method except if the widget is an unmapped toplevel widget (i.e. a `gtk.Window` that has not yet been shown), it enters the main loop and waits for the window to actually be mapped.

### Note

Because the main loop is running, anything can happen during this method.

### gtk.Widget.hide

        def hide()

The `hide`() method reverses the effects of the `show`() method, causing the widget to be hidden (removed from the display) by unmapping it.

### gtk.Widget.show_all

        def show_all()

The `show_all`() method recursively shows the widget, and any child widgets (if the widget is a container).

### gtk.Widget.hide_all

        def hide_all()

The `hide_all`() method recursively hides the widget and its child widgets (if any).

### gtk.Widget.set_no_show_all

        def set_no_show_all(no_show_all)

`no_show_all` : | the new value for the "no_show_all" property

### Note

This method is available in PyGTK 2.4 and above.

The `set_no_show_all`() method sets the "no_show_all" property to the value of `no_show_all`. If `no_show_all` is `True` calls to the `show_all()` and `hide_all()` methods will not affect this widget.

This method is mostly for use in constructing widget hierarchies with externally controlled visibility, see the `gtk.UIManager` reference for mote information.

### gtk.Widget.get_no_show_all

        def get_no_show_all()

Returns : | the current value of the "no_show_all" property.

### Note

This method is available in PyGTK 2.4 and above.

The `get_no_show_all`() method returns the current value of the "no_show_all" property. If "no-show-all" is `True` calls to the `show_all()` and `hide_all()` methods will not affect the widget.

### gtk.Widget.map

        def map()

The `map`() method maps the widget (causes it to be displayed). This method will also cause the widget to be realized if it is not currently realized. This method is usually not used by applications.

### gtk.Widget.unmap

        def unmap()

The `unmap`() method unmaps the widget (causes it to be removed from the display). This method is not usually used by applications.

### gtk.Widget.realize

        def realize()

The `realize`() method creates the resources associated with a widget. For example, the widget `gtk.gdk.Window` will be created when the widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget's parent widgets to be realized; calling the `realize`() method realizes the widget's parents in addition to the widget itself. A widget must be inside a toplevel window when you realize it. This method is primarily used in widget implementations, and not in applications. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as "expose_event". Or simply using the `gobject.connect_after`() method to add a handler to the "realize" signal.

### gtk.Widget.unrealize

        def unrealize()

The `unrealize`() method frees all resources associated with the widget, such as the `gtk.gdk.Window`.

### gtk.Widget.queue_draw

        def queue_draw()

The `queue_draw`() method is equivalent to calling the `queue_draw_area`() method for the entire area of a widget.

### gtk.Widget.queue_draw_area

        def queue_draw_area(x, y, width, height)

`x` : | the x coordinate of upper-left corner of rectangle to redraw
`y` : | the y coordinate of upper-left corner of rectangle to redraw
`width` : | the width of rectangle to redraw
`height` : | the height of rectangle to redraw

The `queue_draw_area`() method invalidates the rectangular area of the widget specified by `x`, `y`, `width` and `height` by calling the `gtk.gdk.Window.invalidate_rect`() method on the widget's window and all its child windows. Once the main loop becomes idle (after the current batch of events has been processed, roughly), the window will receive expose events for the union of all regions that have been invalidated.

Normally you would only use this method in widget implementations. But you might also use it, or the `gtk.gdk.Window.invalidate_rect`() method directly, to schedule a redraw of a `gtk.DrawingArea` or some portion thereof. Frequently you can just call the `gtk.gdk.Window.invalidate_rect`() method instead of this method. This method will invalidate only a single window, instead of the widget and all its children. The advantage of adding to the invalidated region compared to simply drawing immediately is efficiency; using an invalid region ensures that you only have to redraw one time.

### gtk.Widget.queue_resize

        def queue_resize()

The `queue_resize`() method schedules the widget to have its size renegotiated. This method should be called when a widget for some reason has a new size request. For example, when you change the text in a `gtk.Label`, a resize is queued to ensure there's enough space for the new text.

### gtk.Widget.queue_resize_no_redraw

        def queue_resize_no_redraw()

### Note

This method is available in PyGTK 2.4 and above.

The `queue_resize_no_redraw`() method works like the `queue_resize()` method, except that the widget is not invalidated.

### gtk.Widget.size_request

        def size_request()

Returns : | a tuple containing the widget's required width and height.

The `size_request`() method returns the preferred size of a widget as a tuple containing its required width and height. This method is typically used when implementing a `gtk.Container` subclass to arrange the container's child widgets and decide what size allocations to give them with the `size_allocate`() method. Obtaining a size request requires that the widget be associated with a screen, because font information may be needed.

Also remember that the size request is not necessarily the size a widget will actually be allocated.

See the `get_child_requisition`() method.

### gtk.Widget.size_allocate

        def size_allocate(allocation)

`allocation` : | the position and size to be allocated to the widget

The `size_allocate`() method sets a size allocation for the widget using the `gtk.gdk.Rectangle` specified by `allocation`. This method is only used by `gtk.Container` subclasses, to assign a size and position to their child widgets.

### gtk.Widget.get_child_requisition

        def get_child_requisition()

Returns : | a tuple containing the required size of the widget

The `get_child_requisition`() method returns a tuple containing the widget requisition width and height. This method is only for use in widget container implementations since it obtains the widget requisition directly. By comparison the `size_request`() method actually computes the size request and fills in the widget requisition before returning. Because this method does not recalculate the size request, it can only be used when you know that the widget requisition is up-to-date, i.e. the `size_request`() method has been called since the last time a resize was queued. In general, only container implementations have this information; applications should use the `size_request`() method instead.

### gtk.Widget.add_accelerator

        def add_accelerator(accel_signal, accel_group, accel_key, accel_mods, accel_flags)

`accel_signal` : | the widget signal to emit on accelerator activation
`accel_group` : | the accel group for this widget, added to its toplevel
`accel_key` : | the keyval of the accelerator e.g. `ord('q')`
`accel_mods` : | the modifier key combination of the accelerator
`accel_flags` : | the flag accelerators, e.g. `gtk.ACCEL_VISIBLE`

The `add_accelerator`() method installs an accelerator for the widget in `accel_group` that causes `accel_signal` to be emitted if the accelerator is activated. The accelerator key and modifiers are specified by `accel_key` and `accel_mods` respectively. `accel_mods` should be a combination of the GDK Modifier Constants. `accel_flags` is a combination of `gtk.ACCEL_VISIBLE` and `gtk.ACCEL_LOCKED` (see the GTK Accel Flags Constants). The `accel_group` needs to be added to the widget's toplevel via the `gtk.Window.add_accel_group`() method and the signal specified by `accel_signal` must have signal flags that include the `gobject.SIGNAL_ACTION` flag (see the GObject Signal Flag Constants for more information). Accelerators added through this method are not user changeable during runtime. If you want to support accelerators that can be changed by the user, the `set_accel_path`() or `gtk.MenuItem.set_accel_path`() methods instead.

### gtk.Widget.remove_accelerator

        def remove_accelerator(accel_group, accel_key, accel_mods)

`accel_group` : | the accel group for this widget
`accel_key` : | the keyval of the accelerator
`accel_mods` : | the modifier key combination of the accelerator
Returns : | `True` if the accelerator was removed

The `remove_accelerator`() method removes the accelerator specified by `accel_key` and `accel_mods` from the widget's accelerator group (specified by `accel_group`), previously installed with the `add_accelerator`() method.

### gtk.Widget.set_accel_path

        def set_accel_path(accel_path, accel_group)

`accel_path` : | the path used to look up the the accelerator
`accel_group` : | a `gtk.AccelGroup`.

The `set_accel_path`() method sets an accelerator (using the key bindings defined in `accel_path`) in the accelerator group specified by `accel_group`. This method removes any accelerators for any accelerator group installed by previous calls to the `set_accel_path`() method. Associating accelerators with paths allows them to be modified by the user and the modifications to be saved for future use. This method is a low level method that would most likely be used by a menu creation system like `gtk.ItemFactory`. If you use `gtk.ItemFactory`, setting up accelerator paths will be done automatically. Even when you you aren't using `gtk.ItemFactory`, if you only want to set up accelerators on menu items the `gtk.MenuItem.set_accel_path`() method provides a somewhat more convenient interface.

### gtk.Widget.can_activate_accel

        def can_activate_accel(signal_id)

`signal_id` : | the ID of an installed signal
Returns : | `True` if the accelerator can be activated.

### Note

This method is available in PyGTK 2.4 and above.

The `can_activate_accel`() method returns `True` if an accelerator that activates the signal specified by `signal_id` can currently be activated. This is done by emitting the "can-activate-accel" signal. If the signal isn't overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped.

### gtk.Widget.mnemonic_activate

        def mnemonic_activate(group_cycling)

`group_cycling` : | if True grab the focus instead of activating the widget
Returns : | True if the signal was handled

The`mnemonic_activate`() method emits the "mnemonic-activate" signal on the widget and returns `True` if the signal was handled. `group_cycling` is `True` if the focus is being shifted to the widget and `False` if the widget should be activated.

### gtk.Widget.event

        def event(event)

`event` : | a `gtk.gdk.Event`
Returns : | `True` if the event was handled

The `event`() method emits the event signals on a widget (those signals should never be emitted without using this method to do so). If you want to synthesize an event though, don't use this method; instead, use the `gtk.main_do_event`() function so the event will behave as if it were in the event queue. Don't synthesize expose events; instead, use the `gtk.gdk.Window.invalidate_rect`() method to invalidate a region of the window.

### gtk.Widget.send_expose

        def send_expose(event)

`event` : | an expose `gtk.gdk.Event`
Returns : | `True` if the event was handled

The `send_expose`() method emits an expose event signal on a widget. This method is usually used when propagating an expose event to a child `NO_WINDOW` widget, and that is normally done using the `gtk.Container.propagate_expose`() method. If you want to force an area of a window to be redrawn, use the `gtk.gdk.Window.invalidate_rect`() method. To cause the redraw to be done immediately, follow that call with a call to the `gtk.gdk.Window.process_updates`() method.

### gtk.Widget.activate

        def activate()

Returns : | `True` if the widget was activatable

The `activate`() method emits the "activate" signal on the widget that activates it (if it can be activated). Activation is what happens when you press Enter on a widget during key navigation; clicking a button, selecting a menu item, etc. If the widget isn't activatable, the method returns `False`.

### gtk.Widget.set_scroll_adjustments

        def set_scroll_adjustments(hadjustment, vadjustment)

`hadjustment` : | an adjustment for horizontal scrolling, or `None`
`vadjustment` : | an adjustment for vertical scrolling, or `None`
Returns : | `True` if the widget supports scrolling

The `set_scroll_adjustments`() method sets the horizontal and vertical scroll adjustments specified by `hadjustment` and `vadjustment` respectively and returns `True`. If the widget doesn't support scrolling this method returns `False`. Widgets that don't support scrolling can be scrolled by placing them in a `gtk.Viewport`, which does support scrolling. This method emits the "set-scroll-adjustments" signal on the widget.

### gtk.Widget.reparent

        def reparent(new_parent)

`new_parent` : | a `gtk.Container` to move the widget into

The `reparent`() method moves a widget from one `gtk.Container` to another.

### gtk.Widget.intersect

        def intersect(area, intersection)

`area` : | a rectangle
Returns : | a rectangle of the intersection of the widget and `area` or `None`

The `intersect`() method computes the intersection of a the widget's area and `area`, and returns the intersection in a `gtk.gdk.Rectangle`. This method returns `False` if there is no intersection.

### gtk.Widget.region_intersect

        def region_intersect(region)

`region` : | a `gtk.gdk.Region`, in the same coordinate system as the widget.allocation. That is, relative to the widget.window for `NO_WINDOW` widgets; relative to the parent window of the widget.window for widgets with their own window.
Returns : | a newly allocated `gtk.gdk.Region` holding the intersection of the widget and `region`. The coordinates of the returned region are relative to widget.window for `NO_WINDOW` widgets, and relative to the parent window of widget.window for widgets with their own window.

### Note

This method is available in PyGTK 2.10 and above.

The `region_intersect`() method computes and returns as a `gtk.gdk.Region` the intersection of a the widget's area and the `gtk.gdk.Region` specified by `region`. Since the result may be empty, use the `gtk.gdk.Region.empty`() method to check.

### gtk.Widget.freeze_child_notify

        def freeze_child_notify()

The `freeze_child_notify`() method freezes the child notify queue that is used to notify child widgets of child property changes.

### gtk.Widget.child_notify

        def child_notify(child_property)

`child_property` : | a child property

The `child_notify`() method adds a child property to the widget's child notify queue that is used to notify child widgets of a change to a child property.

### gtk.Widget.thaw_child_notify

        def thaw_child_notify()

The `thaw_child_notify`() method reverses the effect of a previous call to the `freeze_child_notify`() method.

### gtk.Widget.is_focus

        def is_focus()

Returns : | `True` if the widget is the focus widget.

The `is_focus`() method returns `True` if the widget is the focus widget within its toplevel. This does not mean that the `gtk.HAS_FOCUS` flag is necessarily set; `gtk.HAS_FOCUS` will only be set if the toplevel widget additionally has the global input focus.

### gtk.Widget.grab_focus

        def grab_focus()

The `grab_focus`() method causes the widget to have the keyboard focus for it's enclosing `gtk.Window`. The widget must be a focusable widget, such as a `gtk.Entry`. Also, the widget must have the `gtk.CAN_FOCUS` flag set.

### gtk.Widget.grab_default

        def grab_default()

The `grab_default`() method causes the widget to become the default widget. The widget must have the `gtk.CAN_DEFAULT` flag set by calling the `gtk.Object.set_flags`() method. The default widget is activated when the user presses Enter in a window.

### gtk.Widget.set_name

        def set_name(name)

`name` : | the name for the widget

The `set_name`() method sets the "name" property of the widget to the string specified by `name`. Widgets can be named, which allows you to refer to them in a GTK resource file.

### gtk.Widget.get_name

        def get_name()

Returns : | the name of the widget

The `get_name`() method returns the value of the "name" property that contains the name of the widget or `None` if the widget has no name.

### gtk.Widget.set_state

        def set_state(state)

`state` : | the new state for the widget

The set_state() method sets the state of the widget to the value specified by state. The value of state must be one of the GTK State Type Constants.

Usually you should set the state using wrapper methods such as `set_sensitive`().

### gtk.Widget.set_sensitive

        def set_sensitive(sensitive)

`sensitive` : | if `True` make the widget sensitive

The `set_sensitive`() method sets the "sensitive" property of the widget to the value specified by `sensitive`. If `sensitive` is `True` the widget will be sensitive and the user can interact with it. An insensitive widget appears "grayed out" and the user can't interact with it. Insensitive widgets are known as "inactive", "disabled", or "ghosted" in some other toolkits.

### gtk.Widget.set_app_paintable

        def set_app_paintable(app_paintable)

`app_paintable` : | if `True` the application will paint directly on the widget

The `set_app_paintable`() method sets the "app-paintable" property to the value of `app_paintable`. If `app_paintable` is `True` the application will paint directly on the widget.

### gtk.Widget.set_double_buffered

        def set_double_buffered(double_buffered)

`double_buffered` : | if `True` double-buffer a widget

The `set_double_buffered`() method sets the widget's flags according to the value of `double_buffered`. If `double_buffered` is `True` the `gtk.DOUBLE_BUFFERED` flag is set; otherwise it is unset. Widgets are double buffered by default. "Double buffered" simply means that the `gtk.gdk.Window.begin_paint_rect`() and `gtk.gdk.Window.end_paint`() methods are called automatically around expose events sent to the widget. The `gtk.gdk.Window.begin_paint_rect`() method diverts all drawing to a widget's window to an off screen buffer, and the `gtk.gdk.Window.end_paint`() method draws the buffer to the screen. The result is that users see the window update in one smooth step, and don't see individual graphics primitives being rendered. In very simple terms, double buffered widgets don't flicker, so you would only use this method to turn off double buffering if you had special needs and really knew what you were doing.

### gtk.Widget.set_redraw_on_allocate

        def set_redraw_on_allocate(redraw_on_allocate)

`redraw_on_allocate` : | if `True`, the entire widget will be redrawn when it is allocated to a new size. Otherwise, only the new portion of the widget will be redrawn.

The `set_redraw_on_allocate`() method sets a flag that determines if the entire widget is queued for drawing when a widget's size allocation changes. By default, this setting is `True` and the entire widget is redrawn on every size change. If your widget leaves the upper left are unchanged when made bigger, turning this setting on will improve performance.

### Note

For `NO_WINDOW` widgets setting this flag to `False` turns off all allocation on resizing: the widget will not redraw even if its position changes; this is to allow containers that don't draw anything to avoid excess invalidations. If you set this flag on a `NO_WINDOW` widget that does draw on the widget's `gtk.gdk.Window`, you are responsible for invalidating both the old and new allocation of the widget when the widget is moved and responsible for invalidating regions newly when the widget increases size.

### gtk.Widget.set_parent

        def set_parent(parent)

`parent` : | a parent container

The `set_parent`() method is useful only when implementing subclasses of `gtk.Container`. This method sets the container as the parent of the widget, and takes care of some details such as updating the state and style of the child to reflect its new location. The reverse method is the `unparent`() method.

### gtk.Widget.set_parent_window

        def set_parent_window(parent_window)

`parent_window` : | the new parent window.

The `set_parent_window`() method sets a non default parent window for the widget.

### gtk.Widget.set_child_visible

        def set_child_visible(is_visible)

`is_visible` : | if `True`, the widget should be mapped along with its parent.

The `set_child_visible`() method determines if the widget should be mapped along with its parent. If `is_visible` is `True` the widget will be mapped with its parent if it has called the `show`() method.

The child visibility can be set for widget before it is added to a container to avoid mapping children unnecessarily. The widget's child visibility flag will be reset to its default state of `True` when the widget is removed from a container. Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. This method is only useful for container implementations and never should be called by an application.

### gtk.Widget.get_child_visible

        def get_child_visible()

Returns : | `True` if the widget is mapped with the parent.

The `get_child_visible`() method returns the value set with the `set_child_visible`() method. This method is only useful for container implementations and never should be called by an application.

### gtk.Widget.get_parent

        def get_parent()

Returns : | the parent container of the widget, or `None`

The `get_parent`() method returns the parent container of the widget or `None` if the widget has no parent.

### gtk.Widget.get_parent_window

        def get_parent_window()

Returns : | the parent `gtk.gdk.Window` of the widget

The `get_parent_window`() method returns the widget's parent `gtk.gdk.Window`.

### gtk.Widget.child_focus

        def child_focus(direction)

`direction` : | the direction of focus movement
Returns : | `True` if focus ended up inside the widget

The `child_focus`() method is used by custom widget implementations. If you're writing an application, use the `grab_focus`() method to move the focus to a particular widget, and the `gtk.Container.set_focus_chain`() method to change the focus tab order.

The `child_focus`() method is called by containers as the user moves around the window using keyboard shortcuts. The value of `direction` indicates what kind of motion is taking place: `gtk.DIR_TAB_FORWARD`, `gtk.DIR_TAB_BACKWARD`, `gtk.DIR_UP`, `gtk.DIR_DOWN`, `gtk.DIR_LEFT` or `gtk.DIR_RIGHT`

This method emits the "focus" signal on the widget. Widgets override the default handler for this signal in order to implement appropriate focus behavior. The "focus" default handler for a widget should return:

- `True` if the focus is left on a focusable location inside the widget, and
- `False` if the focus moved outside the widget

If returning `True`, widgets normally call the `grab_focus`() method to place the focus accordingly; if returning `False`, they don't modify the current focus location.

### gtk.Widget.set_size_request

        def set_size_request(width, height)

`width` : | the width the widget should request, or -1 to unset
`height` : | the height the widget should request, or -1 to unset

The `set_size_request`() method sets the minimum size of a widget to the values specified by `width` and `height`. You can use this method to force a widget to be either larger or smaller than it normally would be. In most cases, the `gtk.Window.set_default_size`() is a better choice for toplevel windows than this method. Setting the default size will still allow users to shrink the window but setting the size request will force them to leave the window at least as large as the size request. When dealing with window sizes, the `gtk.Window.set_geometry_hints`() can be a useful method as well.

### Note

There is an inherent danger when setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hard code a size that will always be correct.

The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested. If the size request in a given direction is -1 (unset), then the "natural" size request of the widget will be used instead. Widgets can't actually be allocated a size less than 1 by 1, but you can pass 0,0 to this method to mean "as small as possible".

### gtk.Widget.get_size_request

        def get_size_request()

Returns : | a 2-tuple containing the requested width and height

The `get_size_request`() method returns a 2-tuple containing the width and height of the widget that was explicitly set for the widget using the `set_size_request()`. A value of -1 for the width or height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See the `set_size_request()` method for more information. To get the size a widget will actually use, call the `size_request()` instead of this method.

### gtk.Widget.set_events

        def set_events(events)

`events` : | the event mask

The `set_events`() method sets the event mask for a widget using the value specified by `events`. The event mask determines which events a widget will receive. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget's functionality, so be careful. This method must be called while a widget is unrealized. Consider using the `add_events`() method for widgets that are already realized, or if you want to preserve the existing event mask. This method can't be used with `gtk.NO_WINDOW` widgets since a widget must have a `gtk.gdk.Window` to receive events. To get events on `gtk.NO_WINDOW` widgets, place them inside a `gtk.EventBox` and receive events on the event box.

The value of `events` must be a combination of the GDK Event Mask Flag Constants:

### gtk.Widget.add_events

        def add_events(events)

`events` : | an event mask

The `add_events`() method adds the events specified by `events` to the event mask for the widget. See the `set_events`() method for details.

### gtk.Widget.set_extension_events

        def set_extension_events(mode)

`mode` : | the extension events to receive

The `set_extension_events`() method sets the extension events mask to the value specified by `mode`. The value of mode must be one of the GDK Extension Mode Constants.

See the `gtk.gdk.Window.input_set_extension_events`() method for more information.

### gtk.Widget.get_extension_events

        def get_extension_events()

Returns : | the extension events for the widget

The `get_extension_events`() method returns the extension events the widget will receive. See the `gtk.gdk.Window.input_set_extension_events`() method for more information.

### gtk.Widget.get_toplevel

        def get_toplevel()

Returns : | the topmost ancestor of the widget, or the widget itself if there's no ancestor.

The `get_toplevel`() method returns the topmost widget in the container hierarchy that the widget is a part of. If the widget has no parent widgets, it will be returned as the topmost widget.

Note the difference in behavior as compared to the `get_ancestor`() method that returns `None` if the widget isn't inside a toplevel window, and if the window is inside a widget derived from `gtk.Window` that is in turn inside the toplevel `gtk.Window`. While the second case may seem unlikely, it actually happens when a `gtk.Plug` is embedded inside a `gtk.Socket` within the same application.

To reliably find the toplevel `gtk.Window`, use the `get_toplevel`() method and check if the `gtk.TOPLEVEL` flag is set on the result.

### gtk.Widget.get_ancestor

        def get_ancestor(widget_type)

`widget_type` : | a widget type
Returns : | the ancestor widget, or `None` if not found

The `get_ancestor`() method returns the first ancestor of the widget with the type specified by `widget_type`. For example:

      widget.get_ancestor(gtk.Box)

returns the first `gtk.Box` that's an ancestor of the widget. See the `get_toplevel`() method for information about checking for a toplevel `gtk.Window`.

### gtk.Widget.get_colormap

        def get_colormap()

Returns : | the colormap used by the widget

The `get_colormap`() method returns the colormap that will be used to render the widget.

### gtk.Widget.get_visual

        def get_visual()

Returns : | the visual for the widget

The `get_visual`() method returns the visual that will be used to render the widget.

### gtk.Widget.get_screen

        def get_screen()

Returns : | the `gtk.gdk.Screen` for the toplevel for this widget.

### Note

This method is available in PyGTK 2.2 and above.

The `get_screen`() method returns the `gtk.gdk.Screen` from the toplevel window associated with the widget. This method can only be called after the widget has been added to a widget hierarchy with a `gtk.Window` at the top.

### gtk.Widget.has_screen

        def has_screen()

Returns : | `True` if there is a `gtk.gdk.Screen` associated with the widget.

### Note

This method is available in PyGTK 2.2 and above.

The `has_screen`() method returns `True` if a `gtk.gdk.Screen` is associated with the widget. All toplevel widgets have an associated screen, as do all widgets added into a hierarchy with a toplevel window.

### gtk.Widget.get_display

        def get_display()

Returns : | the `gtk.gdk.Display` for the toplevel for this widget.

### Note

This method is available in PyGTK 2.2 and above.

The `get_display`() method returns the `gtk.gdk.Display` for the toplevel window associated with the widget. This method can only be called after the widget has been added to a widget hierarchy with a toplevel `gtk.Window`

### gtk.Widget.get_root_window

        def get_root_window()

Returns : | the `gtk.gdk.Window` root window for the toplevel for this widget.

### Note

This method is available in PyGTK 2.2 and above.

The `get_root_window`() method returns the root window containing the widget. This method should only be called after the widget has been added to a widget hierarchy with a toplevel `gtk.Window`

The root window is useful for such purposes as creating a popup `gtk.gdk.Window` associated with the window.

### gtk.Widget.get_settings

        def get_settings()

Returns : | the associated `gtk.Settings` object

The `get_settings`() method returns the settings object holding the settings (global property settings, RC file information, etc) used for this widget.

### gtk.Widget.get_clipboard

        def get_clipboard(selection)

`selection` : | a `gtk.gdk.Atom` or string that identifies the clipboard to use. `gtk.gdk.SELECTION_CLIPBOARD` gives the default clipboard. Another common value is `gtk.gdk.SELECTION_PRIMARY`, which gives the primary X selection.
Returns : | the appropriate `gtk.Clipboard` object. If no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent for all time.

### Note

This method is available in PyGTK 2.2 and above.

The `get_clipboard`() method returns the `gtk.Clipboard` object for the selection specified by `selection`. The widget must have a `gtk.gdk.Display` associated with it, and so must be attached to a toplevel window.

### gtk.Widget.get_accessible

        def get_accessible()

Returns : | an `atk.Object`

The `get_accessible`() method returns the Accessibility ToolKit (ATK) object for the widget as an `atk.Object`.

### gtk.Widget.set_colormap

        def set_colormap(colormap)

`colormap` : | a `gtk.gdk.Colormap`

The `set_colormap`() method sets the `gtk.gdk.Colormap` for the widget to the value specified by `colormap`. Widget must not have been realized.

### gtk.Widget.get_events

        def get_events()

Returns : | the event mask for the widget

The `get_events`() method returns the event mask for the widget that determines the events that the widget will receive. See the `set_events`() method for more detail about events.

### gtk.Widget.get_pointer

        def get_pointer()

Returns : | a tuple containing the X and Y coordinates of the mouse pointer

The `get_pointer`() method returns a tuple containing the location of the mouse pointer in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as:

- the widget `gtk.gdk.Window` coordinates for widgets that are not `gtk.NO_WINDOW` widgets, or
- the coordinates relative to the widget allocation for widgets that are `gtk.NO_WINDOW` widgets.

### gtk.Widget.is_ancestor

        def is_ancestor(ancestor)

`ancestor` : | another `gtk.Widget`
Returns : | `True` if `ancestor` contains the widget as a child, grandchild, great grandchild, etc.

The `is_ancestor`() method returns `True` if the widget is somewhere inside the hierarchy of the widget specified by`ancestor`

### gtk.Widget.translate_coordinates

        def translate_coordinates(dest_widget, src_x, src_y)

`dest_widget` : | a `gtk.Widget`
`src_x` : | the X position relative to the widget
`src_y` : | the Y position relative to the widget
Returns : | a tuple containing the X and Y position relative to `dest_widget`

The `translate_coordinates`() method returns a tuple containing the translation of the widget x and y coordinates specified by `src_x` and `src_y` respectively to coordinates relative to `dest_widget`. In order to perform this operation, both widgets must be realized, and must share a common toplevel.

### gtk.Widget.hide_on_delete

        def hide_on_delete()

Returns : | `True`

The `hide_on_delete`() method is a utility method that is intended to be connected to the "delete_event" signal on a `gtk.Window`. The method calls the `hide`() method on the widget, then returns `True`. If connected to "delete_event", the result is that clicking the close button for a window (on the window frame, top right corner usually) will hide but not destroy the window. By default, `PyGTK` destroys windows when "delete_event" is received.

### gtk.Widget.set_style

        def set_style(style)

`style` : | a `gtk.Style`, or `None` to revert to the default style

The `set_style`() method sets the "style" property to the value of `style`. The "style" property contains the `gtk.Style` for the widget. This method interacts badly with themes, because themes work by replacing the `gtk.Style`.

### gtk.Widget.ensure_style

        def ensure_style()

The `ensure_style`() method makes sure that the widget has a style. This method is useful if applied to an unrealized widget. Usually, if you want the style, the widget is realized, and guaranteed to have a style.

### gtk.Widget.get_style

        def get_style()

Returns : | the widget's `gtk.Style`

The `get_style`() method returns the value of the "style" property.

### gtk.Widget.modify_style

        def modify_style(style)

`style` : | the `gtk.RcStyle` holding the style modifications

The `modify_style`() method modifies the style values on the widget using the values in `style`. Modifications made using this technique take precedence over style values set via an RC file, however, they will be overridden if a style is explicitly set on the widget using the `set_style`() method. The `gtk.RcStyle` object is designed so each attribute can either be set or unset, so it is possible, using this method, to modify some style values and leave the others unchanged.

Note that modifications made with this method are not cumulative with previous calls to the `modify_style`() method or with such methods as the `modify_fg`() method. If you wish to retain previous values, you must first call the `get_modifier_style`() method, make your modifications to the returned style, then call the `modify_style`() method with that style. On the other hand, if you first call the `modify_style`() method, subsequent calls to such methods as the `modify_fg`() method will have a cumulative effect with the initial modifications.

### gtk.Widget.get_modifier_style

        def get_modifier_style()

Returns : | the modifier style for the widget. This `gtk.RcStyle` is owned by the widget.

The `get_modifier_style`() method returns the current modifier style for the widget as set by the `modify_style`() method. If no style was previously set, a new `gtk.RcStyle` object will be created( with all values unset), and set as the modifier style for the widget. If you make changes to this rc style, you must call the `modify_style`() method, passing in the returned rc style, to make sure that your changes take effect.

### Caution

Passing the style back to the `modify_style`() method will normally end up destroying it, because the `modify_style`() method copies the passed-in style and sets the copy as the new modifier style, thus dropping any reference to the old modifier style.

### gtk.Widget.modify_fg

        def modify_fg(state, color)

`state` : | a widget state.
`color` : | the `gtk.gdk.Color` to assign.

The `modify_fg`() method sets the foreground color to the `gtk.gdk.Color` specified by `color` for the widget in the specified `state`. All other style values are left untouched. The value of state must be one of the GTK State Type Constants.

### gtk.Widget.modify_bg

        def modify_bg(state, color)

`state` : | a widget state.
`color` : | the `gtk.gdk.Color` to assign

The `modify_bg`() method sets the background color to the `gtk.gdk.Color` specified by `color` for the widget in the specified `state`. All other style values are left untouched. See `modify_fg`() method for detail on the possible values of `state`.

### Note

`modify_bg`() only affects widgets that have an associated `gtk.gdk.Window`. Widgets that do not have an associated window include `gtk.Arrow`, `gtk.Bin`, `gtk.Box`, `gtk.Button`, `gtk.CheckButton`, `gtk.Fixed`, `gtk.Image`, `gtk.Label`, `gtk.MenuItem`, `gtk.Notebook`, `gtk.Paned`, `gtk.RadioButton`, `gtk.Range`, `gtk.ScrolledWindow`, `gtk.Separator`, `gtk.Table`, `gtk.Toolbar`, `gtk.AspectFrame`, `gtk.Frame`, `gtk.VBox`, `gtk.HBox`, `gtk.VSeparator`, `gtk.HSeparator`. These widgets can be added to a `gtk.EventBox` to overcome this limitation.

### gtk.Widget.modify_text

        def modify_text(state, color)

`state` : | a widget state.
`color` : | the `gtk.gdk.Color` to assign.

The `modify_text`() method sets the text color to the `gtk.gdk.Color` specified by `color` for the widget in the specified `state`. All other style values are left untouched. The text color is the foreground color used along with the base color (see the `modify_base`() method) for widgets such as `gtk.Entry` and `gtk.TextView`. See the `modify_fg`() method for detail on the possible values of `state`.

### gtk.Widget.modify_base

        def modify_base(state, color)

`state` : | a widget state.
`color` : | the `gtk.gdk.Color` to assign

The `modify_base`() method sets the base color to the `gtk.gdk.Color` specified by `color` for the widget in the specified `state`. All other style values are left untouched. The base color is the background color used along with the text color (see the `modify_text`() method) for widgets such as `gtk.Entry` and `gtk.TextView`. See `modify_fg`() method for detail on the possible values of `state`.

### gtk.Widget.modify_font

        def modify_font(font_desc)

`font_desc` : | a font description to use

The `modify_font`() method sets the font to use to the value specified by `font_desc` for the widget. All other style values are left untouched.

### gtk.Widget.create_pango_context

        def create_pango_context()

Returns : | the new `pango.Context`

The `create_pango_context`() method creates a new `pango.Context` with the appropriate colormap, font description, and base direction for drawing text for this widget. See the `get_pango_context`() method.

### gtk.Widget.get_pango_context

        def get_pango_context()

Returns : | the `pango.Context` for the widget.

The `get_pango_context`() method returns the `pango.Context` with the appropriate colormap, font description and base direction for this widget. Unlike the context returned by the `create_pango_context`() method, this context is owned by the widget (it can be used as long as widget exists), and will be updated to match any changes to the widget's attributes.

If you create and keep a `pango.Layout` using this context, you must deal with changes to the context by calling the `pango.Layout.context_changed`() method on the layout in response to the "style-set" and "direction-set" signals for the widget.

### gtk.Widget.create_pango_layout

        def create_pango_layout(text)

`text` : | the text to set on the layout
Returns : | the new `pango.Layout`

The `create_pango_layout`() method creates a new `pango.Layout` with the appropriate colormap, font description, and base direction for drawing the specified `text` for this widget. If you keep a `pango.Layout` created by this method, you must call `pango.Layout.context_changed()` in response to the "style-set" and "direction-set" signals for the widget to notify the layout of changes to the base direction or font of this widget.

### gtk.Widget.render_icon

        def render_icon(stock_id, size, detail=None)

`stock_id` : | a stock ID
`size` : | a stock size
`detail` : | the render detail to pass to the theme engine or `None`
Returns : | a new pixbuf, or `None` if the stock ID wasn't known

The `render_icon`() method is a convenience method that uses the theme engine and RC file settings for the widget to look up the stock icon specified by `stock_id` of the specified `size` and to render it to a pixbuf that is returned. `stock_id` should be a stock icon ID such as `gtk.STOCK_OPEN` or `gtk.STOCK_OK`. `size` should be one of the GTK Icon Size Constants:

`detail` is an optional string that identifies the widget or code doing the rendering, so that theme engines can special-case rendering for that widget or code.

### gtk.Widget.set_composite_name

        def set_composite_name(name)

`name` : | the name to set.

The `set_composite_name`() method sets a widgets composite name to the value specified by `name`. The widget must be a composite child of its parent

### gtk.Widget.get_composite_name

        def get_composite_name()

Returns : | the composite name of the widget or `None`

The `get_composite_name`() method returns the composite name of a widget or `None` if the widget is not a composite.

### gtk.Widget.reset_rc_styles

        def reset_rc_styles()

The `reset_rc_styles`() method resets the styles of widget and all descendants to the correct values for the currently loaded RC file settings. This method is not useful for applications.

### gtk.Widget.style_get_property

        def style_get_property(property_name)

`property_name` : | the name of a style property
Returns : | the property value

### Note

This method is available in PyGTK 2.4 and above.

The `style_get_property`() method returns the value of a style property specified by `property_name`.

### gtk.Widget.set_direction

        def set_direction(dir)

`dir` : | the new direction

The `set_direction`() method sets the "direction" property to the value specified by `dir`. The "direction" property determines the reading direction of the widget that controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is to handle localization for languages with right-to-left reading directions. Generally, applications will use the default reading direction, except for containers that are arranged in an order that is explicitly visual rather than logical (such as buttons for text justification). The values of `dir` must be one of the GTK Text Direction Constants.

If the direction is set to `gtk.TEXT_DIR_NONE`, then the value set by the `gtk.widget.set_default_direction`() function will be used.

### gtk.Widget.get_direction

        def get_direction()

Returns : | the reading direction for the widget.

The `get_direction`() method returns the reading direction for the widget. See the `set_direction`() method for more information.

### gtk.Widget.shape_combine_mask

        def shape_combine_mask(shape_mask, offset_x, offset_y)

`shape_mask` : | the shape to be added.
`offset_x` : | the X position of shape mask with respect to the widget's `gtk.gdk.Window`.
`offset_y` : | Y position of shape mask with respect to the widget's `gtk.gdk.Window`.

The `shape_combine_mask`() method sets a shape for the widget's `gtk.gdk.Window` using the mask specified by `shape_mask` at the location specified by `offset_x` and `offset_y`. This allows for transparent windows etc., see the `gtk.gdk.Window.shape_combine_mask`() method for more information.

### gtk.Widget.reset_shapes

        def reset_shapes()

The `reset_shapes`() method recursively resets the shapes of the widget and its descendants.

### gtk.Widget.path

        def path()

Returns : | the widget's path

The `path`() method returns the full path to the widget. The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. The name of a widget comes from the `get_name`() method. Paths are used to apply styles to a widget in gtkrc configuration files. Widget names are the type of the widget by default (e.g. "GtkButton") or can be set to an application-specific value with the `set_name`() method. By setting the name of a widget, you allow users or theme authors to apply styles to that specific widget in their gtkrc file.

### gtk.Widget.class_path

        def class_path()

Returns : | the widget's class path

The `class_path`() method is similar to the `path`() method, but does not use a custom name set with the `set_name`() (e.g. always uses "GtkButton" even if a custom name is available).

### gtk.Widget.list_mnemonic_labels

        def list_mnemonic_labels()

Returns : | the list of mnemonic labels

### Note

This method is available in PyGTK 2.4 and above.

The `list_mnemonic_labels`() method returns a list of the widgets, normally labels, for which this widget is a the target of a mnemonic (see for example, the `gtk.Label.set_mnemonic_widget()` method).

### gtk.Widget.add_mnemonic_label

        def add_mnemonic_label(label)

`label` : | a `gtk.Widget` that acts as a mnemonic label.

### Note

This method is available in PyGTK 2.4 and above.

The `add_mnemonic_label`() method adds the widget specified by `label` to the list of mnemonic labels for the widget.(See the `list_mnemonic_labels()` method for more detail).

### gtk.Widget.remove_mnemonic_label

        def remove_mnemonic_label(label)

`label` : | a `gtk.Widget` that was previously set as a mnemonic label.

### Note

This method is available in PyGTK 2.4 and above.

The `remove_mnemonic_label`() method removes the widget specified by `label` from the list of mnemonic labels for the widget. (See the `list_mnemonic_labels()` method). `label` must have previously been added to the list with the `add_mnemonic_label()`.

### gtk.Widget.menu_get_for_attach_widget

        def menu_get_for_attach_widget()

Returns : | a list of menus attached to this widget.

### Note

This method is available in PyGTK 2.6 and above.

The `menu_get_for_attach_widget`() method returns a list of the menus that are attached to this widget.

### gtk.Widget.set_activate_signal

        def set_activate_signal(signal_name)

signal_name : | a signal name

### Note

This method is available in PyGTK 2.8 and above.

The `set_activate_signal`() method sets the signal specified by `signal_name` as the signal to be emitted when the widget is activated for example by a call to the `activate`() method.

### gtk.Widget.set_set_scroll_adjustments_signal

        def set_set_scroll_adjustments_signal(signal_name)

signal_name : | a signal name

### Note

This method is available in PyGTK 2.8 and above.

The `set_scroll_adjustments_signal`() method sets the signal specified by `signal_name` as the signal to be emitted when the widget has its scroll adjustments set for example by a call to the `set_scroll_adjustments`() method.

### gtk.Widget.get_action

        def get_action()

Returns : | the `gtk.Action` that a widget is a proxy for, or `None`, if it is not attached to an action.

### Note

This method is available in PyGTK 2.10 and above.

The `get_action`() method returns the `gtk.Action` that `widget` is a proxy for. See also the `gtk.Action.get_proxies()` method.

### gtk.Widget.drag_dest_set_track_motion

        def drag_dest_set_track_motion(track_motion)

`track_motion` : | if `True` accept all targets

### Note

This method is available in PyGTK 2.10 and above.

The `drag_dest_set_track_motion`() method tells the widget to emit "drag-motion" and "drag-leave" events regardless of the targets and the `gtk.DEST_DEFAULT_MOTION` flag.

This may be used when a widget wants to do generic actions regardless of the targets that the source offers.

### gtk.Widget.drag_dest_get_track_motion

        def drag_dest_get_track_motion()

Returns : | `True` if the widget always emits "drag-motion events"

### Note

This method is available in PyGTK 2.10 and above.

The `drag_dest_get_track_motion`() method returns `True` if the widget has been configured to always emit "drag-motion" signals.

### gtk.Widget.is_composited

        def is_composited()

Returns : | `True` if the widget can rely on its alpha channel being drawn correctly.

### Note

This method is available in PyGTK 2.10 and above.

The `is_composited`() method returns `True` if the widget can rely on having its alpha channel drawn correctly. On X11 this function returns whether a compositing manager is running for the widget's screen

### gtk.Widget.input_shape_combine_mask

        def input_shape_combine_mask(shape_mask, offset_x, offset_y)

`shape_mask` : | shape to be added, or `None` to remove an existing shape.
`offset_x` : | X position of `shape_mask` with respect to the widget's window.
`offset_y` : | Y position of `shape_mask` with respect to the widget's window.

### Note

This method is available in PyGTK 2.10 and above.

The `input_shape_combine_mask`() method sets an input shape for this widget's `gtk.gdk.Window`. This allows for windows that react to a mouse click in a nonrectangular region, see the `gtk.gdk.Window.input_shape_combine_mask`() method for more information.

### gtk.Widget.get_activate_signal

        def get_activate_signal()

Returns : | a signal name

### Note

This method is available in PyGTK 2.10 and above.

The `get_activate_signal`() method returns the name of the signal that is emitted when the widget is activated for example by a call to the `activate`() method. See the `set_activate_signal`() method for more information.

### gtk.Widget.error_bell

        def error_bell()

### Note

This method is available in PyGTK 2.12 and above.

The `error_bell`() method notifies the user about an input-related error on this widget. If the GtkSettings:gtk-error-bell setting is `True`, it calls `gtk.gdk.Window.beep`(), otherwise it does nothing. Note that the effect of `gtk.gdk.Window.beep`() can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.

### gtk.Widget.get_has_tooltip

        def get_has_tooltip()

Returns : | the current value of has-tooltip on widget.

### Note

This method is available in PyGTK 2.12 and above.

The `get_has_tooltip`() method returns the current value of the has-tooltip property. See GtkWidget:has-tooltip for more information.

### gtk.Widget.get_tooltip_markup

        def get_tooltip_markup()

Returns : | the tooltip text, or `None`.

### Note

This method is available in PyGTK 2.12 and above.

The `get_tooltip_markup`() method gets the contents of the tooltip for widget.

### gtk.Widget.get_tooltip_text

        def get_tooltip_text()

Returns : | the tooltip text, or `None`.

### Note

This method is available in PyGTK 2.12 and above.

The `get_tooltip_text`() method gets the contents of the tooltip for widget.

### gtk.Widget.get_tooltip_window

        def get_tooltip_window()

Returns : | the `gtk.Window` of the current tooltip.

### Note

This method is available in PyGTK 2.12 and above.

The `get_tooltip_window`() method returns the `gtk.Window` of the current tooltip. This can be the `gtk.Window` created by default, or the custom tooltip window set using `gtk.Widget.set_tooltip_window`().

### gtk.Widget.keynav_failed

        def keynav_failed(direction)

`direction` : | direction of focus movement.
Returns : | `True` if stopping keyboard navigation is fine, `False` if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).

### Note

This method is available in PyGTK 2.12 and above.

The `keynav_failed`() should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the GtkWidget::keynav-changed signal on the widget and its return value should be interpreted in a way similar to the return value of `gtk.Widget.child_focus`():

When `True` is returned, stay in the widget, the failed keyboard navigation is Ok and/or there is nowhere we can/should move the focus to.

When `False` is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling gtk_widget_child_focus() on the widget's toplevel.

The default ::keynav-failed handler returns `True` for gtk.DIR_TAB_FORWARD and gtk.DIR_TAB_BACKWARD. For the other values of GtkDirectionType, it looks at the GtkSettings:gtk-keynav-cursor-only" setting and returns `False` if the setting is `True` This way the entire user interface becomes cursor-navigatable on input devices such as mobile phones which only have cursor keys but no tab key.

Whenever the default handler returns `True`, it also calls `gtk.Widget.error_bell`() to notify the user of the failed keyboard navigation.

A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys.

### gtk.Widget.modify_cursor

        def modify_cursor(primary, secondary)

`primary` : | the color to use for primary cursor (does not need to be allocated), or `None` to undo the effect of previous calls to of `gtk.Widget.modify_cursor` ().
`secondary` : | the color to use for secondary cursor (does not need to be allocated), or `None` to undo the effect of previous calls to of `gtk.Widget.modify_cursor` ().

### Note

This method is available in PyGTK 2.12 and above.

The `modify_cursor`() sets the cursor color to use in a widget, overriding the GtkWidget:cursor-color and GtkWidget:secondary-cursor-color style properties. All other style values are left untouched. See also `gtk.Widget.modify_style`().

### gtk.Widget.set_has_tooltip

        def set_has_tooltip(has_tooltip)

`has_tooltip` : | whether or not widget has a tooltip.

### Note

This method is available in PyGTK 2.12 and above.

The `set_has_tooltip`() sets the has-tooltip property on widget to `has_tooltip`. See GtkWidget:has-tooltip for more information.

### gtk.Widget.set_tooltip_markup

        def set_tooltip_markup(markup)

`markup` : | the contents of the tooltip for widget, or `None`

### Note

This method is available in PyGTK 2.12 and above.

The `set_tooltip_markup`() sets markup as the contents of the tooltip, which is marked up with the Pango text markup language. This function will take care of setting GtkWidget:has-tooltip to `True` and of the default handler for the GtkWidget::query-tooltip signal. See also the GtkWidget:tooltip-markup property and `gtk.Tooltip.set_markup`().

### gtk.Widget.set_tooltip_text

        def set_tooltip_text(text)

`text` : | the contents of the tooltip for widget, or `None`

### Note

This method is available in PyGTK 2.12 and above.

The `set_tooltip_text`() sets `text` as the contents of the tooltip. This function will take care of setting GtkWidget:has-tooltip to `True` and of the default handler for the GtkWidget::query-tooltip signal. See also the GtkWidget:tooltip-text property and `gtk.Tooltip.set_text`().

### gtk.Widget.set_tooltip_window

        def set_tooltip_window(custom_window)

`custom_window` : | a `gtk.Window`, or `None`

### Note

This method is available in PyGTK 2.12 and above.

The `set_tooltip_window`() replaces the default, usually yellow, window used for displaying tooltips with `custom_window`. GTK+ will take care of showing and hiding custom_window at the right moment, to behave likewise as the default tooltip window. If custom_window is `None`, the default tooltip window will be used.

### gtk.Widget.trigger_tooltip_query

        def trigger_tooltip_query()

### Note

This method is available in PyGTK 2.12 and above.

The `trigger_tooltip_query`() triggers a tooltip query on the display where the toplevel of widget is located. See `gtk.tooltip_trigger_tooltip_query` () for more information.

### gtk.Widget.get_snapshot

        def get_snapshot(clip_rect)

`clip_rect` : | a `gtk.gdk.Rectangle` or `None`.
Returns : | The `gtk.gdk.PixmapWindow` snapshot of the widget.

### Note

This method is available in PyGTK 2.14 and above.

The `get_snapshot`() method creates a `gtk.gdk.Pixmap` of the contents of the widget and its children.

Works even if the widget is obscured. The depth and visual of the resulting pixmap is dependent on the widget being snapshot and likely differs from those of a target widget displaying the pixmap. The function `gtk.gdk.Pixbuf.get_from_drawable`() can be used to convert the pixmap to a visual independant representation.

The snapshot area used by this function is the widget's allocation plus any extra space occupied by additional windows belonging to this widget (such as the arrows of a spin button). Thus, the resulting snapshot pixmap is possibly larger than the allocation.

If clip_rect is non-`None`, the resulting pixmap is shrunken to match the specified clip_rect. The (x,y) coordinates of clip_rect are interpreted widget relative. If width or height of clip_rect are 0 or negative, the width or height of the resulting pixmap will be shrunken by the respective amount. For instance a clip_rect { +5, +5, -10, -10 } will chop off 5 pixels at each side of the snapshot pixmap. If non-NULL, clip_rect will contain the exact widget-relative snapshot coordinates upon return. A clip_rect of { -1, -1, 0, 0 } can be used to preserve the auto-grown snapshot area and use clip_rect as a pure output parameter.

The returned pixmap can be `None`, if the resulting clip_area was empty.

### gtk.Widget.get_window

        def get_window()

Returns : | the widget's `gtk.Window` .

### Note

This method is available in PyGTK 2.14 and above.

The `get_window`() method returns the widget's `gtk.Window` if it is realized, `None` otherwise.

## Functions

### gtk.widget_push_colormap

        def gtk.widget_push_colormap(cmap)

`cmap` : | a `gtk.gdk.Colormap`

The `gtk.widget_push_colormap`() function pushes the `gtk.gdk.Colormap` specified by `cmap` onto a global stack of colormaps. The topmost colormap on the stack will be used when creating widgets. Remove `cmap` with the `gtk.widget_pop_colormap`() function. There's little reason to use this function.

### gtk.widget_push_composite_child

        def gtk.widget_push_composite_child()

The `gtk.widget_push_composite_child`() function creates all new widgets as composite children until the corresponding `gtk.widget_pop_composite_child`() function call. A composite child is a child that's an implementation detail of the container it's inside and should not be visible to people using the container. Composite children aren't treated differently (but see the `gtk.Container.foreach`() method vs. the `gtk.Container.forall`() method), but e.g. GUI builders might want to treat them in a different way.

### gtk.widget_pop_composite_child

        def gtk.widget_pop_composite_child()

The `gtk.widget_pop_composite_child`() function cancels the effect of a previous call to the `gtk.widget_push_composite_child`() function.

### gtk.widget_pop_colormap

        def gtk.widget_pop_colormap()

The `gtk.widget_pop_colormap`() function removes the `gtk.gdk.Colormap` on the top of the global stack of colormaps. This function reverses the effect of the `gtk.widget_push_colormap`() function.

### gtk.widget_get_default_style

        def gtk.widget_get_default_style()

Returns : | the default `gtk.Style`

The `gtk.widget_get_default_style`() function returns the default `gtk.Style` used by all newly created widgets

### gtk.widget_set_default_colormap

        def gtk.widget_set_default_colormap(colormap)

`colormap` : | a `gtk.gdk.Colormap` object

The `gtk.widget_set_default_colormap`() function sets the default `gtk.gdk.Colormap` to use when creating widgets to the value specified by `colormap`. The `gtk.widget_push_colormap`() function is a better function to use if you only want to affect a few widgets, rather than all widgets.

### gtk.widget_get_default_colormap

        def gtk.widget_get_default_colormap()

Returns : | the default `gtk.gdk.Colormap` object

The `gtk.widget_get_default_colormap`() function returns the default `gtk.gdk.Colormap` used when creating new widgets.

### gtk.widget_get_default_visual

        def gtk.widget_get_default_visual()

Returns : | the default `gtk.gdk.Visual` object

The `gtk.widget_get_default_visual`() function returns the default `gtk.gdk.Visual` of the default `gtk.gdk.Colormap`.

### gtk.widget_set_default_direction

        def gtk.widget_set_default_direction(dir)

`dir` : | the new default direction - either `gtk.TEXT_DIR_RTL` or `gtk.TEXT_DIR_LTR`.

The `gtk.widget_set_default_direction`() function sets the default text direction to the value specified by `dir`. The value of `dir` must be either `gtk.TEXT_DIR_RTL` or `gtk.TEXT_DIR_LTR`. The default text direction is used for widgets that have not had a text direction set by the `set_direction`() method.

### gtk.widget_get_default_direction

        def gtk.widget_get_default_direction()

Returns : | the default text direction

The `gtk.widget_get_default_direction`() function returns the default text direction as set by the `gtk.widget_set_default_direction`() function.

### gtk.widget_class_find_style_property

        def gtk.widget_class_find_style_property(widget)

`widget` : | a `gtk.Widget`
`property_name` : | a style property name
Returns : | the style property as a GParam object

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.widget_class_find_style_property`() function returns the GParam object corresponding to the style property specified by `property_name` of the `gtk.Widget` specified by `widget`.

### gtk.widget_class_list_style_properties

        def gtk.widget_class_list_style_properties(widget)

`widget` : | a `gtk.Widget`
Returns : | a list of style properties as GParam objects

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.widget_class_list_style_properties`() function returns a list of the style properties of the `gtk.Widget` specified by `widget`. The list contains a GParam object for each style property.

### gtk.widget_class_install_style_property

        def gtk.widget_class_install_style_property(widget)

`widget` : | a `gtk.Widget`
`pspec` : | a 4-tuple containing the property spec

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.widget_class_install_style_property`() function installs the style property specified by `pspec` on the `gtk.Widget` specified by `widget`. `pspec` is a 4-tuple containing the property name, the property type, a nickname (or `None`) and a description of the property (or None).

This function raises the TypeError exception if `widget` is not a `gtk.Widget` or if the property is already installed.

## Signals

### The "accel-closures-changed" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "accel-closures-changed" signal is emitted when an accelerator is added to or removed from the `gtk.AccelGroup` for `widget` or an accelerator path is setup.

### The "button-press-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "button-press-event" signal is emitted when a mouse button is pressed.

### The "button-release-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "button-release-event" signal is emitted when a mouse button is released.

### The "can-activate-accel" gtk.Widget Signal

        def callback(widget, signal_id, user_param1, ...)

`widget` : | the widget that received the signal
`signal_id` : | the ID of a signal installed on `widget`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

### Note

This signal is available in GTK+ 2.4 and above.

The "can-activate-accel" signal is emitted when an accelerator is about to activate `widget`. The handler determines if the accelerator that activates the signal identified by `signal_id` can currently be activated. This signal is present to allow applications and derived widgets to override the default GtkWidget handling for determining whether an accelerator can be activated.

### The "child-notify" gtk.Widget Signal

        def callback(widget, child_property, user_param1, ...)

`widget` : | the widget that received the signal
`child_property` : | the name of a child property
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "child-notify" signal is emitted when `child_property` is changed.

Child properties are available with objects derived from `gtk.Container`. Those properties are not specific to either the container or the child widget but to their relation. For example, the "pack-type" property of `gtk.Box` or the "menu-label" property of `gtk.Notebook` are child properties.

### The "client-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "client-event" signal is emitted when another application has sent an event to `widget`.

### The "composited-changed" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the object which received the signal.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### The "configure-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "configure-event" signal is emitted when the widget's window is allocated a size and width.

### The "damage-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "damage-event" signal is emitted when a redirected window belonging to widget gets drawn into. The region/area members of the event shows what area of the redirected drawable was drawn into.

### The "delete-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "delete-event" signal is emitted when a request is made to delete `widget`.

### The "destroy-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "destroy-event" signal is emitted when a `gtk.gdk.Window` is destroyed. You rarely get this signal, because most widgets disconnect themselves from their window before they destroy it, so no widget owns the window at destroy time.

### The "direction-changed" gtk.Widget Signal

        def callback(widget, direction, user_param1, ...)

`widget` : | the widget that received the signal
`direction` : | the previous direction: `gtk.TEXT_DIR_NONE`, `gtk.TEXT_DIR_LTR` or `gtk.TEXT_DIR_RTL`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "direction-changed" signal is emitted when the reading direction of `widget` is changed (usually with the `set_direction`() method)

### The "drag-begin" gtk.Widget Signal

        def callback(widget, drag_context, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "drag-begin" signal is emitted when the user initiates a drag operation on `widget`. A typical reason to connect to this signal is to set up a custom drag icon with the `drag_source_set_icon`() method.

### The "drag-data-delete" gtk.Widget Signal

        def callback(widget, drag_context, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "drag-data-delete" signal is emitted when the drag completes a move operation and requires the source data to be deleted. The signal handler is responsible for deleting the data that has been dropped.

### The "drag-data-get" gtk.Widget Signal

        def callback(widget, drag_context, selection_data, info, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`selection_data` : | a `gtk.SelectionData` object
`info` : | an integer ID for the drag
`timestamp` : | the time of the drag event
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "drag-data-get" signal is emitted when a drag operation completes that copies data or when a drag drop occurs using the `gtk.gdk.DRAG_PROTO_ROOTWIN` protocol. The drag source revceives this signal when the drag destination requests the data using the `drag_get_data`() method. The handler needs to fill `selection_data` with the data in the format specified by the target associated with `info`.

### The "drag-data-received" gtk.Widget Signal

        def callback(widget, drag_context, x, y, selection_data, info, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`x` : | the X position of the drop
`y` : | the Y position of the drop
`selection_data` : | a `gtk.SelectionData` object
`info` : | an integer ID for the drag
`timestamp` : | the time of the drag event
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "drag-data-received" signal is emitted when the drag destination receives the data from the drag operation. If the data was received in order to determine whether the drop will be accepted, the handler is expected to call the `gtk.gdk.DragContext.drag_status`() method and not finish the drag. If the data was received in response to a "drag-drop" signal (and this is the last target to be received), the handler for this signal is expected to process the received data and then call the `gtk.gdk.DragContext.finish`() method, setting the `success` parameter to `True` if the data was processed successfully.

### The "drag-drop" gtk.Widget Signal

        def callback(widget, drag_context, x, y, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`x` : | the X position of the drop
`y` : | the Y position of the drop
`timestamp` : | the time of the drag event
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the cursor is in a drop zone

The "drag-drop" signal is emitted when the drag initiates a drop operation on the destination `widget`. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns `False` and no further processing is necessary. Otherwise, the handler returns `True`. In this case, the handler must ensure that the `gtk.gdk.DragContext.finish`() method is called to let the source know that the drop is done. The call to the `gtk.gdk.DragContext.finish`() method can be done either directly or in a "drag-data-received" handler that gets triggered by calling the `drag_get_data`() method to receive the data for one or more of the supported targets.

### The "drag-end" gtk.Widget Signal

        def callback(widget, drag_context, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "drag-end" signal is emitted when the drag operation is completed. A typical reason to connect to this signal is to undo things done in a "drag-begin" handler.

### The "drag-failed" gtk.Widget Signal

        def callback(widget, drag_context, result, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`result` : | the result of the drag operation.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the failed drag operation has been already handled.

The "drag-failed" signal is emitted on the drag source when a drag has failed. The signal handler may hook custom code to handle a failed DND operation based on the type of error, it returns `True` is the failure has been already handled (not showing the default "drag operation failed" animation), otherwise it returns `False`.

### The "drag-leave" gtk.Widget Signal

        def callback(widget, drag_context, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`timestamp` : | the time of the drag event
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "drag-leave" signal is emitted when the drag operation moves off of a drop target widget. A typical reason to connect to this signal is to undo things done in a "drag-motion" handler, e.g. undo highlighting with the `drag_unhighlight`() method.

### The "drag-motion" gtk.Widget Signal

        def callback(widget, drag_context, x, y, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`drag_context` : | the `gtk.gdk.DragContext`
`x` : | the X position of the drop
`y` : | the Y position of the drop
`timestamp` : | the time of the drag event
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the cursor is in a drop zone

The "drag-motion" signal is emitted when the drag operation moves over a drop target widget. The signal handler must determine if the cursor position is in a drop zone or not. If it is not in a drop zone, it should return `False` and no further processing is necessary. Otherwise, the handler should return `True`. In this case, the handler is responsible for providing the necessary information for displaying feedback to the user, by calling the `gtk.gdk.DragContext.drag_status`() method. If the decision to accept or reject the drop can't be made based solely on the cursor position and the type of the data, the handler may inspect the dragged data by calling the `drag_get_data`() method and defer the `gtk.gdk.DragContext.drag_status`() method call to the "drag-data-received" handler.

### Note

There is no "drag-enter" signal. The drag receiver has to keep track of any "drag-motion" signals received since the last "drag-leave" signal. The first "drag-motion" signal received after a "drag_leave" signal should be treated as an "enter" signal. Upon an "enter", the handler will typically highlight the drop site with the `drag_highlight`() method.

### The "enter-notify-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "enter-notify-event" signal is emitted when the mouse pointer enters `widget`.

### The "event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "event" signal is emitted when any `gtk.gdk.Event` occurs on `widget`. The "event" signal is emitted before any of the specific `gtk.gdk.Event` signals are emitted.

### The "event-after" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "event-after" signal is emitted after any other event handling has occurred for `widget`

### The "expose-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "expose-event" signal is emitted when `widget` needs to be repainted because it is first displayed or has been partially or fully obscured by another window.

### The "focus" gtk.Widget Signal

        def callback(widget, direction, user_param1, ...)

`widget` : | the widget that received the signal
`direction` : | the direction: `gtk.DIR_TAB_FORWARD`, `gtk.DIR_TAB_BACKWARD`, `gtk.DIR_UP`, `gtk.DIR_DOWN`, `gtk.DIR_LEFT` or `gtk.DIR_RIGHT`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "focus" signal is emitted when `widget` receives the focus.

### The "focus-in-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "focus-in-event" signal is emitted when the focus changes to `widget`.

### The "focus-out-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "focus-out-event" signal is emitted when the focus leaves `widget`.

### The "grab-broken-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the object which received the signal.
`event` : | the gtk.gdk.EventGrabBroken event
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

### Note

This signal is available in GTK+ 2.8 and above.

Emitted when a pointer or keyboard grab on a window belonging to `widget` gets broken.

On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again.

### The "grab-focus" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "grab-focus" signal is emitted when `widget` grabs the focus usually by calling the `grab_focus`() method or by the user using a mnemonic accelerator..

### The "grab-notify" gtk.Widget Signal

        def callback(widget, was_grabbed, user_param1, ...)

`widget` : | the widget that received the signal
`was_grabbed` : | if `True` `widget` had grabbed the focus
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "grab-notify" signal is emitted when widget (or its ancestor) either is grabbing the focus or has the focus grabbed from it.

### The "hide" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "hide" signal is emitted when `widget` is hidden usually by calling the `hide`() method.

### The "hierarchy-changed" gtk.Widget Signal

        def callback(widget, previous_toplevel, user_param1, ...)

`widget` : | the widget that received the signal
`previous_toplevel` : | the toplevel widget in the previous hierarchy containing `widget`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "hierarchy-changed" signal is emitted when `widget` is unparented or has a new parent set.

### The "key-press-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "key-press-event" signal is emitted when the user presses a key on the keyboard.

### The "keynav-failed" gtk.Widget Signal

        def callback(widget, direction, user_param1, ...)

`widget` : | the widget that received the signal
`direction` : | the direction of movement.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if stopping keyboard navigation is fine, `False` if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).

The "key-press-event" signal gets emitted if keyboard navigation fails. See `gtk.Widget.keynav_failed` () for details.

### The "key-release-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "key-release-event" signal is emitted when the user releases a key on the keyboard.

### The "leave-notify-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "leave-notify-event" signal is emitted when the mouse pointer leaves the area of `widget`.

### The "map" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "map" signal is emitted when `widget` requests to be mapped onto the display usually by calling the `show`() or `map`() methods.

### The "map-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "map-event" signal is emitted when `widget` has been mapped onto the display.

### The "mnemonic-activate" gtk.Widget Signal

        def callback(widget, group_cycling, user_param1, ...)

`widget` : | the widget that received the signal
`group_cycling` : | if `True` shifts the focus instead of activating `widget`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "mnemonic-activate" signal is emitted when the user uses a mnemonic accelerator to activate `widget`.

### The "motion-notify-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "motion-notify-event" signal is emitted when the mouse pointer moves while over `widget`.

### The "no-expose-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further

The "no-expose-event" signal is emitted when a no expose event occurs.

### The "parent-set" gtk.Widget Signal

        def callback(widget, old_parent, user_param1, ...)

`widget` : | the widget that received the signal
`old_parent` : | the previous parent of `widget`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "parent-set" signal is emitted when the parent of `widget` is set or unset.

### The "popup-menu" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further
Returns : | `True` if a menu was activated

The "popup-menu" signal is emitted when the user presses the Shift+F10 or Menu keys when `widget` has the focus to popup a menu.

### The "property-notify-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "property-notify-event" signal is emitted when a window property value has changed. This is used for selection data retrieval.

### The "proximity-in-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "proximity-in-event" (available for devices like touch screens or graphics tablets) is emitted when the pen touches the tablet or when the user's finger touches the screen.

### The "proximity-out-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "proximity-out-event" (available for devices like touch screens or graphics tablets) is emitted when the pen leaves the tablet or when the user's finger leaves the screen.

### The "query-tooltip" gtk.Widget Signal

        def callback(widget, x, y, keyboard_mode, tooltip, user_param1, ...)

`widget` : | the widget that received the signal
`x` : | the x coordinate of the cursor position where the request has been emitted, relative to widget->window
`y` : | the y coordinate of the cursor position where the request has been emitted, relative to widget->window
`keyboard_mode` : | `True` if the tooltip was trigged using the keyboard
`tooltip` : | a `gtk.Tooltip`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if tooltip should be shown right now, `False` otherwise.

The "query-tooltip" signal is emitted when the GtkSettings:gtk-tooltip-timeout has expired with the cursor hovering "above" widget; or emitted when widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for widget. If this is the case `True` should be returned, `False` otherwise. Note that if `keyboard_mode` is `True`, the values of x and y are undefined and should not be used. The signal handler is free to manipulate tooltip with the therefore destined function calls.

### The "realize" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "realize" signal is emitted when `widget` requests to be realized by calling the `realize`() method.

### The "screen-changed" gtk.Widget Signal

        def callback(widget, screen, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.4 and above.

The "screen-changed" signal is emitted when `screen` becomes the new `gtk.gdk.Screen` for `widget`.

### The "scroll-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "scroll-event" signal is emitted when widget receives a scroll event.

### The "selection-clear-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "selection-clear-event" signal is emitted when the selection needs to be cleared.

### The "selection-get" gtk.Widget Signal

        def callback(widget, selection_data, info, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`selection_data` : | a `gtk.SelectionData` object
`info` : | an integer ID for the selection
`timestamp` : | the time the event occurred
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "selection-get" signal is emitted when the selection data is requested from `widget`.

### The "selection-notify-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "selection-notify-event" signal is emitted when the selection owner has responded to the selection conversion request.

### The "selection-received" gtk.Widget Signal

        def callback(widget, selection_data, timestamp, user_param1, ...)

`widget` : | the widget that received the signal
`selection_data` : | a `gtk.SelectionData` object
`timestamp` : | the time the event occurred
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "selection-received" signal is emitted when the selection owner has responded to the request for the selection data.

### The "selection-request-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "selection-request-event" signal is emitted when a selection request is made on `widget`.

### The "show" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "show" signal is emitted when `widget` requests to be displayed using either the `show`() or `show_all`() method.

### The "show-help" gtk.Widget Signal

        def callback(widget, help_type, user_param1, ...)

`widget` : | the widget that received the signal
`help_type` : | the help type; either `gtk.WIDGET_HELP_TOOLTIP` or `gtk.WIDGET_HELP_WHATS_THIS`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked.

The "show-help" signal is emitted when the user presses the Control+F1 key combination.

### The "size-allocate" gtk.Widget Signal

        def callback(widget, allocation, user_param1, ...)

`widget` : | the widget that received the signal
`allocation` : | the widget's space allocation in a `gtk.gdk.Rectangle`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "size-allocate" signal is emitted when widget is given a new space allocation.

### The "size-request" gtk.Widget Signal

        def callback(widget, requisition, user_param1, ...)

`widget` : | the widget that received the signal
`requisition` : | the widget's requested size as a `gtk.Requisition`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "size-request" signal is emitted when a new size is requested for `widget` using the `set_size_request`() method.

### The "state-changed" gtk.Widget Signal

        def callback(widget, state, user_param1, ...)

`widget` : | the widget that received the signal
`state` : | the previous widget state: `gtk.STATE_NORMAL`, `gtk.STATE_ACTIVE`, `gtk.STATE_PRELIGHT`, `gtk.STATE_SELECTED` or `gtk.STATE_INSENSITIVE`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "state-changed" signal is emitted when the state of `widget` changes.

### The "style-set" gtk.Widget Signal

        def callback(widget, previous_style, user_param1, ...)

`widget` : | the widget that received the signal
`previous_style` : | the previous widget `gtk.Style`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "style-set" signal is emitted when the `gtk.Style` of `widget` is set.

### The "unmap" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "unmap" signal is emitted when `widget` requests to be unmapped from the display.

### The "unmap-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "unmap-event" signal is emitted when `widget` has been unmapped from the display.

### The "unrealize" gtk.Widget Signal

        def callback(widget, user_param1, ...)

`widget` : | the widget that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "unrealize" signal is emitted when `widget` requests to be unrealized (i.e. have all its resources released).

### The "visibility-notify-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "visibility-notify-event" signal is emitted when the visibility of `widget` changes i.e. it has been obscured or unobscured.

### The "window-state-event" gtk.Widget Signal

        def callback(widget, event, user_param1, ...)

`widget` : | the widget that received the signal
`event` : | the event that triggered the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` to stop other handlers from being invoked for the event. `False` to propagate the event further.

The "window-state-event" signal is emitted when window state of widget changes. For example, for a toplevel window this event is signaled when the window is iconified, deiconified, minimized, maximized, made sticky, made not sticky, shaded or unshaded.

Prev | Up | Next
gtk.Viewport | Home | gtk.Window