Description

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

Details

GtkWidget

typedef struct {
/* The style for the widget. The style contains the
* colors the widget should be drawn in for each state
* along with graphics contexts used to draw with and
* the font to use for text.
*/
GtkStyle *style;
/* The widgets desired size.
*/
GtkRequisition requisition;
/* The widgets allocated size.
*/
GtkAllocation allocation;
/* The widgets window or its parent window if it does
* not have a window. (Which will be indicated by the
* GTK_NO_WINDOW flag being set).
*/
GdkWindow *window;
/* The widgets parent.
*/
GtkWidget *parent;
} GtkWidget;

GtkWidgetClass

typedef struct {
/* The object class structure needs to be the first
* element in the widget class structure in order for
* the class mechanism to work correctly. This allows a
* GtkWidgetClass pointer to be cast to a GtkObjectClass
* pointer.
*/
GtkObjectClass parent_class;
guint activate_signal;
guint set_scroll_adjustments_signal;
} GtkWidgetClass;

activate_signal
The signal to emit when a widget of this class is activated,
gtk_widget_activate() handles the emission. Implementation of this
signal is optional.

set_scroll_adjustment_signal
This signal is emitted when a widget of this class is added
to a scrolling aware parent, gtk_widget_set_scroll_adjustments()
handles the emission.
Implementation of this signal is optional.

Set and unset by gtk_widget_set_sensitive().
The sensitivity of a widget determines whether it will receive
certain events (e.g. button or key presses). One premise for
the widgets sensitivity is to have this flag set.

GTK_PARENT_SENSITIVE

Set and unset by gtk_widget_set_sensitive() operations on the
parents of the widget.
This is the second premise for the widgets sensitivity. Once
it has GTK_SENSITIVE and GTK_PARENT_SENSITIVE set, its state is
effectively sensitive. This is expressed (and can be examined) by
the GTK_WIDGET_IS_SENSITIVE macro.

GTK_CAN_FOCUS

Determines whether a widget is able to handle focus grabs.

GTK_HAS_FOCUS

Set by gtk_widget_grab_focus() for widgets that also
have GTK_CAN_FOCUS set. The flag will be unset once another widget
grabs the focus.

struct GtkAllocation

struct GtkAllocation {
gint x;
gint y;
gint width;
gint height;
};

A GtkAllocation of a widget represents region which has been allocated to the
widget by its parent. It is a subregion of its parents allocation. See
the section called “Size Allocation” for more information.

enum GtkWidgetHelpType

gtk_widget_new ()

This is a convenience function for creating a widget and setting
its properties in one go. For example you might write:
gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign",
0.0, NULL) to create a left-aligned label. Equivalent to
g_object_new(), but returns a widget so you don't have to
cast the object yourself.

gtk_widget_ref ()

Adds a reference to a widget. This function is exactly the same
as calling g_object_ref(), and exists mostly for historical
reasons. It can still be convenient to avoid casting a widget
to a GObject, it saves a small amount of typing.

gtk_widget_unref ()

gtk_widget_destroy ()

Destroys a widget. Equivalent to gtk_object_destroy(), except that
you don't have to cast the widget to GtkObject. 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
GtkWindow), it will be removed from the list of toplevels, and the
reference GTK+ holds to it will be removed. Removing a
widget from its container or the list of toplevels results in the
widget being finalized, unless you've added additional references
to the widget with g_object_ref().

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

This function sets *widget_pointer to NULL if widget_pointer !=
NULL. It's intended to be used as a callback connected to the
"destroy" signal of a widget. You connect gtk_widget_destroyed()
as a signal handler, and pass the address of your widget variable
as user data. Then when the widget is destroyed, the variable will
be set to NULL. Useful for example to avoid multiple copies
of the same dialog.

gtk_widget_show ()

Flags a widget to be displayed. 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 gtk_widget_show_all() on the
container, instead of individually showing the widgets.

Remember that you have to show the containers containing a widget,
in addition to 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 ()

Shows a widget. If the widget is an unmapped toplevel widget
(i.e. a GtkWindow that has not yet been shown), enter the main
loop and wait for the window to actually be mapped. Be careful;
because the main loop is running, anything can happen during
this function.

gtk_widget_realize ()

Creates the GDK (windowing system) resources associated with a
widget. For example, widget->window will be created when a 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
gtk_widget_realize() realizes the widget's parents in addition to
widget itself. If a widget is not yet inside a toplevel window
when you realize it, bad things will happen.

