The
gtk:widget class is the base class all widgets in GTK derive
from. It manages the widget life cycle, states and style.
Height-for-width Geometry Management
GTK uses a height-for-width and width-for-height geometry management system.
Height-for-width means that a widget can change how much vertical space it
needs, depending on the amount of horizontal space that it is given and
similar for width-for-height. The most common example is a label that reflows
to fill up the available width, wraps to fewer lines, and therefore needs
less height.
GTK also supports baseline vertical alignment of widgets. This means that
widgets are positioned such that the typographical baseline of widgets in the
same row are aligned. This happens if a widget supports baselines, has a vertical alignment of
:baseline, and is inside a container that
supports baselines and has a natural "row" that it aligns to the baseline,
or a baseline assigned to it by the grandparent.
If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was
:fill, but the selected baseline can be found via the
gtk:widget-allocated-baseline function. If this has a value
other than -1 you need to align the widget such that the baseline appears at
the position.
Style Properties
The
gtk:widget class 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.
Use the
gtk:widget-class-find-style-property or
gtk:widget-class-list-style-properties functions to get information about existing style properties and the
gtk:widget-style-property
function to obtain the value of a style property.
GtkWidget as GtkBuildable
The
gtk:widget implementation of the
gtk:buildable interface supports a custom
<accelerator> element, which has attributes named
key,
modifiers and
signal and allows to specify
accelerators.
Example: A UI definition fragment specifying an accelerator
<object class="GtkButton">
<accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/>
</object>
In addition to accelerators, the
gtk:widget implementation also support a custom
<accessible> element, which supports actions and
relations. Properties on the accessible implementation of an object can be set by accessing the internal child
"accessible" of a
gtk:widget
object.
Example: A UI definition fragment specifying an accessible
<object class="GtkButton" id="label1"/>
<property name="label">I am a Label for a Button</property>
</object>
<object class="GtkButton" id="button1">
<accessibility>
<action action_name="click"
translatable="yes">Click the button.</action>
<relation target="label1" type="labelled-by"/>
</accessibility>
<child internal-child="accessible">
<object class="AtkObject" id="a11y-button1">
<property name="AtkObject::name">Clickable Button</property>
</object>
</child>
</object> Finally, the
gtk:widget implementation allows style information such
as style classes to be associated with widgets, using the custom
<style> element:
Example: A UI definition fragment specifying an style class
<object class="GtkButton" id="button1">
<style>
<class name="my-special-button-class"/>
<class name="dark-button"/>
</style>
</object> Building composite widgets from template XML
The
gtk:widget implementation exposes some facilities to automate the proceedure of creating composite widgets using the
gtk:builder
interface description language.
To create composite widgets with
gtk:builder XML, one must associate
the interface description with the widget class at class initialization time using the
gtk:widget-class-set-template function.
The interface description semantics expected in composite template descriptions is slightly different from regulare
gtk:builder XML. Unlike regular interface descriptions, the
gtk:widget-class-set-template function will expect a
<template> tag as a direct child of the toplevel
<interface> tag. The
<template> tag must specify the
"class" attribute which must be the type name of the widget. Optionally, the
"parent" attribute may be specified to specify the
direct parent type of the widget type, this is ignored by the
gtk:builder object but required for Glade to introspect what kind of
properties and internal children exist for a given type when the actual type
does not exist.
The XML which is contained inside the
<template> tag behaves as if it were added to the
<object> tag defining the widget itself. You may set properties on the widget by inserting
<property> tags into the
<template> tag, and also add
<child> tags to add children and extend the widget in the normal way you would with
<object> tags.
Additionally,
<object> tags can also be added before and after the initial
<template> tag in the normal way, allowing one to define
auxilary objects which might be referenced by other widgets declared as children of the
<template> tag.
Example: A
gtk:builder template definition
<interface>
<template class="FooWidget" parent="GtkBox">
<property name="orientation">GTK_ORIENTATION_HORIZONTAL</property>
<property name="spacing">4</property>
<child>
<object class="GtkButton" id="hello_button">
<property name="label">Hello World</property>
</object>
</child>
<child>
<object class="GtkButton" id="goodbye_button">
<property name="label">Goodbye World</property>
</object>
</child>
</template>
</interface> Style Property Details
- cursor-aspect-ratio
- The cursor-aspect-ratio style property of type :float (Read)
Aspect ratio with which to draw insertion cursor.
Allowed values: [0.0,1.0]
Default value: 0.04 - cursor-color
- The cursor-color style property of type gdk:color (Read )
Color with which to draw insertion cursor. - focus-line-pattern
- The focus-line-pattern style property of type :string (Read)
Dash pattern used to draw the focus indicator.
Warning: The focus-line-pattern style property has been
deprecated since version 3.14 and should not be used in newly written code. Use the outline-style CSS property instead.
Default value: "001001" - focus-line-width
- The focus-line-width style property of type :int (Read)
Width, in pixels, of the focus indicator line.
Warning: The focus-line-width style property has been
deprecated since version 3.14 and should not be used in newly written code. Use the outline-width CSS property instead.
Allowed values: >= 0
Default value: 1 - focus-padding
- The focus-padding style property of type :int (Read)
Width, in pixels, between focus indicator and the widget 'box'.
Warning: The focus-padding style property has been
deprecated since version 3.14 and should not be used in newly written code. Use the padding CSS property instead.
Allowed values: >= 0
Default value: 1 - interior-focus
- The interior-focus style property of type :boolean (Read)
Whether to draw the focus indicator inside widgets.
Warning: The interior-focus style property has been
deprecated since version 3.14 and should not be used in newly written code. Use the outline CSS property instead.
Default value: true - link-color
- The link-color style property of type gdk:color (Read)
Defines the color of unvisited links.
Warning: The link-color style property has been
deprecated since version 3.12 and should not be used in newly written
code. Links now use a separate state flags for selecting different
theming. This style property is ignored. - scroll-arrow-hlength
- The scroll-arrow-hlength style property of type :int (Read)
Defines the length of horizontal scroll arrows.
Allowed values: >= 1
Default value: 16 - scroll-arrow-vlength
- The scroll-arrow-vlength style property of type :int (Read)
Defines the length of vertical scroll arrows.
Allowed values: >= 1
Default value: 16 - secondary-cursor-color
- The secondary-cursor-color style property of type gdk:color (Read)
Color with which to draw the secondary insertion cursor when editing
mixed right-to-left and left-to-right text. - separator-height
- The separator-height style property of type :int (Read)
Defines the height of separators. This property only takes effect if the wide-separators style property is true.
Warning: The separator-height style property has been
deprecated since version 3.20 and should not be used in newly written
code. Use the standard min-height CSS property on the separator elements to size separators. The value of this style property is ignored.
Allowed values: >= 0
Default value: 0 - separator-width
- The separator-width style property of type :int (Read)
Defines the width of separators. This property only takes effect if the wide-separators style property is true.
Warning: The separator-width style property has been
deprecated since version 3.20 and should not be used in newly written
code. Use the standard min-height CSS property on the separator elements to size separators. The value of this style property is ignored.
Allowed values: >= 0
Default value: 0 - text-handle-height
- The text-handle-height style property of type :int (Read)
Height of text selection handles.
Allowed values: >= 1
Default value: 24 - text-handle-width
- The text-handle-width style property of type :int (Read)
Width of text selection handles.
Allowed values: >= 1
Default value: 20 - visited-link-color
- The visited-link-color style property of type gdk:color (Read)
Defines the color of visited links.
Warning: The visited-link-color style property has been
deprecated since version 3.12 and should not be used in newly written
code. Links now use a separate state flags for selecting different
theming. This style property is ignored. - wide-separators
- The wide-separators style property of type :boolean (Read)
Defines whether separators have configurable width and should be drawn using a box instead of a line.
Default value: false - window-dragging
- The window-dragging style property of type :boolean (Read)
Whether windows can be dragged by clicking on empty areas.
Default value: false
Signal Details
The "accel-closures-changed" signal
lambda (widget)
- widget
- The gtk:widget object which received the signal.
The "button-press-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-button event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a button typically from a mouse is pressed. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:button-press-mask mask of the
gdk:event-mask
flags. The signal will be sent to the grab widget if there is one.
The "button-release-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-button event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a button typically from a mouse is released. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:button-realease-mask mask of the
gdk:event-mask flags. The signal will be sent to the grab widget
if there is one.
The "can-activate-accel" signal
lambda (widget signal) :run-last
- widget
- The gtk:widget object which received the signal.
- signal
- The unsigned integer with the ID of a signal installed on the widget.
- Returns
- True if the signal can be activated.
Determines whether an accelerator that activates the signal identified by
signal can currently be activated. The signal is present to allow
applications and derived widgets to override the default handling for
determining whether an accelerator can be activated.
The "child-notify" signal
lambda (widget pspec) :no-hooks
- widget
- The gtk:widget object which received the signal.
- pspec
- The g:param-spec instance of the changed child property.
Emitted for each child property that has changed on an object. The
detail of the signal holds the property name.
The "composited-changed" signal
lambda (widget) :action
- widget
- The gtk:widget object on which the signal is emitted.
Emitted when the composited status of widgets screen changes.
Warning: The
"composited-changed" signal has been deprecated
since version 3.22 and should not be used in newly written code. Use the
"composited-changed" signal of the
gdk:screen class
instead.
The "configure-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-configure event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the size, position or stacking of the GDK window of the widget has changed. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:structure-mask mask of the
gdk:event-mask flags. GDK will enable this mask
automatically for all new windows.
The "damage-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-expose event.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a redirected window belonging to the widget gets drawn into.
The region/area members of the event shows what area of the redirected
drawable was drawn into.
The "delete-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted if a user requests that a toplevel window is closed. The default
handler for this signal destroys the window. Connecting the
gtk:widget-hide-on-delete function to this signal will cause the
window to be hidden instead, so that it can later be shown again without
reconstructing it.
The "destroy" signal
lambda (widget) :no-hooks
- widget
- The gtk:widget object which received the signal.
Signals that all holders of a reference to the widget should release the
reference that they hold. May result in finalization of the widget if all
references are released.
The "destroy-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a
gdk:window object is destroyed. You rarely get this
signal, because most widgets disconnect themselves from their GDK window
before they destroy it, so no widget owns the GDK window at destroy time. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:structure-mask mask of the
gdk:event-mask flags. GDK will enable this mask automatically
for all new windows.
The "direction-changed" signal
lambda (widget direction) :run-first
- widget
- The gtk:widget object on which the signal is emitted.
- direction
- The previous gtk:text-direction text direction of the widget.
Emitted when the text direction of a widget changes.
The "drag-begin" signal
lambda (widget context) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context object.
Emitted on the drag source when a drag is started. A typical reason to
connect to this signal is to set up a custom drag icon with, for example, the
gtk:drag-source-set-icon-pixbuf function. Note that some widgets
set up a drag icon in the default handler of this signal, so you may have to use the
g:signal-connect function to override what the default
handler did.
The "drag-data-delete" signal
lambda (widget context) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context object.
Emitted on the drag source when a drag with the
:move action of the
gdk:drag-action flags 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.
The "drag-data-get" signal
lambda (widget context selection info time) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context object.
- selection
- The gtk:selection-data instance to be filled with the dragged data.
- info
- The unsigned integer with the info that has been registered with the target in the gtk:target-list instance.
- time
- The unsigned integer with the timestamp at which the data was requested.
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 the
selection argument with the data in the format which is indicated by the
info argument. See the
gtk:selection-data-set and
gtk:selection-data-text functions.
The "drag-data-received" signal
lambda (widget context x y selection info time) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context drag context.
- x
- The integer where the drop happened.
- y
- The integer where the drop happened.
- selection
- The received gtk:selection-data data.
- info
- The unsigned integer with the info that has been registered with the target in the gtk:target-list instance.
- time
- The unsigned integer with the timestamp at which the data was received.
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 the
gdk:drag-status function 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:drag-finish function, setting the success
parameter depending on whether the data was processed successfully.
Applications must create some means to determine why the signal was emitted and therefore whether to call the
gdk:drag-status or
gtk:drag-finish functions. The handler may inspect the selected action with the
gdk:drag-context-selected-action function before calling the
gtk:drag-finish function, for example, to implement the
:ask value of the
gdk:drag-action flags as shown in the
following example:
void
drag_data_received (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
GtkSelectionData *data,
guint info,
guint time)
{
if ((data->length >= 0) && (data->format == 8))
{
GdkDragAction action;
// handle data here
action = gdk_drag_context_get_selected_action (context);
if (action == GDK_ACTION_ASK)
{
GtkWidget *dialog;
gint response;
dialog = gtk_message_dialog_new (NULL,
GTK_DIALOG_MODAL |
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_MESSAGE_INFO,
GTK_BUTTONS_YES_NO,
"Move the data ?n");
response = gtk_dialog_run (GTK_DIALOG (dialog));
gtk_widget_destroy (dialog);
if (response == GTK_RESPONSE_YES)
action = GDK_ACTION_MOVE;
else
action = GDK_ACTION_COPY;
}
gtk_drag_finish (context, TRUE, action == GDK_ACTION_MOVE, time);
}
else
gtk_drag_finish (context, FALSE, FALSE, time);
} The "drag-drop" signal
lambda (widget context x y time) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context drag context.
- x
- The integer with the x coordinate of the current cursor position.
- y
- The integer with the y coordinate of the current cursor position.
- time
- The unsigned integer with the timestamp of the motion event.
- Returns
- The boolean whether the cursor position is in a drop zone.
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 the
gtk:drag-finish function is called to let the source know that the drop is done. The call to the
gtk:drag-finish function can be done either directly or in a
"drag-data-received" signal handler which gets triggered by calling the
gtk:drag-data function to receive the
data for one or more of the supported targets.
The "drag-end" signal
lambda (widget context) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context drag context.
Emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in the
"drag-begin"
signal handler.
The "drag-failed" signal
lambda (widget context result) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context drag context.
- result
- The gtk:drag-result result of the drag operation.
- Returns
- True if the failed drag operation has been already handled.
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 if the failure has been already handled, not
showing the default "drag operation failed" animation, otherwise it returns
false.
The "drag-leave" signal
lambda (widget context time) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context drag context.
- time
- The unsigned integer with the timestamp of the motion event.
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 a
"drag-motion" signal handler, for example, undo highlighting with the
gtk:drag-unhighlight function. Likewise, the
"drag-leave" signal is also emitted before the
"drag-drop" signal, for instance to allow cleaning up of a preview item created in the
"drag-motion" signal handler.
The "drag-motion" signal
lambda (widget context x y time) :run-last
- widget
- The gtk:widget object which received the signal.
- context
- The gdk:drag-context drag context.
- x
- The integer with the x coordinate of the current cursor position.
- y
- The integer with the y coordinate of the current cursor position.
- time
- The unsigned integer with the timestamp of the motion event.
- Returns
- The boolean whether the cursor position is in a drop zone.
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 the
gdk:drag-status function.
If the decision whether the drop will be accepted or rejected cannot be
made based solely on the cursor position and the type of the data, the handler may inspect the dragged data by calling the
gtk:drag-data function and defer the
gdk:drag-status function call to the
"drag-data-received" signal handler. Note that you cannot pass the
:drop,
:motion or
:all values of the
gtk:dest-defaults flags to the
gtk:drag-dest-set function when using the
"drag-motion" signal that way.
Also 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" signal and if not, treat the
"drag-motion" signal as an
"enter" signal. Upon an
"enter", the handler will typically highlight the drop site with the
gtk:drag-highlight function.
static void
drag_motion (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
guint time)
{
GdkAtom target;
PrivateData *private_data = GET_PRIVATE_DATA (widget);
if (!private_data->drag_highlight)
{
private_data->drag_highlight = 1;
gtk_drag_highlight (widget);
}
target = gtk_drag_dest_find_target (widget, context, NULL);
if (target == GDK_NONE)
gdk_drag_status (context, 0, time);
else
{
private_data->pending_status = context->suggested_action;
gtk_drag_get_data (widget, context, target, time);
}
return TRUE;
}
static void
drag_data_received (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
GtkSelectionData *selection_data,
guint info,
guint time)
{
PrivateData *private_data = GET_PRIVATE_DATA (widget);
if (private_data->suggested_action)
{
private_data->suggested_action = 0;
/* We are getting this data due to a request in drag_motion,
* rather than due to a request in drag_drop, so we are just
* supposed to call gdk_drag_status (), not actually paste in
* the data.
*/
str = gtk_selection_data_get_text (selection_data);
if (!data_is_acceptable (str))
gdk_drag_status (context, 0, time);
else
gdk_drag_status (context, private_data->suggested_action, time);
}
else
{
/* accept the drop */
}
} The "draw" signal
lambda (widget cr) :run-last
- widget
- The gtk:widget object which received the signal.
- cr
- The gdk:cairo-context Cairo context to draw to.
Emitted when a widget is supposed to render itself. The top left corner
of the widget must be painted at the origin of the passed in Cairo context
and be sized to the values returned by the
gtk:widget-allocated-width and
gtk:widget-allocated-height
functions. Signal handlers connected to this signal can modify the Cairo
context in any way they like and do not need to restore it. The signal emission takes care of calling the
cairo:save function before and the
cairo:restore function after invoking the handler.
The "enter-notify-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-crossing event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the pointer enters the GDK window of the widget. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:enter-notify-mask mask of the
gdk:event-mask flags. The signal will be sent to the grab widget
if there is one.
The "event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for
the event and to cancel the emission of the second specific "event" signal. False to propagate the event further and to allow the emission of the second signal. The "event-after" signal is emitted regardless of the return value.
The GTK main loop will emit three signals for each GDK event delivered to a widget: one generic
"event" signal, another, more specific,
signal that matches the type of event delivered, for example, the
"key-press-event" signal, and finally a generic
"event-after" signal.
The "event-after" signal
lambda (widget event)
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event event which triggered this signal.
After the emission of the
"event" signal and optionally the second more specific signal, the
"event-after" signal will be
emitted regardless of the previous two signals handlers return values.
The "focus" signal
lambda (widget direction) :run-last
- widget
- The gtk:widget object which received the signal.
- direction
- The gtk:direction-type direction.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
The "focus-in-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-focus event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the keyboard focus enters the GDK window of the widget. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:focus-change-mask mask of the
gdk:event-mask flags.
The "focus-out-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-focus event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false topropagate the event further.
Emitted when the keyboard focus leaves the GDK window of the widget. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:focus-change-mask mask of the
gdk:event-mask flags.
The "grab-broken-event" signal
lambda (widget event) : run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-grab-broken event.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a pointer or keyboard grab on a GDK window belonging to
the widget gets broken. On X11, this happens when the grab window becomes
unviewable, that is, it or one of its ancestors is unmapped, or if the
same application grabs the pointer or keyboard again.
The "grab-focus" signal
lambda (widget) :action
- widget
- The gtk:widget object which received the signal.
The "grab-notify" signal
lambda (widget grabbed) :run-first
- widget
- The gtk:widget object which received the signal.
- grabbed
- False if the widget becomes shadowed, true if it becomes unshadowed.
Emitted when a widget becomes shadowed by a GTK grab, not a pointer or
keyboard grab, on another widget, or when it becomes unshadowed due to a grab being removed. A widget is shadowed by a the
gtk:grab-add
function when the topmost grab widget in the grab stack of its window
group is not its ancestor.
The "hide" signal
lambda (widget) :run-first
- widget
- The gtk:widget object which received the signal.
Emitted when the widget is hidden, for example with the
gtk:widget-hide function.
The "hierarchy-changed" signal
lambda (widget toplevel) :run-last
- widget
- The gtk:widget object on which the signal is emitted.
- toplevel
- The previous gtk:widget toplevel ancestor, or nil if the widget was previously unanchored.
Emitted when the anchored state of a widget changes. A widget is anchored when its toplevel ancestor is a
gtk:window widget. The signal is
emitted when a widget changes from un-anchored to anchored or vice-versa.
The "key-press-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-key event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a key is pressed. The signal emission will reoccur at the
key-repeat rate when the key is kept pressed. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:key-press-mask mask of the
gdk:event-mask flags. This
signal will be sent to the grab widget if there is one.
The "key-release-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-key event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a key is released. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:key-release-mask mask of the
gdk:event-mask flags. This
signal will be sent to the grab widget if there is one.
The "keynav-failed" signal
lambda (widget direction) :run-last
- widget
- The gtk:widget object which received the signal.
- direction
- The gtk:direction-type direction of movement.
- Returns
- True if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).
Gets emitted if keyboard navigation fails.
The "leave-notify-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-crossing event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the pointer leaves the GDK window of the widget. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:leave-notify-mask mask of the
gdk:event-mask flags. The signal will be sent to the grab widget
if there is one.
The "map" signal
lambda (widget) :run-first
- widget
- The gtk:widget object which received the signal.
Emitted when the widget is going to be mapped, that is when the widget is visible, which is controlled with the
gtk:widget-visible
function, and all its parents up to the toplevel widget are also visible. Once the map has occurred, the
"map-event" signal will be emitted. The
"map" signal can be used to determine whether a
widget will be drawn, for instance it can resume an animation that was stopped during the emission of the
"unmap" signal.
The "map-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the GDK window of the widget is mapped. A window is mapped
when it becomes visible on the screen. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:structure-mask mask of the
gdk:event-mask flags. GDK will
enable this mask automatically for all new windows.
The "mnemonic-activate" signal
lambda (widget cycling) :run-last
- widget
- The gtk:widget object which received the signal.
- cycling
- True if there are other widgets with the same mnemonic.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
The default handler for this signal activates the widget if the
cycling argument is
false, or just makes the widget grab focus if the
cycling argument is
true.
The "motion-notify-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-motion event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the pointer moves over the GDK window of the widget. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:pointer-motion-mask mask of the
gdk:event-mask flags. The signal will be sent to the grab widget
if there is one.
The "move-focus" signal
lambda (widget direction) :action
- widget
- The gtk:widget object which received the signal.
- direction
- The gtk:direction-type direction.
The "parent-set" signal
lambda (widget parent) :run-first
- widget
- The gtk:widget object on which the signal is emitted.
- parent
- The previous gtk:widget parent, or nil if the widget just got its initial parent.
Emitted when a new parent has been set on a widget.
The "popup-menu" signal
lambda (widget) :action
- widget
- The gtk:widget object which received the signal.
- Returns
- True if a menu was activated.
Gets emitted whenever a widget should pop up a context 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.
The "property-notify-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-property event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a property on the GDK window of the widget has been changed or deleted. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:property-change-mask mask of the
gdk:event-mask flags.
The "proximity-in-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-proximity event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event. False to propagate the event further.
To receive this signal the
gdk:window object associated to the widget needs to enable the
:proximity-in-mask mask of the
gdk:event-mask flags. The signal will be sent to the grab widget
if there is one.
The "proximity-out-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-proximity event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
To receive this signal the
gdk:window object associated to the widget needs to enable the
:proximity-out-mask mask of the
gdk:event-mask flags. The signal will be sent to the grab widget
if there is one.
The "query-tooltip" signal
lambda (widget x y mode tooltip) :run-last
- widget
- The gtk:widget object which received the signal.
- x
- The integer with the x coordinate of the cursor position where the request has been emitted, relative to the left side of the widget.
- y
- The integer with the y coordinate of the cursor position where the request has been emitted, relative to the top of the widget.
- mode
- True if the tooltip was trigged using the keyboard.
- tooltip
- The gtk:tooltip object.
- Returns
- True if tooltip should be shown right now, false otherwise.
Emitted when the
has-tooltip property is
true and the
gtk-tooltip-timeout setting has expired with the
cursor hovering "above" widget, or emitted when the widget got focus in
keyboard mode. Using the given coordinates, the signal handler should
determine whether a tooltip should be shown for the widget. If this is the case
true should be returned,
false otherwise. Note that if the
mode argument is
true, the
x and
y values are
undefined and should not be used. The signal handler is free to manipulate the
tooltip argument with the therefore destined function calls.
The "realize" signal
lambda (widget) :run-first
- widget
- The gtk:widget object which received the signal.
Emitted when the widget is associated with a
gdk:window object, which means that the
gtk:widget-realize function has been called or
the widget has been mapped, that is, it is going to be drawn.
The "screen-changed" signal
lambda (widget screen) :run-last
- widget
- The gtk:widget object on which the signal is emitted.
- screen
- The previous gdk:screen object, or nil if the widget was not associated with a screen before.
Gets emitted when the screen of a widget has changed.
The "scroll-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-scroll event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when a button in the 4 to 7 range is pressed. Wheel mice are
usually configured to generate button press events for buttons 4 and 5 when the wheel is turned. To receive this signal, the
gdk:window
object associated to the widget needs to enable the
:button-press-mask mask of the
gdk:event-mask flags. This
signal will be sent to the grab widget if there is one.
The "selection-clear-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-selection event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the the GDK window of the widget has lost ownership of a
selection.
The "selection-get" signal
lambda (widget data info time) :run-last
- widget
- The gtk:widget object which received the signal.
- data
- The gtk:selection-data instance.
- info
- The unsigned integer with the info that has been registered with the target.
- time
- The unsigned integer with the timestamp at which the data was requested.
The "selection-notify-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-selection event.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
The "selection-received" signal
lambda (widget data time) :run-last
- widget
- The gtk:widget object which received the signal.
- data
- The gtk:selection-data instance.
- time
- The unsigned integer with the timestamp.
The "selection-request-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-selection event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when another client requests ownership of the selection owned by
the GDK window of the widget.
The "show" signal
lambda (widget)
- widget
- The gtk:widget object which received the signal.
Emitted when the widget is shown, for example with the
gtk:widget-show function.
The "show-help" signal
lambda (widget help) :action
- widget
- The gtk:widget object which received the signal.
- help
- The gtk:widget-help-type value.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
The "size-allocate" signal
lambda (widget allocation) :run-first
- widget
- The gtk:widget object which received the signal.
- allocation
- The gdk:rectangle instance with the region which has been allocated to the widget.
The "state-changed" signal
lambda (widget state) :run-first
- widget
- The gtk:widget object which received the signal.
- state
- The previous gtk:state-type state.
Emitted when the widget state changes.
Warning: The
"state-changed" signal is deprecated since
version 3.0 and should not be used in newly written code. Use the
"state-flags-changed" signal instead.
The "state-flags-changed" signal
lambda (widget flags) :run-first
- widget
- The gtk:widget object which received the signal.
- flags
- The previous gtk:state-flags state flags.
Emitted when the widget state changes.
The "style-set" signal
lambda (widget style) :run-first
- widget
- The gtk:widget object on which the signal is emitted.
- style
- The previous GtkStyle style, or nil if the widget just got its initial style.
Emitted when a new style has been set on a widget.
Warning: The
"style-set" signal has been deprecated since
version 3.0 and should not be used in newly written code. Use the
"style-updated" signal.
The "style-updated" signal
lambda (widget) :run-first
- widget
- The gtk:widget object on which the signal is emitted.
Emitted when the
gtk:style-context object of a widget is changed.
Note that style-modifying functions like the
gtk:widget-override-color function also cause this signal to be
emitted.
The "touch-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object on which the signal is emitted.
- event
- The gdk:event event.
The "unmap" signal
lambda (widget) :run-first
- widget
- The gtk:widget object which received the signal.
Emitted when the widget is going to be unmapped, which means that either
it or any of its parents up to the toplevel widget have been set as hidden. As the
"unmap" signal indicates that a widget will not
be shown any longer, it can be used to, for example, stop an animation on
the widget.
The "unmap-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the GDK window of the widget is unmapped. A window is
unmapped when it becomes invisible on the screen. To receive this signal, the
gdk:window object associated to the widget needs to enable the
:structure-mask mask of the
gdk:event-mask flags. GDK
will enable this mask automatically for all new windows.
The "unrealize" signal
lambda (widget) :run-last
- widget
- The gtk:widget object which received the signal.
Emitted when the
gdk:window object associated with the widget is destroyed, which means that the
gtk:widget-unrealize function
has been called or the widget has been unmapped, that is, it is going to
be hidden.
The "visibility-notify-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-visibility event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the GDK window of the widget is obscured or unobscured. To receive this signal the
gdk:window object associated to the widget needs to enable the
:visibility-notify-mask mask of the
gdk:event-mask flags.
Warning: The
"visibility-notify-event" signal has been
deprecated since version 3.12 and should not be used in newly written
code. Modern composited windowing systems with pervasive transparency
make it impossible to track the visibility of a window reliably, so this
signal can not be guaranteed to provide useful information.
The "window-state-event" signal
lambda (widget event) :run-last
- widget
- The gtk:widget object which received the signal.
- event
- The gdk:event-window-state event which triggered this signal.
- Returns
- True to stop other handlers from being invoked for the event, false to propagate the event further.
Emitted when the state of the toplevel window associated to the widget changes. To receive this signal the
gdk:window object associated to the widget needs to enable the
:structure-mask mask of the
gdk:event-mask flags. GDK will enable this mask automatically
for all new windows.