Detail

The base class for all widgets. While a widget cannot be created directly,
this module contains many useful methods common to all widgets. In
particular, these functions are needed to add functionality to
blank widgets such as DrawingArea or Layout.

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.

Widgets receive events, that is, signals that indicate some low-level
user iteraction. The signal handlers for all these events have to
return True if the signal has been dealt with and False if other
signal handlers should be run.

Methods

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

Shows a widget. If the widget is an unmapped toplevel widget (i.e. a
Window 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.

Destroys a widget. Equivalent to
Graphics.UI.Gtk.Abstract.Object.objectDestroy.

When a widget is destroyed it will be removed from the screen and
unrealized. 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. The widget will be garbage collected
(finalized) time after your last reference to the widget dissapears.

In most cases, only toplevel widgets (windows) require explicit
destruction, because when you destroy a toplevel its children will be
destroyed as well.

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
Graphics.UI.Gtk.Display.Label.Label,
Graphics.UI.Gtk.Display.Label.Label queues a resize to ensure there's
enough space for the new text.

This function is typically used when implementing a
Graphics.UI.Gtk.Abstract.Container.Container 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
widgetSizeAllocate.

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.

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

This function differs from widgetSizeRequest in that it retrieves the
last size request value stored in the widget, while widgetSizeRequest
actually emits the sizeRequest signal on the widget to compute the size
request (which updates the widget's requisition information).

Since this function does not emit the sizeRequest signal, it can only be
used when you know that the widget's requisition is up-to-date, that is,
widgetSizeRequest has been called since the last time a resize was
queued. In general, only container implementations have this information;
applications should use widgetSizeRequest.

Installs an accelerator for this widget in accelGroup that causes
accelSignal to be emitted if the accelerator is activated. The
accelGroup needs to be added to the widget's toplevel via
windowAddAccelGroup, and the signal must be of type G_RUN_ACTION.
Accelerators added through this function are not user changeable during
runtime. If you want to support accelerators that can be changed by the
user, use accelMapAddEntry and widgetSetAccelPath or
menuItemSetAccelPath instead.

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

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

Even when you you aren't using ItemFactory, if you only want to set up
accelerators on menu items menuItemSetAccelPath provides a somewhat more
convenient interface.

Determines whether an accelerator that activates the signal identified by
signalId can currently be activated. This is done by emitting the
canActivateAccel signal on the widget the signal is attached to; 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.

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.

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

Causes widget to have the keyboard focus for the Window it's inside.
widget must be a focusable widget, such as a
Graphics.UI.Gtk.Entry.Entry; something like
Graphics.UI.Gtk.Ornaments.Frame won't work. (More precisely, it must have
the widgetCanFocus flag set.)

Causes widget to become the default widget. widget must have the
canDefault flag set. The default widget is
activated when the user presses Enter in a window. Default widgets must be
activatable, that is, widgetActivate should affect them.

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.

This function thows an error if the widget has not yet been realized, since
a widget does not allocate its window resources until just before it is
displayed on the screen. You can use the
Graphics.UI.Gtk.Abstract.Widget.onRealize signal to give you the
opportunity to use a widget's DrawWindow as soon as it has been created
but before the widget is displayed.

Remove events from the EventMask of this widget. The event mask
determines which events a widget will receive. Events are signals
that return an Event data type. On connecting to a such a signal,
the event mask is automatically adjusted so that he signal is emitted.
This function is useful to disable the reception of the signal. It
should be called whenever all signals receiving an Event
have been disconected.

Sets the event mask (see EventMask) 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 widgetAddEvents for
widgets that are already realized, or if you want to preserve the existing
event mask. This function can't be used with NoWindow widgets; to get
events on those widgets, place them inside a
Graphics.UI.Gtk.Misc.EventBox and receive events on the event box.

Gets the first ancestor of widget with type widgetType. For example,
widgetGetAncestor widget gTypeBox gets the first Box that's
an ancestor of widget. See note about checking for a toplevel
Window in the docs for widgetGetToplevel.

Obtains the location of the mouse pointer in widget coordinates. Widget
coordinates are a bit odd; for historical reasons, they are defined as
widgetGetParentWindow coordinates for widgets that are not NoWindow widgets,
and are relative to the widget's allocation's (x,y) for
widgets that are NoWindow widgets.

Just (destX, destY) - X and Y position
relative to destWidget. Returns Nothing if
either widget was not realized, or there was no
common ancestor.

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

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

Replaces the default, usually yellow, window used for displaying tooltips with customWindow. GTK+
will take care of showing and hiding customWindow at the right moment, to behave likewise as the
default tooltip window. If customWindow is Nothing, the default tooltip window will be used.

If the custom window should have the default theming it needs to have the name 'gtk-tooltip', see
widgetSetName.

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

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

The returned pixmap can be Nothing, if the resulting clipArea was empty.

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 widgetGetName. 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 widgetSetName. By setting the name of a
widget, you allow users or theme authors to apply styles to that specific
widget in their gtkrc file. Also returns the path in reverse
order, i.e. starting with the widget's name instead of starting with the
name of the widget's outermost ancestor.

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
widgetSetStyle. The RcStyle 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.

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

Caution: passing the style back to widgetModifyStyle will normally end
up destroying it, because widgetModifyStyle 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.

Sets the background color for a widget in a particular state. All other
style values are left untouched. See also widgetModifyStyle.

Note that "no window" widgets (which have the NoWindow flag set) draw
on their parent container's window and thus may not draw any background
themselves. This is the case for e.g. Label. To modify the background of
such widgets, you have to set the background color on their parent; if you
want to set the background of a rectangular area around a label, try placing
the label in a EventBox widget and setting the background color on that.

Sets the text color for a widget in a particular state. All other style
values are left untouched. The text color is the foreground color used along
with the base color (see widgetModifyBase) for widgets such as Entry and
TextView. See also widgetModifyStyle.

Sets the base color for a widget in a particular state. All other style
values are left untouched. The base color is the background color used along
with the text color (see widgetModifyText) for widgets such as Entry and
TextView. See also widgetModifyStyle.

Note that "no window" widgets (which have the NoWindow flag set) draw
on their parent container's window and thus may not draw any background
themselves. This is the case for e.g. Label. To modify the background of
such widgets, you have to set the base color on their parent; if you want to
set the background of a rectangular area around a label, try placing the
label in a EventBox widget and setting the base color on that.

Gets a PangoContext with the appropriate font description and base
direction for this widget. Unlike the context returned by
widgetCreatePangoContext, 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
layoutContextChanged on the layout
in response to the onStyleChanged and onDirectionChanged signals for the
widget.

The PangoLayout represents the rendered text. It can be shown on screen
by calling drawLayout.

The returned PangoLayout shares the same font information (PangoContext) as this
widget. If this information changes, the PangoLayout should change. The
following code ensures that the displayed text always reflects the widget's
settings:

A convenience function that uses the theme engine and RC file settings
for widget to look up the stock icon and render it to a
Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf.
The icon should be one of the stock id constants such as
Graphics.UI.Gtk.General.StockItems.stockOpen. size should be a
size such as Graphics.UI.Gtk.General.IconFactory.IconSizeMenu.
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 Graphics.UI.Gtk.Gdk.Pixbuf.Pixbuf are
shared with the rest of the
application and should not be modified.

Invalidates the rectangular area of widget defined by x, y, width
and height by calling
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowInvalidateRect on the widget's
Graphics.UI.Gtk.Gdk.DrawWindow.DrawWindow 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 function in widget implementations. In
particular, you might use it, or
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowInvalidateRect directly, to
schedule a redraw of a Graphics.UI.Gtk.Gdk.DrawWindow.DrawingArea or some
portion thereof.

Frequently you can just call
Graphics.UI.Gtk.Gdk.DrawWindow.windowInvalidateRect or
Graphics.UI.Gtk.Gdk.DrawWindow.windowInvalidateRegion instead of this
function. Those functions 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.

Sets whether the application intends to draw on the widget in response
to an onExpose signal.

This is a hint to the widget and does not affect the behavior of the
GTK+ core; many widgets ignore this flag entirely. For widgets that do
pay attention to the flag, such as EventBox and Window, the effect
is to suppress default themed drawing of the widget's background.
(Children of the widget will still be drawn.) The application is then
entirely responsible for drawing the widget background.

Widgets are double buffered by default; you can use this function to turn
off the buffering. "Double buffered" simply means that
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowBeginPaintRegion and
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowEndPaint are called automatically
around expose events sent to the widget.
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowBeginPaintRegion diverts all
drawing to a widget's window to an offscreen buffer, and
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowEndPaint
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.

Note: if you turn off double-buffering, you have to handle expose events,
since even the clearing to the background color or pixmap will not happen
automatically (as it is done in
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowBeginPaint).

Sets whether the entire widget is queued for drawing when its 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
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 its 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.

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 Viewport, which does support scrolling.

region - a Region in the same coordinate system as the
widget's allocation. That is, relative to the widget's
DrawWindow for NoWindow widgets; relative to the parent
DrawWindow of the widget's DrawWindow for widgets with
their own DrawWindow.

returns A region holding the intersection of the widget and
region. The coordinates of the return value are relative to
the widget's DrawWindow, if it has one, otherwise
it is relative to the parent's DrawWindow.

Computes the intersection of a widget's area and region, returning
the intersection. The result may be empty, use
Graphics.UI.Gtk.Gdk.Region.regionEmpty to check.

Returns the accessible object that describes the widget to an assistive
technology.

If no accessibility library is loaded (i.e. no ATK implementation library
is loaded via GTK_MODULES or via another application library, such as
libgnome), then this Object instance may be a no-op. Likewise, if no
class-specific Object implementation is available for the widget instance
in question, it will inherit an Object implementation from the first
ancestor class for which such an implementation is defined.

The documentation of the ATK library contains more information about
accessible objects and their uses.

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

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 widgetGrabFocus to place the focus
accordingly; if returning False, they don't modify the current focus
location.

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
Window at the top.

The root window is useful for such purposes as creating a popup
DrawWindow 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.

Gets the size request that was explicitly set for the widget using
widgetSetSizeRequest. A value of -1 for width or height
indicates that that dimension has not been set explicitly and the natural
requisition of the widget will be used intead. See widgetSetSizeRequest.
To get the size a widget will actually use, call widgetSizeRequest instead
of this function.

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

The child visibility can be set for widget before it is added to a
container with widgetSetParent, 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.

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, Graphics.UI.Gtk.Windows.Window.windowSetDefaultSize
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, Graphics.UI.Gtk.Windows.Window.windowSetGeometryHints 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."

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

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 mainDoEvent so the event will behave as if it
were in the event queue. Don't synthesize expose events; instead, use windowInvalidateRect
to invalidate a region of the window.

Sets the text of tooltip to be the given string, which is marked up with the Pango text markup
language. Also see tooltipSetMarkup.

This is a convenience property which will take care of getting the tooltip shown if the given string
is not "": hasTooltip will automatically be set to True and there will be taken care of
queryTooltip in the default signal handler.

This is a convenience property which will take care of getting the tooltip shown if the given string
is not "": hasTooltip will automatically be set to True and there will be taken care of
queryTooltip in the default signal handler.

Enables or disables the emission of queryTooltip on widget. A value of True indicates that widget
can have a tooltip, in this case the widget will be queried using queryTooltip 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
Windows 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.

Signals

The widget should allocate any resources needed, in particular, the
widget's DrawWindow is created. If you connect to this signal and
you rely on some of these resources to be present, you have to use
System.Glib.Signals.after.

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

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 Entry widget
creates a menu with clipboard commands.

Emitted when hasTooltip is True and the gtkTooltipTimeout 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 if widget got focus in keyboard mode, Point is Nothing.

The signal handler is free to manipulate tooltip with the therefore destined function calls.

The deleteEvent signal is emitted if a user requests that a toplevel
window is closed. The default handler for this signal destroys the window.
Calling widgetHide and returning True on reception of this signal will
cause the window to be hidden instead, so that it can later be shown again
without reconstructing it.

The destroyEvent signal is emitted when a DrawWindow 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. However, you might want to connect to the objectDestroy
signal of Object.

The part that needs to be redrawn is available via eventArea and
eventRegion. The options are, in order of efficiency: (a) redraw the
entire window, (b) ask for the eventArea and redraw that rectangle, (c)
ask for the eventRegion and redraw each of those rectangles.

Only the exposed region will be updated; see also
drawWindowBeginPaintRegion.

The mouse pointer has moved. Since receiving all mouse movements is
expensive, it is necessary to specify exactly what mouse motions are
required by calling widgetAddEvents on this widget with one or more of
the following flags:

If the application cannot respond quickly enough to all mouse motions,
it is possible to only receive motion signals on request. In this case,
you need to add PointerMotionHintMask to the flags above and call
Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowGetPointer each time a
motion even is received. Motion events will then be delayed until the
function is called.

This event is useful for the DrawingArea. On receiving this signal
the content of the passed Rectangle or Region needs to be redrawn.
The return value should be True if the region was completely redrawn
and False if other handlers in the chain should be invoked.
If a client will redraw the whole area and is not interested in the
extra information in Expose, it is more efficient
to use onExposeRect.

Widgets that are very expensive to re-render, such as an image editor,
may prefer to use the onExpose call back which delivers a
Region in addition to a Rectangle. A Region consists of several
rectangles that need redrawing. The simpler onExposeRect event encodes
the area to be redrawn as a bounding rectangle which might be easier
to deal with in a particular application.

If hint is False, a callback for every movement of the mouse is
generated. To avoid a backlog of mouse messages, it is usually sufficient
to sent hint to True, generating only one event. The
application now has to state that it is ready for the next message by
calling Graphics.UI.Gtk.Gdk.DrawWindow.drawWindowGetPointer.