This function is primarily used in widget implementations, and
isn't very useful otherwise. 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 g_signal_connect_after() to the
"realize" signal.

gtk_widget_queue_resize ()

This function is only for use in widget implementations.
Flags a widget to have its size renegotiated; should
be called when a widget for some reason has a new size request.
For example, when you change the text in a GtkLabel, GtkLabel
queues a resize to ensure there's enough space for the new text.

gtk_widget_draw ()

Warning

gtk_widget_draw is deprecated and should not be used in newly-written code.

In GTK+ 1.2, this function would immediately render the
region area of a widget, by invoking the virtual draw method of a
widget. In GTK+ 2.0, the draw method is gone, and instead
gtk_widget_draw() simply invalidates the specified region of the
widget, then updates the invalid region of the widget immediately.
Usually you don't want to update the region immediately for
performance reasons, so in general gtk_widget_queue_draw_area() is
a better choice if you want to draw a region of a widget.

gtk_widget_size_request ()

This function is typically used when implementing a GtkContainer
subclass. Obtains the preferred size of a widget. The container
uses this information to arrange its child widgets and decide what
size allocations to give them with gtk_widget_size_allocate().

You can also call this function from an application, with some
caveats. Most notably, getting a size request requires the widget
to be associated with a screen, because font information may be
needed. Multihead-aware applications should keep this in mind.

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

gtk_widget_get_child_requisition ()

This function is only for use in widget implementations. Obtains
widget->requisition, unless someone has forced a particular
geometry on the widget (e.g. with gtk_widget_set_usize()), in which
case it returns that geometry instead of the widget's requisition.

This function differs from gtk_widget_size_request() in that
it retrieves the last size request value from widget->requisition,
while gtk_widget_size_request() actually calls the "size_request" method
on widget to compute the size request and fill in widget->requisition,
and only then returns widget->requisition.

Because this function does not call the "size_request" method, it
can only be used when you know that widget->requisition is
up-to-date, that is, gtk_widget_size_request() has been called
since the last time a resize was queued. In general, only container
implementations have this information; applications should use
gtk_widget_size_request().

gtk_widget_set_accel_path ()

Given an accelerator group, accel_group, and an accelerator path,
accel_path, sets up an accelerator in accel_group so whenever the
key binding that is defined for accel_path is pressed, widget
will be activated. This removes any accelerators (for any
accelerator group) installed by previous calls to
gtk_widget_set_accel_path(). Associating accelerators with
paths allows them to be modified by the user and the modifications
to be saved for future use. (See gtk_accel_map_save().)

This function is a low level function that would most likely
be used by a menu creation system like GtkItemFactory. If you
use GtkItemFactory, setting up accelerator paths will be done
automatically.

gtk_widget_can_activate_accel ()

Determines whether an accelerator that activates the signal
identified by signal_id can currently be activated.
This is done by emitting the GtkWidget::can-activate-accel
signal on widget; 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_event ()

Rarely-used function. This function is used to emit
the event signals on a widget (those signals should never
be emitted without using this function to do so).
If you want to synthesize an event though, don't use this function;
instead, use gtk_main_do_event() so the event will behave as if
it were in the event queue. Don't synthesize expose events; instead,
use gdk_window_invalidate_rect() to invalidate a region of the
window.

gtk_widget_activate ()

For widgets that can be "activated" (buttons, menu items, etc.)
this function activates them. Activation is what happens when you
press Enter on a widget during key navigation. If widget isn't
activatable, the function returns FALSE.

gtk_widget_intersect ()

Computes the intersection of a widget's area and area, storing
the intersection in intersection, and returns TRUE if there was
an intersection. intersection may be NULL if you're only
interested in whether there was an intersection.

gtk_widget_is_focus ()

Determines if the widget is the focus widget within its
toplevel. (This does not mean that the HAS_FOCUS flag is
necessarily set; HAS_FOCUS will only be set if the
toplevel widget additionally has the global input focus.)

gtk_widget_grab_focus ()

Causes widget to have the keyboard focus for the GtkWindow it's
inside. widget must be a focusable widget, such as a GtkEntry;
something like GtkFrame won't work. (More precisely, it must have the
GTK_CAN_FOCUS flag set.)

gtk_widget_grab_default ()

