Class widget - cl-cffi-gtk3 API documentation

Package: gtk

Class gtk:widget

Superclasses

gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

gtk:calendar, gtk:cell-view, gtk:container, gtk:drawing-area, gtk:entry, gtk:hsv, gtk:invisible, gtk:level-bar, gtk:misc, gtk:progress-bar, gtk:range, gtk:separator, gtk:spinner, gtk:switch

Direct Slots

app-paintable

The app-paintable property of type :boolean (Read / Write)
Whether the application will paint directly on the widget.
Default value: false

can-default

The can-default property of type :boolean (Read / Write)
Whether the widget can be the default widget.
Default value: false

can-focus

The can-focus property of type :boolean (Read / Write)
Whether the widget can accept the input focus.
Default value: false

composite-child

The composite-child property of type :boolean (Read)
Whether the widget is part of a composite widget.
Default value: false

double-buffered

The double-buffered property of type :boolean (Read / Write)
Whether the widget is double buffered.
Warning: The double-buffered property has been deprecated since version 3.14 and should not be used in newly written code. Widgets should not use this property.
Default value: true

events

The events property of type gdk:event-mask (Read / Write)
The event mask that decides what kind of gdk:event events this widget gets.
Default value: :structure-mask

expand

The expand property of type :boolean (Read / Write)
Whether to expand in both directions. Setting the expand property sets both hexpand and vexpand properties.
Default value: false

focus-on-click

The focus-on-click property of type :boolean (Read / Write)
Whether the widget should grab focus when it is clicked with the mouse. This property is only relevant for widgets that can take focus.
Default value: true

halign

The halign property of type gtk:align (Read / Write)
How to distribute horizontal space if the widget gets extra space.
Default value: :fill

has-default

The has-default property of type :boolean (Read / Write)
Whether the widget is the default widget.
Default value: false

has-focus

The has-focus property of type :boolean (Read / Write)
Whether the widget has the input focus.
Default value: false

The has-tooltip property of type :boolean (Read / Write)
Enables or disables the emission of the "query-tooltip" signal on the widget. A true value indicates that the widget can have a tooltip, in this case the widget will be queried using the "query-tooltip" signal 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 gdk:window objects of this widget to include leave-notify and motion-notify events. This cannot and will not be undone when the property is set to false again.
Default value: false

height-request

The height-request property of type :int (Read / Write)
Override for height request of the widget, or -1 if natural request should be used.
Allowed values: >= -1
Default value: -1

hexpand

The hexpand property of type :boolean (Read / Write)
Whether to expand horizontally.
Default value: false

hexpand-set

The hexpand-set property of type :boolean (Read / Write)
Whether to use the hexpand property.
Default value: false

is-focus

The is-focus property of type :boolean (Read / Write)
Whether the widget is the focus widget within the toplevel.
Default value: false

margin

The margin property of type :int (Read / Write)
Sets the margin of all four sides at once. If read, returns the maximum margin on any side.
Allowed values: [0,32767]
Default value: 0

margin-bottom

The margin-bottom property of type :int (Read / Write)
Margin on bottom side of the widget. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0

margin-end

The margin-end property of type :int (Read / Write)
Margin on end of the widget, horizontally. This property supports left-to-right text directions. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0

margin-left

The margin-left property of type :int (Read / Write)
Margin on left side of the widget.
Warning: The margin-left property has been deprecated since version 3.12 and should not be used in newly written code. Use the margin-start property instead.
Allowed values: [0,32767]
Default value: 0

margin-right

The margin-right property of type :int (Read / Write)
Margin on right side of the widget.
Warning: The margin-right property has been deprecated since version 3.12 and should not be used in newly written code. Use the margin-end property instead.
Allowed values: [0,32767]
Default value: 0

margin-start

The margin-start property of type :int (Read / Write)
Margin on start of the widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0

margin-top

The margin-top property of type :int (Read / Write)
Margin on top side of the widget. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0

name

The name property of type :string (Read / Write)
The name of the widget.
Default value: nil

no-show-all

The no-show-all property of type :boolean (Read / Write)
Whether the gtk:widget-show-all function should not affect this widget.
Default value: false

opacity

The opacity property of type :double (Read / Write)
The requested opacity of the widget.
Allowed values: [0.0,1.0]
Default value: 1.0

