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 Trueshow_all()
should not affect this widget. Available in GTK+ 2.4 and above.

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.

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.

Methods

gtk.Widget.get_allocation

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

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.

gtk.Widget.drag_dest_set_proxy

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.

gtk.Widget.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

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.

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.

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.

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.

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

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

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

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.

gtk.Widget.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

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.

gtk.Widget.get_toplevel

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:

gtk.Widget.get_screen

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

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

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

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

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

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

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.

gtk.Widget.modify_text

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

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

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

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.

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

gtk.Widget.drag_dest_set_track_motion

Note

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

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

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.

Note

You have to connect to the "query-tooltip"
signal a callback to decide if the custom_window should be shown or not, return True
if you want to show the custom_window, False otherwise.
You have also to set the property "has-tooltip" to True or the "query-tooltip"
signal will not be emitted.

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

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.

Functions

gtk.widget_push_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_set_default_colormap

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_visual

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_class_install_style_property

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