gtk.Widget

gtk.Widget
Prev	The gtk Class Reference	Next

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

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

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

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, ...)`
"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-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, ...)`
"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, ...)`
"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.