Causes widget to become the default widget. widget must have the
GTK_CAN_DEFAULT flag set; typically you have to set this flag
yourself by calling GTK_WIDGET_SET_FLAGS (widget,
GTK_CAN_DEFAULT). The default widget is activated when the user
presses Enter in a window. Default widgets must be activatable,
that is, gtk_widget_activate() should affect them.

gtk_widget_set_name ()

Widgets can be named, which allows you to refer to them from a
gtkrc file. You can apply a style to widgets with a particular name
in the gtkrc file. See the documentation for gtkrc files (on the
same page as the docs for GtkRcStyle).

Note that widget names are separated by periods in paths (see
gtk_widget_path()), so names with embedded periods may cause confusion.

gtk_widget_set_state ()

This function is for use in widget implementations. Sets the state
of a widget (insensitive, prelighted, etc.) Usually you should set
the state using wrapper functions such as gtk_widget_set_sensitive().

gtk_widget_set_sensitive ()

Sets the sensitivity of a widget. A widget is sensitive if the user
can interact with it. Insensitive widgets are "grayed out" and the
user can't interact with them. Insensitive widgets are known as
"inactive", "disabled", or "ghosted" in some other toolkits.

gtk_widget_set_parent ()

This function is useful only when implementing subclasses of GtkContainer.
Sets the container as the parent of widget, and takes care of
some details such as updating the state and style of the child
to reflect its new location. The opposite function is
gtk_widget_unparent().

gtk_widget_set_uposition ()

Warning

gtk_widget_set_uposition is deprecated and should not be used in newly-written code.

Sets the position of a widget. The funny "u" in the name comes from
the "user position" hint specified by the X Window System, and
exists for legacy reasons. This function doesn't work if a widget
is inside a container; it's only really useful on GtkWindow.

Don't use this function to center dialogs over the main application
window; most window managers will do the centering on your behalf
if you call gtk_window_set_transient_for(), and it's really not
possible to get the centering to work correctly in all cases from
application code. But if you insist, use gtk_window_set_position()
to set GTK_WIN_POS_CENTER_ON_PARENT, don't do the centering
manually.

Note that although x and y can be individually unset, the position
is not honoured unless both x and y are set.

gtk_widget_set_usize ()

Warning

gtk_widget_set_usize is deprecated and should not be used in newly-written code.

Sets the minimum size of a widget; that is, the widget's size
request will be width by height. You can use this function to
force a widget to be either larger or smaller than it is. The
strange "usize" name dates from the early days of GTK+, and derives
from X Window System terminology. In many cases,
gtk_window_set_default_size() is a better choice for toplevel
windows than this function; setting the default size will still
allow users to shrink the window. Setting the usize will force them
to leave the window at least as large as the usize. When dealing
with window sizes, gtk_window_set_geometry_hints() can be a useful
function as well.

Note the inherent danger of 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 hardcode a size that will always be
correct.

gtk_widget_set_events ()

Sets the event mask (see GdkEventMask) for a widget. 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 function must be called while a widget is
unrealized. Consider gtk_widget_add_events() for widgets that are
already realized, or if you want to preserve the existing event
mask. This function can't be used with GTK_NO_WINDOW widgets;
to get events on those widgets, place them inside a GtkEventBox
and receive events on the event box.

gtk_widget_get_toplevel ()

This function returns the topmost widget in the container hierarchy
widget is a part of. If widget has no parent widgets, it will be
returned as the topmost widget. No reference will be added to the
returned widget; it should not be unreferenced.

Note the difference in behavior vs. gtk_widget_get_ancestor();
gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)
would return
NULL if widget wasn't inside a toplevel window, and if the
window was inside a GtkWindow-derived widget which was in turn
inside the toplevel GtkWindow. While the second case may
seem unlikely, it actually happens when a GtkPlug is embedded
inside a GtkSocket within the same application.

gtk_widget_get_ancestor ()

Gets the first ancestor of widget with type widget_type. For example,
gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the
first GtkBox that's
an ancestor of widget. No reference will be added to the returned widget;
it should not be unreferenced. See note about checking for a toplevel
GtkWindow in the docs for gtk_widget_get_toplevel().

gtk_widget_set_colormap ()

Sets the colormap for the widget to the given value. Widget must not
have been previously realized. This probably should only be used
from an init() function (i.e. from the constructor
for the widget).

gtk_widget_get_pointer ()