parent

The parent property of type gtk:container (Read / Write)
The parent widget of this widget, which must be a container.

receives-default

The receives-default property of type :boolean (Read / Write)
If true, the widget will receive the default action when it is focused.
Default value: false

scale-factor

The scale-factor property of type :int (Read)
The scale factor of the widget.
Allowed values: >= 1
Default value: 1

sensitive

The sensitive property of type :boolean (Read / Write)
Whether the widget responds to input.
Default value: true

style

The style property of type GtkStyle (Read / Write)
The style of the widget, which contains information about how it will look.
Warning: The style property is deprecated since version 3.0 and should not be used in newly written code. Use the gtk:style-context class instead.

The tooltip-markup property of type :string (Read / Write)
Sets the text of the tooltip to be the given string, which is marked up with the Pango text markup language. This is a convenience property which will take care of getting the tooltip shown if the given string is not nil. The has-tooltip property will automatically be set to true and there will be taken care of the "query-tooltip" signal in the default signal handler. Note that if both the tooltip-text and tooltip-markup properties are set, the last one wins.
Default value: nil

The tooltip-text property of type :string (Read / Write)
Sets the text of the tooltip to be the given string. This is a convenience property which will take care of getting the tooltip shown if the given string is not nil. The has-tooltip property will automatically be set to true and there will be taken care of the "query-tooltip" signal in the default signal handler. Note that if both the tooltip-text and tooltip-markup properties are set, the last one wins.
Default value: nil

valign

The valign property of type gtk:align (Read / Write)
How to distribute vertical space if the widget gets extra space.
Default value: :fill

vexpand

The vexpand property of type :boolean (Read / Write)
Whether to expand vertically.
Default value: false

vexpand-set

The vexpand-set property of type :boolean (Read / Write)
Whether to use the vexpand property.
Default value: false

visible

The visible property of type :boolean (Read / Write)
Whether the widget is visible.
Default value: false

width-request

The width-request property of type :int (Read / Write)
Override for width request of the widget, or -1 if natural request should be used.
Allowed values: >= -1
Default value: -1

window

The window property of type gdk:window (Read)
The GDK window of the widget if it is realized, nil otherwise.

Details

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 that received the signal.

The "button-press-event" signal

lambda (widget event)    :run-last

widget: The gtk:widget object that received the signal.
event: The gdk:event-button event that 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 that 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 that received the signal.
signal: The unsigned integer for 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 that received the signal.
pspec: The g:param-spec instance for 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 for the info that has been registered with the target in the gtk:target-list instance.
time: The unsigned integer for 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 that 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 for the info that has been registered with the target in the gtk:target-list instance.
time: The unsigned integer for 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 that received the signal.
context: The gdk:drag-context drag context.
x: The integer for the x coordinate of the current cursor position.
y: The integer for the y coordinate of the current cursor position.
time: The unsigned integer for 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 that 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 that 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 that received the signal.
context: The gdk:drag-context drag context.
time: The unsigned integer for 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 that received the signal.
context: The gdk:drag-context drag context.
x: The integer for the x coordinate of the current cursor position.
y: The integer for the y coordinate of the current cursor position.
time: The unsigned integer for 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 that received the signal.
cr: The cairo:context-t instance 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that received the signal.

The "grab-notify" signal

lambda (widget grabbed)    :run-first

widget: The gtk:widget object that 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 that received the signal.

Emitted when the widget is hidden, for example with the gtk:widget-hide function.

The "hierachy-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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 "property-notify-event" signal

lambda (widget event)    :run-last

widget: The gtk:widget object that 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 that 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 that 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 "realize" signal

lambda (widget)    :run-first

widget: The gtk:widget object that 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 that 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 that 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 that received the signal.
data: The gtk:selection-data instance.
info: The unsigned integer for the info that has been registered with the target.
time: The unsigned integer for the timestamp at which the data was requested.

The "selection-notify-event" signal

lambda (widget event)    :run-last

widget: The gtk:widget object that 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 that received the signal.
data: The gtk:selection-data instance.
time: The unsigned integer for the timestamp.

The "selection-request-event" signal

lambda (widget event)    :run-last

widget: The gtk:widget object that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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 that 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.

Slot Access Functions

Inherited Slot Access Functions

g:object-has-reference

g:object-pointer