Obtains the location of the mouse pointer in widget coordinates.
Widget coordinates are a bit odd; for historical reasons, they are
defined as widget->window coordinates for widgets that are not
GTK_NO_WINDOW widgets, and are relative to widget->allocation.x,
widget->allocation.y for widgets that are GTK_NO_WINDOW widgets.

gtk_widget_translate_coordinates ()

Translate coordinates relative to src_widget's allocation to coordinates
relative to dest_widget's allocations. In order to perform this
operation, both widgets must be realized, and must share a common
toplevel.

gtk_widget_hide_on_delete ()

Utility function; intended to be connected to the "delete_event"
signal on a GtkWindow. The function calls gtk_widget_hide() on its
argument, 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, GTK+ destroys windows when "delete_event"
is received.

gtk_widget_set_style ()

Sets the GtkStyle for a widget (widget->style). You probably don't
want to use this function; it interacts badly with themes, because
themes work by replacing the GtkStyle. Instead, use
gtk_widget_modify_style().

gtk_widget_ensure_style ()

Ensures that widget has a style (widget->style). Not a very useful
function; most of the time, if you want the style, the widget is
realized, and realized widgets are guaranteed to have a style
already.

gtk_widget_push_colormap ()

Pushes cmap onto a global stack of colormaps; the topmost
colormap on the stack will be used to create all widgets.
Remove cmap with gtk_widget_pop_colormap(). There's little
reason to use this function.

gtk_widget_set_direction ()

Sets the reading direction on a particular widget. This direction
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 present in order
so that correct localization into languages with right-to-left
reading directions can be done. Generally, applications will
let the default reading direction present, except for containers
where the containers are arranged in an order that is explicitely
visual rather than logical (such as buttons for text justification).

gtk_widget_path ()

Obtains the full path to 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
gtk_widget_get_name(). 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 gtk_widget_set_name(). By setting
the name of a widget, you allow users or theme authors to apply
styles to that specific widget in their gtkrc
file. path_reversed_p fills in the path in reverse order,
i.e. starting with widget's name instead of starting with the name
of widget's outermost ancestor.

gtk_widget_modify_style ()

Modifies style values on the widget. Modifications made using this
technique take precedence over style values set via an RC file,
however, they will be overriden if a style is explicitely set on
the widget using gtk_widget_set_style(). The GtkRcStyle structure
is designed so each field can either be set or unset, so it is
possible, using this function, to modify some style values and
leave the others unchanged.

gtk_widget_get_modifier_style ()

Returns the current modifier style for the widget. (As set by
gtk_widget_modify_style().) If no style has previously set, a new
GtkRcStyle 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 gtk_widget_modify_style(), passing in the
returned rc style, to make sure that your changes take effect.

Caution: passing the style back to gtk_widget_modify_style() will
normally end up destroying it, because gtk_widget_modify_style() copies
the passed-in style and sets the copy as the new modifier style,
thus dropping any reference to the old modifier style. Add a reference
to the modifier style if you want to keep it alive.

gtk_widget_get_pango_context ()

Gets a PangoContext with the appropriate colormap, font description
and base direction for this widget. Unlike the context returned
by gtk_widget_create_pango_context(), this context is owned by
the widget (it can be used until the screen for the widget changes
or the widget is removed from its toplevel), and will be updated to
match any changes to the widget's attributes.

If you create and keep a PangoLayout using this context, you must
deal with changes to the context by calling pango_layout_context_changed()
on the layout in response to the ::style-set and ::direction-changed signals
for the widget.

gtk_widget_create_pango_layout ()

Creates a new PangoLayout with the appropriate colormap,
font description, and base direction for drawing text for
this widget.

If you keep a PangoLayout created in this way around, in order
notify the layout of changes to the base direction or font of this
widget, you must call pango_layout_context_changed() in response to
the ::style-set and ::direction-changed signals for the widget.

gtk_widget_render_icon ()

A convenience function that uses the theme engine and RC file
settings for widget to look up stock_id and render it to
a pixbuf. stock_id should be a stock icon ID such as
GTK_STOCK_OPEN or GTK_STOCK_OK. size should be a size
such as GTK_ICON_SIZE_MENU. detail should be a string that
identifies the widget or code doing the rendering, so that
theme engines can special-case rendering for that widget or code.

The pixels in the returned GdkPixbuf are shared with the rest of
the application and should not be modified. The pixbuf should be freed
after use with g_object_unref().

gtk_widget_push_composite_child ()

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 by GTK (but
see gtk_container_foreach() vs. gtk_container_forall()), but e.g. GUI
builders might want to treat them in a different way.

gtk_widget_queue_draw_area ()

Invalidates the rectangular area of widget defined by x, y,
width and height by calling gdk_window_invalidate_rect() 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.

gtk_widget_set_double_buffered ()

Widgets are double buffered by default; you can use this function
to turn off the buffering. "Double buffered" simply means that
gdk_window_begin_paint_region() and gdk_window_end_paint() are called
automatically around expose events sent to the
widget. gdk_window_begin_paint() diverts all drawing to a widget's
window to an offscreen buffer, and gdk_window_end_paint() 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 function to turn off double buffering
if you had special needs and really knew what you were doing.

gtk_widget_set_redraw_on_allocate ()

Sets whether a when a widgets size allocation changes, the entire
widget is queued for drawing. By default, this setting is TRUE and
the entire widget is redrawn on every size change. If your widget
leaves the upper left unchanged when made bigger, turning this
setting on will improve performance.

Note that for NO_WINDOW widgets setting this flag to FALSE turns
off all allocation on resizing: the widget will not even redraw 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 widget->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_scroll_adjustments ()

For widgets that support scrolling, sets the scroll adjustments and
returns TRUE. For widgets that don't support scrolling, does
nothing and returns FALSE. Widgets that don't support scrolling
can be scrolled by placing them in a GtkViewport, which does
support scrolling.

a GdkRegion, in the same coordinate system as
widget->allocation. That is, relative to widget->window
for NO_WINDOW widgets; relative to the parent window
of widget->window for widgets with their own window.

Returns :

A newly allocated region holding the intersection of widget
and region. The coordinates of the return value 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_send_expose ()

Very rarely-used function. This function is used to emit
an expose event signals on a widget. This function is not
normally used directly. The only time it is used is when
propagating an expose event to a child NO_WINDOW widget, and
that is normally done using gtk_container_propagate_expose().

gtk_widget_get_accessible ()

gtk_widget_child_focus ()

This function is used by custom widget implementations; if you're
writing an app, you'd use gtk_widget_grab_focus() to move the focus
to a particular widget, and gtk_container_set_focus_chain() to
change the focus tab order. So you may want to investigate those
functions instead.

gtk_widget_child_focus() is called by containers as the user moves
around the window using keyboard shortcuts. direction indicates
what kind of motion is taking place (up, down, left, right, tab
forward, tab backward). gtk_widget_child_focus() invokes the
"focus" signal on GtkWidget; 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
moving in direction left the focus on a focusable location inside
that widget, and FALSE if moving in direction moved the focus
outside the widget. If returning TRUE, widgets normally
call gtk_widget_grab_focus() to place the focus accordingly;
if returning FALSE, they don't modify the current focus location.

This function replaces gtk_container_focus() from GTK+ 1.2. It was
necessary to check that the child was visible, sensitive, and
focusable before calling
gtk_container_focus(). gtk_widget_child_focus() returns FALSE if
the widget is not currently in a focusable state, so there's no
need for those checks.

gtk_widget_get_root_window ()

Get the root window where this widget is located. This function can
only be called after the widget has been added to a widget
heirarchy with GtkWindow at the top.

The root window is useful for such purposes as creating a popup
GdkWindow associated with the window. In general, you should only
create display specific resources when a widget has been realized,
and you should free those resources when the widget is unrealized.

gtk_widget_set_child_visible ()

Sets whether widget should be mapped along with its when its parent
is mapped and widget has been shown with gtk_widget_show().

The child visibility can be set for widget before it is added to
a container with gtk_widget_set_parent(), to avoid mapping
children unnecessary before immediately unmapping them. However
it 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 function is only useful for container implementations and
never should be called by an application.

gtk_widget_set_size_request ()

Sets the minimum size of a widget; that is, the widget's size
request will be width by height. You can use this function to
force a widget to be either larger or smaller than it normally
would be.

In most cases, gtk_window_set_default_size() is a better choice for
toplevel windows than this function; setting the default size will
still allow users to shrink the window. Setting the size request
will force them to leave the window at least as large as the size
request. When dealing with window sizes,
gtk_window_set_geometry_hints() can be a useful function as well.

Note the inherent danger of 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 hardcode 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 function to mean "as small as possible."

gtk_widget_list_mnemonic_labels ()

Returns a newly allocated list of the widgets, normally labels, for
which this widget is a the target of a mnemonic (see for example,
gtk_label_set_mnemonic_widget()).

The widgets in the list are not individually referenced. If you
want to iterate through the list and perform actions involving
callbacks that might destroy the widgets, you
must call g_list_foreach (result,
(GFunc)g_object_ref, NULL) first, and then unref all the
widgets afterwards.

gtk_widget_add_mnemonic_label ()

Adds a widget to the list of mnemonic labels for
this widget. (See gtk_widget_list_mnemonic_labels()). Note the
list of mnemonic labels for the widget is cleared when the
widget is destroyed, so the caller must make sure to update
it's internal state at this point as well, by using a connection
to the ::destroy signal or a weak notifier.

The "can-activate-accel" signal

Determines whether an 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 "delete-event" signal

The ::delete-event signal is emitted if a user requests that
a toplevel window is closed. The default handler for this signal
destroys the window. Connecting gtk_widget_hide_on_delete() to
this signal will cause the window to be hidden instead, so that
it can later be shown again without reconstructing it.

widget :

the object which received the signal.

event :

the event which triggered this signal

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event.
FALSE to propagate the event further.

The "destroy-event" signal

The ::destroy-event signal is emitted when a GdkWindow 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.

widget :

the object which received the signal.

event :

the event which triggered this signal

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event.
FALSE to propagate the event further.

The "drag-data-delete" signal

The ::drag-data-delete signal is emitted on the drag source when a drag with the action
GDK_ACTION_MOVE is successfully completed. The signal handler is responsible for deleting
the data that has been dropped. What "delete" means, depends on the context of the drag
operation.

widget :

the object which received the signal.

drag_context :

the drag context

user_data :

user data set when the signal handler was connected.

The "drag-data-get" signal

The ::drag-data-get signal is emitted on the drag source when the drop site requests
the data which is dragged. It is the responsibility of the signal handler to fill data
with the data in the format which is indicated by info. See gtk_selection_data_set() and
gtk_selection_data_set_text().

The "drag-data-received" signal

The ::drag-data-received signal is emitted on the drop site when the dragged data has been
received. If the data was received in order to determine whether the drop will be accepted,
the handler is expected to call gdk_drag_status() 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
gtk_drag_finish(), setting the success parameter depending on whether the data was processed
successfully.

The handler may inspect and modify drag_context->action before calling gtk_drag_finish(),
e.g. to implement GDK_ACTION_ASK as shown in the following example:

The "drag-drop" signal

The ::drag-drop signal is emitted on the drop site when the user drops the data
onto the 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 gtk_drag_finish() is called to let the source know that the drop is done.
The call to gtk_drag_finish() can be done either directly or in a ::drag-data-received handler
which gets triggered by calling gtk_drop_get_data() to receive the data for one or more of the
supported targets.

The "drag-leave" signal

The ::drag-leave signal is emitted on the drop site when the cursor leaves the widget.
A typical reason to connect to this signal is to undo things done in ::drag-motion, e.g.
undo highlighting with gtk_drag_unhighlight()

widget :

the object which received the signal.

drag_context :

the drag context

time :

the timestamp of the motion event

user_data :

user data set when the signal handler was connected.

The "drag-motion" signal

The ::drag-motion signal is emitted on the drop site when the user moves the cursor over
the widget during a drag. 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 is responsible for
providing the necessary information for displaying feedback to the user, by calling
gdk_drag_status(). If the decision whether the drop will be accepted or rejected 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 gtk_drag_get_data() and defer the gdk_drag_status() call to the ::drag-data-received
handler.

Note that there is no ::drag-enter signal. The drag receiver has to keep track of whether
he has received any ::drag-motion signals since the last ::drag-leave and if not, treat the
::drag-motion signal as an "enter" signal. Upon an "enter", the handler will typically highlight
the drop site with gtk_drag_highlight().

The "hierarchy-changed" signal

Emitted when there is a chance in the hierarchy to
which a widget belong. More precisely, a widget is
anchored when its toplevel
ancestor is a GtkWindow. This signal is emitted when
a widget changes from un-anchored to anchored or vice-versa.

The "popup-menu" signal

This signal gets emitted whenever a widget should pop up a context-sensitive
menu. This usually happens through the standard key binding mechanism; by
pressing a certain key while a widget is focused, the user can cause the
widget to pop up a menu. For example, the GtkEntry widget creates a menu
with clipboard commands. See the section called “Implement GtkWidget::popup_menu” for an
example of how to use this signal.