Next: , Previous: GtkSeparator, Up: Top


138 GtkWidget

Base class for all widgets

138.1 Overview

introduces style properties - these are basically object properties that are stored not on the object, but in the style object associated to the widget. Style properties are set in resource files. This mechanism is used for configuring such things as the location of the scrollbar arrows through the theme, giving theme authors more control over the look of applications without the need to write a theme engine in C.

Use gtk-widget-class-install-style-property to install style properties for a widget class, gtk-widget-class-find-style-property or gtk-widget-class-list-style-properties to get information about existing style properties and gtk-widget-style-get-property, gtk-widget-style-get or gtk-widget-style-get-valist to obtain the value of a style property.

138.2 Usage

— Class: <gtk-widget>

Derives from <atk-implementor-iface>, <gtk-buildable>, <gtk-object>.

This class defines the following slots:

name
The name of the widget
parent
The parent widget of this widget. Must be a Container widget
width-request
Override for width request of the widget, or -1 if natural request should be used
height-request
Override for height request of the widget, or -1 if natural request should be used
visible
Whether the widget is visible
sensitive
Whether the widget responds to input
app-paintable
Whether the application will paint directly on the widget
can-focus
Whether the widget can accept the input focus
has-focus
Whether the widget has the input focus
is-focus
Whether the widget is the focus widget within the toplevel
can-default
Whether the widget can be the default widget
has-default
Whether the widget is the default widget
receives-default
If TRUE, the widget will receive the default action when it is focused
composite-child
Whether the widget is part of a composite widget
style
The style of the widget, which contains information about how it will look (colors etc)
events
The event mask that decides what kind of GdkEvents this widget gets
extension-events
The mask that decides what kind of extension events this widget gets
no-show-all
Whether gtk_widget_show_all() should not affect this widget
has-tooltip
Whether this widget has a tooltip
tooltip-markup
The contents of the tooltip for this widget
tooltip-text
The contents of the tooltip for this widget
— Signal on <gtk-widget>: composited-changed
— Signal on <gtk-widget>: show
— Signal on <gtk-widget>: hide
— Signal on <gtk-widget>: map
— Signal on <gtk-widget>: unmap
— Signal on <gtk-widget>: realize
— Signal on <gtk-widget>: unrealize
— Signal on <gtk-widget>: size-request (arg0 <gtk-requisition>)
— Signal on <gtk-widget>: size-allocate (arg0 <gdk-rectangle>)
— Signal on <gtk-widget>: state-changed (arg0 <gtk-state-type>)
— Signal on <gtk-widget>: parent-set (arg0 <gtk-widget>)

The parent-set signal is emitted when a new parent has been set on a widget.

— Signal on <gtk-widget>: hierarchy-changed (arg0 <gtk-widget>)

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

— Signal on <gtk-widget>: style-set (arg0 <gtk-style>)

The style-set signal is emitted when a new style has been set on a widget. Note that style-modifying functions like gtk-widget-modify-base also cause this signal to be emitted.

— Signal on <gtk-widget>: direction-changed (arg0 <gtk-text-direction>)
— Signal on <gtk-widget>: grab-notify (arg0 <gboolean>)

The ::grab-notify signal is 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 gtk-grab-add when the topmost grab widget in the grab stack of its window group is not its ancestor.

— Signal on <gtk-widget>: child-notify (arg0 <gparam>)

The ::child-notify signal is emitted for each child property that has changed on an object. The signal's detail holds the property name.

— Signal on <gtk-widget>: mnemonic-activate (arg0 <gboolean>) ⇒ <gboolean>
— Signal on <gtk-widget>: grab-focus
— Signal on <gtk-widget>: focus (arg0 <gtk-direction-type>) ⇒ <gboolean>
— Signal on <gtk-widget>: move-focus (arg0 <gtk-direction-type>)

undocumented

— Signal on <gtk-widget>: event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: event-after (arg0 <gdk-event>)
— Signal on <gtk-widget>: button-press-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: button-release-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: scroll-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: motion-notify-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: keynav-failed (arg0 <gtk-direction-type>) ⇒ <gboolean>

undocumented

— Signal on <gtk-widget>: delete-event (arg0 <gdk-event>) ⇒ <gboolean>

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

— Signal on <gtk-widget>: destroy-event (arg0 <gdk-event>) ⇒ <gboolean>

The ::destroy-event signal is emitted when a <gdk-window> is destroyed. You rarely get this signal, because most widgets disconnect themselves from their window before they destroy it, so no widget owns the window at destroy time.

— Signal on <gtk-widget>: expose-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: key-press-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: key-release-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: enter-notify-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: leave-notify-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: configure-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: focus-in-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: focus-out-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: map-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: unmap-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: property-notify-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: selection-clear-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: selection-request-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: selection-notify-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: selection-received (arg0 <gtk-selection-data>) (arg1 <guint>)
— Signal on <gtk-widget>: selection-get (arg0 <gtk-selection-data>) (arg1 <guint>) (arg2 <guint>)
— Signal on <gtk-widget>: proximity-in-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: proximity-out-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: drag-leave (arg0 <gdk-drag-context>) (arg1 <guint>)

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

— Signal on <gtk-widget>: drag-begin (arg0 <gdk-drag-context>)

The ::drag-begin signal is 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 gtk-drag-source-set-icon.

— Signal on <gtk-widget>: drag-end (arg0 <gdk-drag-context>)

The ::drag-end signal is emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in ::drag-begin.

— Signal on <gtk-widget>: drag-data-delete (arg0 <gdk-drag-context>)

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

— Signal on <gtk-widget>: drag-failed (arg0 <gdk-drag-context>) (arg1 <gtk-drag-result>) ⇒ <gboolean>

undocumented

— Signal on <gtk-widget>: drag-motion (arg0 <gdk-drag-context>) (arg1 <gint>) (arg2 <gint>) (arg3 <guint>) ⇒ <gboolean>

The ::drag-motion signal is emitted on the drop site when the user moves the cursor over the widget during a drag. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns ‘#f’ and no further processing is necessary. Otherwise, the handler returns ‘#t’. In this case, the handler is responsible for providing the necessary information for displaying feedback to the user, by calling gdk-drag-status. If the decision whether the drop will be accepted or rejected can't be made based solely on the cursor position and the type of the data, the handler may inspect the dragged data by calling gtk-drag-get-data and defer the gdk-drag-status call to the ::drag-data-received handler.

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

          
          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 */
             }
          }
— Signal on <gtk-widget>: drag-drop (arg0 <gdk-drag-context>) (arg1 <gint>) (arg2 <gint>) (arg3 <guint>) ⇒ <gboolean>

The ::drag-drop signal is emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns ‘#f’ and no further processing is necessary. Otherwise, the handler returns ‘#t’. In this case, the handler must ensure that gtk-drag-finish is called to let the source know that the drop is done. The call to gtk-drag-finish can be done either directly or in a ::drag-data-received handler which gets triggered by calling gtk-drop-get-data to receive the data for one or more of the supported targets.

— Signal on <gtk-widget>: drag-data-get (arg0 <gdk-drag-context>) (arg1 <gtk-selection-data>) (arg2 <guint>) (arg3 <guint>)

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

— Signal on <gtk-widget>: drag-data-received (arg0 <gdk-drag-context>) (arg1 <gint>) (arg2 <gint>) (arg3 <gtk-selection-data>) (arg4 <guint>) (arg5 <guint>)

The ::drag-data-received signal is emitted on the drop site when the dragged data has been received. If the data was received in order to determine whether the drop will be accepted, the handler is expected to call gdk-drag-status and not finish the drag. If the data was received in response to a ::drag-drop signal (and this is the last target to be received), the handler for this signal is expected to process the received data and then call gtk-drag-finish, setting the success parameter depending on whether the data was processed successfully.

The handler may inspect and modify drag-context->action before calling gtk-drag-finish, e.g. to implement ‘GDK_ACTION_ASK’ as shown in the following example:

          
          void
          drag_data_received (GtkWidget          *widget,
                              GdkDragContext     *drag_context,
                              gint                x,
                              gint                y,
                              GtkSelectionData   *data,
                              guint               info,
                              guint               time)
          {
            if ((data->length >= 0) && (data->format == 8))
              {
                if (drag_context->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)
                      drag_context->action = GDK_ACTION_MOVE;
                    else
                      drag_context->action = GDK_ACTION_COPY;
                   }
          
                gtk_drag_finish (drag_context, TRUE, FALSE, time);
                return;
              }
          
             gtk_drag_finish (drag_context, FALSE, FALSE, time);
           }
— Signal on <gtk-widget>: visibility-notify-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: client-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: no-expose-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: window-state-event (arg0 <gdk-event>) ⇒ <gboolean>
— Signal on <gtk-widget>: grab-broken-event (arg0 <gdk-event>) ⇒ <gboolean>

Emitted when a pointer or keyboard grab on a window belonging to widget gets broken.

On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again.

Since 2.8

— Signal on <gtk-widget>: query-tooltip (arg0 <gint>) (arg1 <gint>) (arg2 <gboolean>) (arg3 <gtk-tooltip>) ⇒ <gboolean>

undocumented

— Signal on <gtk-widget>: popup-menu ⇒ <gboolean>

This signal gets emitted whenever a widget should pop up a context-sensitive menu. This usually happens through the standard key binding mechanism; by pressing a certain key while a widget is focused, the user can cause the widget to pop up a menu. For example, the <gtk-entry> widget creates a menu with clipboard commands. See (the missing figure, checklist-popup-menu for an example of how to use this signal.

— Signal on <gtk-widget>: show-help (arg0 <gtk-widget-help-type>) ⇒ <gboolean>
— Signal on <gtk-widget>: accel-closures-changed
— Signal on <gtk-widget>: screen-changed (arg0 <gdk-screen>)
— Signal on <gtk-widget>: can-activate-accel (arg0 <guint>) ⇒ <gboolean>

Determines whether an accelerator that activates the signal identified by signal-id can currently be activated. This signal is present to allow applications and derived widgets to override the default <gtk-widget> handling for determining whether an accelerator can be activated.

— Class: <gtk-requisition>

Derives from <gboxed>.

This class defines no direct slots.

— Class: <gtk-selection-data>

Derives from <gboxed>.

This class defines no direct slots.

— Function: gtk-widget-destroy (self <gtk-widget>)
— Method: destroy

Destroys a widget. Equivalent to gtk-object-destroy, except that you don't have to cast the widget to <gtk-object>. When a widget is destroyed, it will break any references it holds to other objects. If the widget is inside a container, the widget will be removed from the container. If the widget is a toplevel (derived from <gtk-window>), it will be removed from the list of toplevels, and the reference GTK+ holds to it will be removed. Removing a widget from its container or the list of toplevels results in the widget being finalized, unless you've added additional references to the widget with g-object-ref.

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

widget
a <gtk-widget>
— Function: gtk-widget-unparent (self <gtk-widget>)
— Method: unparent

This function is only for use in widget implementations. Should be called by implementations of the remove method on <gtk-container>, to dissociate a child from the container.

widget
a <gtk-widget>
— Function: gtk-widget-show (self <gtk-widget>)
— Method: show

Flags a widget to be displayed. Any widget that isn't shown will not appear on the screen. If you want to show all the widgets in a container, it's easier to call gtk-widget-show-all on the container, instead of individually showing the widgets.

Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen.

When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped.

widget
a <gtk-widget>
— Function: gtk-widget-show-now (self <gtk-widget>)
— Method: show-now

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

widget
a <gtk-widget>
— Function: gtk-widget-hide (self <gtk-widget>)
— Method: hide

Reverses the effects of gtk-widget-show, causing the widget to be hidden (invisible to the user).

widget
a <gtk-widget>
— Function: gtk-widget-show-all (self <gtk-widget>)
— Method: show-all

Recursively shows a widget, and any child widgets (if the widget is a container).

widget
a <gtk-widget>
— Function: gtk-widget-hide-all (self <gtk-widget>)
— Method: hide-all

Recursively hides a widget and any child widgets.

widget
a <gtk-widget>
— Function: gtk-widget-map (self <gtk-widget>)
— Method: map

This function is only for use in widget implementations. Causes a widget to be mapped if it isn't already.

widget
a <gtk-widget>
— Function: gtk-widget-unmap (self <gtk-widget>)
— Method: unmap

This function is only for use in widget implementations. Causes a widget to be unmapped if it's currently mapped.

widget
a <gtk-widget>
— Function: gtk-widget-realize (self <gtk-widget>)
— Method: realize

Creates the GDK (windowing system) resources associated with a widget. For example, widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically.

Realizing a widget requires all the widget's parent widgets to be realized; calling gtk-widget-realize realizes the widget's parents in addition to widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen.

This function is primarily used in widget implementations, and isn't very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as "expose_event". Or simply g-signal-connect-after to the "realize" signal.

widget
a <gtk-widget>
— Function: gtk-widget-unrealize (self <gtk-widget>)
— Method: unrealize

This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as widget->window).

widget
a <gtk-widget>
— Function: gtk-widget-queue-draw (self <gtk-widget>)
— Method: queue-draw

Equivalent to calling gtk-widget-queue-draw-area for the entire area of a widget.

widget
a <gtk-widget>
— Function: gtk-widget-queue-resize (self <gtk-widget>)
— Method: queue-resize

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

widget
a <gtk-widget>
— Function: gtk-widget-queue-resize-no-redraw (self <gtk-widget>)
— Method: queue-resize-no-redraw

This function works like gtk-widget-queue-resize, except that the widget is not invalidated.

widget
a <gtk-widget>

Since 2.4

— Function: gtk-widget-size-request (self <gtk-widget>) (requisition <gtk-requisition>)
— Method: size-request

This function is typically used when implementing a <gtk-container> subclass. Obtains the preferred size of a widget. The container uses this information to arrange its child widgets and decide what size allocations to give them with gtk-widget-size-allocate.

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

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

See also gtk-widget-get-child-requisition.

widget
a <gtk-widget>
requisition
a <gtk-requisition> to be filled in
— Function: gtk-widget-get-child-requisition (self <gtk-widget>) (requisition <gtk-requisition>)
— Method: get-child-requisition

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

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

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

widget
a <gtk-widget>
requisition
a <gtk-requisition> to be filled in
— Function: gtk-widget-size-allocate (self <gtk-widget>) (allocation <gdk-rectangle>)
— Method: size-allocate

This function is only used by <gtk-container> subclasses, to assign a size and position to their child widgets.

widget
a <gtk-widget>
allocation
position and size to be allocated to widget
— Function: gtk-widget-add-accelerator (self <gtk-widget>) (accel_signal mchars) (accel_group <gtk-accel-group>) (accel_key unsigned-int) (accel_mods <gdk-modifier-type>) (accel_flags <gtk-accel-flags>)
— Method: add-accelerator

Installs an accelerator for this widget in accel-group that causes accel-signal to be emitted if the accelerator is activated. The accel-group needs to be added to the widget's toplevel via gtk-window-add-accel-group, and the signal must be of type ‘G_RUN_ACTION’. Accelerators added through this function are not user changeable during runtime. If you want to support accelerators that can be changed by the user, use gtk-accel-map-add-entry and gtk-widget-set-accel-path or gtk-menu-item-set-accel-path instead.

widget
widget to install an accelerator on
accel-signal
widget signal to emit on accelerator activation
accel-group
accel group for this widget, added to its toplevel
accel-key
GDK keyval of the accelerator
accel-mods
modifier key combination of the accelerator
accel-flags
flag accelerators, e.g. ‘GTK_ACCEL_VISIBLE
— Function: gtk-widget-remove-accelerator (self <gtk-widget>) (accel_group <gtk-accel-group>) (accel_key unsigned-int) (accel_mods <gdk-modifier-type>) ⇒  (ret bool)
— Method: remove-accelerator

Removes an accelerator from widget, previously installed with gtk-widget-add-accelerator.

widget
widget to install an accelerator on
accel-group
accel group for this widget
accel-key
GDK keyval of the accelerator
accel-mods
modifier key combination of the accelerator
ret
whether an accelerator was installed and could be removed
— Function: gtk-widget-set-accel-path (self <gtk-widget>) (accel_path mchars) (accel_group <gtk-accel-group>)
— Method: set-accel-path

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

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

Even when you you aren't using <gtk-item-factory>, if you only want to set up accelerators on menu items gtk-menu-item-set-accel-path provides a somewhat more convenient interface.

widget
a <gtk-widget>
accel-path
path used to look up the accelerator
accel-group
a <gtk-accel-group>.
— Function: gtk-widget-list-accel-closures (self <gtk-widget>) ⇒  (ret glist-of)
— Method: list-accel-closures

Lists the closures used by widget for accelerator group connections with gtk-accel-group-connect-by-path or gtk-accel-group-connect. The closures can be used to monitor accelerator changes on widget, by connecting to the ::accel_changed signal of the <gtk-accel-group> of a closure which can be found out with gtk-accel-group-from-accel-closure.

widget
widget to list accelerator closures for
ret
a newly allocated <g-list> of closures
— Function: gtk-widget-can-activate-accel (self <gtk-widget>) (signal_id unsigned-int) ⇒  (ret bool)
— Method: can-activate-accel

Determines whether an accelerator that activates the signal identified by signal-id can currently be activated. This is done by emitting the GtkWidget::can-activate-accel signal on widget; if the signal isn't overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped.

widget
a <gtk-widget>
signal-id
the ID of a signal installed on widget
ret
#t’ if the accelerator can be activated.

Since 2.4

— Function: gtk-widget-event (self <gtk-widget>) (event <gdk-event>) ⇒  (ret bool)
— Method: event

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

widget
a <gtk-widget>
event
a <gdk-event>
ret
return from the event signal emission (‘#t’ if the event was handled)
— Function: gtk-widget-activate (self <gtk-widget>) ⇒  (ret bool)
— Method: activate

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

widget
a <gtk-widget> that's activatable
ret
#t’ if the widget was activatable
— Function: gtk-widget-reparent (self <gtk-widget>) (new_parent <gtk-widget>)
— Method: reparent

Moves a widget from one <gtk-container> to another, handling reference count issues to avoid destroying the widget.

widget
a <gtk-widget>
new-parent
a <gtk-container> to move the widget into
— Function: gtk-widget-is-focus (self <gtk-widget>) ⇒  (ret bool)
— Method: is-focus

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

widget
a <gtk-widget>
ret
#t’ if the widget is the focus widget.
— Function: gtk-widget-grab-focus (self <gtk-widget>)
— Method: grab-focus

Causes widget to have the keyboard focus for the <gtk-window> it's inside. widget must be a focusable widget, such as a <gtk-entry>; something like <gtk-frame> won't work. (More precisely, it must have the ‘GTK_CAN_FOCUS’ flag set.)

widget
a <gtk-widget>
— Function: gtk-widget-grab-default (self <gtk-widget>)
— Method: grab-default

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

widget
a <gtk-widget>
— Function: gtk-widget-set-name (self <gtk-widget>) (name mchars)
— Method: set-name

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

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

widget
a <gtk-widget>
name
name for the widget
— Function: gtk-widget-get-name (self <gtk-widget>) ⇒  (ret mchars)
— Method: get-name

Retrieves the name of a widget. See gtk-widget-set-name for the significance of widget names.

widget
a <gtk-widget>
ret
name of the widget. This string is owned by GTK+ and should not be modified or freed
— Function: gtk-widget-set-state (self <gtk-widget>) (state <gtk-state-type>)
— Method: set-state

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

widget
a <gtk-widget>
state
new state for widget
— Function: gtk-widget-set-sensitive (self <gtk-widget>) (sensitive bool)
— Method: set-sensitive

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

widget
a <gtk-widget>
sensitive
#t’ to make the widget sensitive
— Function: gtk-widget-set-parent (self <gtk-widget>) (parent <gtk-widget>)
— Method: set-parent

This function is useful only when implementing subclasses of <gtk-container>. Sets the container as the parent of widget, and takes care of some details such as updating the state and style of the child to reflect its new location. The opposite function is gtk-widget-unparent.

widget
a <gtk-widget>
parent
parent container
— Function: gtk-widget-set-parent-window (self <gtk-widget>) (parent_window <gdk-window>)
— Method: set-parent-window

Sets a non default parent window for widget.

widget
a <gtk-widget>.
parent-window
the new parent window.
— Function: gtk-widget-get-parent-window (self <gtk-widget>) ⇒  (ret <gdk-window>)
— Method: get-parent-window

Gets widget's parent window.

widget
a <gtk-widget>.
ret
the parent window of widget.
— Function: gtk-widget-set-events (self <gtk-widget>) (events <gdk-event-mask>)
— Method: set-events

Sets the event mask (see <gdk-event-mask>) for a widget. The event mask determines which events a widget will receive. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget's functionality, so be careful. This function must be called while a widget is unrealized. Consider gtk-widget-add-events for widgets that are already realized, or if you want to preserve the existing event mask. This function can't be used with <gtk-no-window> widgets; to get events on those widgets, place them inside a <gtk-event-box> and receive events on the event box.

widget
a <gtk-widget>
events
event mask
— Function: gtk-widget-add-events (self <gtk-widget>) (events <gdk-event-mask>)
— Method: add-events

Adds the events in the bitfield events to the event mask for widget. See gtk-widget-set-events for details.

widget
a <gtk-widget>
events
an event mask, see <gdk-event-mask>
— Function: gtk-widget-set-extension-events (self <gtk-widget>) (mode <gdk-extension-mode>)
— Method: set-extension-events

Sets the extension events mask to mode. See <gdk-extension-mode> and gdk-input-set-extension-events.

widget
a <gtk-widget>
mode
bitfield of extension events to receive
— Function: gtk-widget-get-extension-events (self <gtk-widget>) ⇒  (ret <gdk-extension-mode>)
— Method: get-extension-events

Retrieves the extension events the widget will receive; see gdk-input-set-extension-events.

widget
a <gtk-widget>
ret
extension events for widget
— Function: gtk-widget-get-toplevel (self <gtk-widget>) ⇒  (ret <gtk-widget>)
— Method: get-toplevel

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

Note the difference in behavior vs. gtk-widget-get-ancestor; ‘gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)’ would return ‘#f’ if widget wasn't inside a toplevel window, and if the window was inside a <gtk-window-derived> widget which was in turn inside the toplevel <gtk-window>. While the second case may seem unlikely, it actually happens when a <gtk-plug> is embedded inside a <gtk-socket> within the same application.

To reliably find the toplevel <gtk-window>, use gtk-widget-get-toplevel and check if the ‘TOPLEVEL’ flags is set on the result.

          
           GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
           if (GTK_WIDGET_TOPLEVEL (toplevel))
             {
               [ Perform action on toplevel. ]
             }
widget
a <gtk-widget>
ret
the topmost ancestor of widget, or widget itself if there's no ancestor.
— Function: gtk-widget-get-ancestor (self <gtk-widget>) (widget_type <gtype>) ⇒  (ret <gtk-widget>)
— Method: get-ancestor

Gets the first ancestor of widget with type widget-type. For example, ‘gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)’ gets the first <gtk-box> that's an ancestor of widget. No reference will be added to the returned widget; it should not be unreferenced. See note about checking for a toplevel <gtk-window> in the docs for gtk-widget-get-toplevel.

Note that unlike gtk-widget-is-ancestor, gtk-widget-get-ancestor considers widget to be an ancestor of itself.

widget
a <gtk-widget>
widget-type
ancestor type
ret
the ancestor widget, or ‘#f’ if not found
— Function: gtk-widget-get-colormap (self <gtk-widget>) ⇒  (ret <gdk-colormap>)
— Method: get-colormap

Gets the colormap that will be used to render widget. No reference will be added to the returned colormap; it should not be unreferenced.

widget
a <gtk-widget>
ret
the colormap used by widget
— Function: gtk-widget-set-colormap (self <gtk-widget>) (colormap <gdk-colormap>)
— Method: set-colormap

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

widget
a <gtk-widget>
colormap
a colormap
— Function: gtk-widget-get-visual (self <gtk-widget>) ⇒  (ret <gdk-visual>)
— Method: get-visual

Gets the visual that will be used to render widget.

widget
a <gtk-widget>
ret
the visual for widget
— Function: gtk-widget-get-events (self <gtk-widget>) ⇒  (ret int)
— Method: get-events

Returns the event mask for the widget (a bitfield containing flags from the <gdk-event-mask> enumeration). These are the events that the widget will receive.

widget
a <gtk-widget>
ret
event mask for widget
— Function: gtk-widget-get-pointer (self <gtk-widget>) ⇒  (int) (int)
— Method: get-pointer

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

widget
a <gtk-widget>
x
return location for the X coordinate, or ‘#f
y
return location for the Y coordinate, or ‘#f
— Function: gtk-widget-is-ancestor (self <gtk-widget>) (ancestor <gtk-widget>) ⇒  (ret bool)
— Method: is-ancestor

Determines whether widget is somewhere inside ancestor, possibly with intermediate containers.

widget
a <gtk-widget>
ancestor
another <gtk-widget>
ret
#t’ if ancestor contains widget as a child, grandchild, great grandchild, etc.
— Function: gtk-widget-translate-coordinates (self <gtk-widget>) (dest_widget <gtk-widget>) (src_x int) (src_y int) ⇒  (ret bool) (dest_x int) (dest_y int)
— Method: translate-coordinates

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

src-widget
a <gtk-widget>
dest-widget
a <gtk-widget>
src-x
X position relative to src-widget
src-y
Y position relative to src-widget
dest-x
location to store X position relative to dest-widget
dest-y
location to store Y position relative to dest-widget
ret
#f’ if either widget was not realized, or there was no common ancestor. In this case, nothing is stored in *dest-x and *dest-y. Otherwise ‘#t’.
— Function: gtk-widget-hide-on-delete (self <gtk-widget>) ⇒  (ret bool)
— Method: hide-on-delete

Utility function; intended to be connected to the "delete_event" signal on a <gtk-window>. The function calls gtk-widget-hide on its argument, then returns ‘#t’. If connected to "delete_event", the result is that clicking the close button for a window (on the window frame, top right corner usually) will hide but not destroy the window. By default, GTK+ destroys windows when "delete_event" is received.

widget
a <gtk-widget>
ret
#t
— Function: gtk-widget-set-style (self <gtk-widget>) (style <gtk-style>)
— Method: set-style

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

widget
a <gtk-widget>
style
a <gtk-style>, or ‘#f’ to remove the effect of a previous gtk-widget-set-style and go back to the default style
— Function: gtk-widget-ensure-style (self <gtk-widget>)
— Method: ensure-style

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

widget
a <gtk-widget>
— Function: gtk-widget-get-style (self <gtk-widget>) ⇒  (ret <gtk-style>)
— Method: get-style

Simply an accessor function that returns widget->style.

widget
a <gtk-widget>
ret
the widget's <gtk-style>
— Function: gtk-widget-reset-rc-styles (self <gtk-widget>)
— Method: reset-rc-styles

Reset the styles of widget and all descendents, so when they are looked up again, they get the correct values for the currently loaded RC file settings.

This function is not useful for applications.

widget
a <gtk-widget>.
— Function: gtk-widget-push-colormap (cmap <gdk-colormap>)

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

cmap
a <gdk-colormap>
— Function: gtk-widget-pop-colormap

Removes a colormap pushed with gtk-widget-push-colormap.

— Function: gtk-widget-set-default-colormap (colormap <gdk-colormap>)

Sets the default colormap to use when creating widgets. gtk-widget-push-colormap is a better function to use if you only want to affect a few widgets, rather than all widgets.

colormap
a <gdk-colormap>
— Function: gtk-widget-get-default-style ⇒  (ret <gtk-style>)

Returns the default style used by all widgets initially.

ret
the default style. This <gtk-style> object is owned by GTK+ and should not be modified or freed.
— Function: gtk-widget-get-default-colormap ⇒  (ret <gdk-colormap>)

Obtains the default colormap used to create widgets.

ret
default widget colormap
— Function: gtk-widget-get-default-visual ⇒  (ret <gdk-visual>)

Obtains the visual of the default colormap. Not really useful; used to be useful before gdk-colormap-get-visual existed.

ret
visual of the default colormap
— Function: gtk-widget-set-direction (self <gtk-widget>) (dir <gtk-text-direction>)
— Method: set-direction

Sets the reading direction on a particular widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitely visual rather than logical (such as buttons for text justification).

If the direction is set to ‘GTK_TEXT_DIR_NONE’, then the value set by gtk-widget-set-default-direction will be used.

widget
a <gtk-widget>
dir
the new direction
— Function: gtk-widget-get-direction (self <gtk-widget>) ⇒  (ret <gtk-text-direction>)
— Method: get-direction

Gets the reading direction for a particular widget. See gtk-widget-set-direction.

widget
a <gtk-widget>
ret
the reading direction for the widget.
— Function: gtk-widget-set-default-direction (dir <gtk-text-direction>)

Sets the default reading direction for widgets where the direction has not been explicitly set by gtk-widget-set-direction.

dir
the new default direction. This cannot be ‘GTK_TEXT_DIR_NONE’.
— Function: gtk-widget-get-default-direction ⇒  (ret <gtk-text-direction>)

Obtains the current default reading direction. See gtk-widget-set-default-direction.

ret
the current default direction.
— Function: gtk-widget-shape-combine-mask (self <gtk-widget>) (shape_mask <gdk-drawable>) (offset_x int) (offset_y int)
— Method: shape-combine-mask

Sets a shape for this widget's GDK window. This allows for transparent windows etc., see gdk-window-shape-combine-mask for more information.

widget
a <gtk-widget>.
shape-mask
shape to be added, or ‘#f’ to remove an existing shape.
offset-x
X position of shape mask with respect to window.
offset-y
Y position of shape mask with respect to window.
— Function: gtk-widget-input-shape-combine-mask (self <gtk-widget>) (shape_mask <gdk-drawable>) (offset_x int) (offset_y int)
— Method: input-shape-combine-mask

Sets an input shape for this widget's GDK window. This allows for windows which react to mouse click in a nonrectangular region, see gdk-window-input-shape-combine-mask for more information.

widget
a <gtk-widget>.
shape-mask
shape to be added, or ‘#f’ to remove an existing shape.
offset-x
X position of shape mask with respect to window.
offset-y
Y position of shape mask with respect to window.

Since 2.10

— Function: gtk-widget-path (self <gtk-widget>) ⇒  (path_length unsigned-int) (path mchars) (path_reversed mchars)
— Method: path

Obtains the full path to widget. The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. The name of a widget comes from gtk-widget-get-name. Paths are used to apply styles to a widget in gtkrc configuration files. Widget names are the type of the widget by default (e.g. "GtkButton") or can be set to an application-specific value with gtk-widget-set-name. By setting the name of a widget, you allow users or theme authors to apply styles to that specific widget in their gtkrc file. path-reversed-p fills in the path in reverse order, i.e. starting with widget's name instead of starting with the name of widget's outermost ancestor.

widget
a <gtk-widget>
path-length
location to store length of the path, or ‘#f
path
location to store allocated path string, or ‘#f
path-reversed
location to store allocated reverse path string, or ‘#f
— Function: gtk-widget-class-path (self <gtk-widget>) ⇒  (path_length unsigned-int) (path mchars) (path_reversed mchars)
— Method: class-path

Same as gtk-widget-path, but always uses the name of a widget's type, never uses a custom name set with gtk-widget-set-name.

widget
a <gtk-widget>
path-length
location to store the length of the class path, or ‘#f
path
location to store the class path as an allocated string, or ‘#f
path-reversed
location to store the reverse class path as an allocated string, or ‘#f
— Function: gtk-widget-get-composite-name (self <gtk-widget>) ⇒  (ret mchars)
— Method: get-composite-name

Obtains the composite name of a widget.

widget
a <gtk-widget>.
ret
the composite name of widget, or ‘#f’ if widget is not a composite child. The string should not be freed when it is no longer needed.
— Function: gtk-widget-modify-style (self <gtk-widget>) (style <gtk-rc-style>)
— Method: modify-style

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

Note that modifications made with this function are not cumulative with previous calls to gtk-widget-modify-style or with such functions as gtk-widget-modify-fg. If you wish to retain previous values, you must first call gtk-widget-get-modifier-style, make your modifications to the returned style, then call gtk-widget-modify-style with that style. On the other hand, if you first call gtk-widget-modify-style, subsequent calls to such functions gtk-widget-modify-fg will have a cumulative effect with the initial modifications.

widget
a <gtk-widget>
style
the <gtk-rc-style> holding the style modifications
— Function: gtk-widget-get-modifier-style (self <gtk-widget>) ⇒  (ret <gtk-rc-style>)
— Method: get-modifier-style

Returns the current modifier style for the widget. (As set by gtk-widget-modify-style.) If no style has previously set, a new <gtk-rc-style> will be created with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you must call gtk-widget-modify-style, passing in the returned rc style, to make sure that your changes take effect.

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

widget
a <gtk-widget>
ret
the modifier style for the widget. This rc style is owned by the widget. If you want to keep a pointer to value this around, you must add a refcount using g-object-ref.
— Function: gtk-widget-modify-fg (self <gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)
— Method: modify-fg

Sets the foreground color for a widget in a particular state. All other style values are left untouched. See also gtk-widget-modify-style.

widget
a <gtk-widget>.
state
the state for which to set the foreground color.
color
the color to assign (does not need to be allocated), or ‘#f’ to undo the effect of previous calls to of gtk-widget-modify-fg.
— Function: gtk-widget-modify-bg (self <gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)
— Method: modify-bg

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

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

widget
a <gtk-widget>.
state
the state for which to set the background color.
color
the color to assign (does not need to be allocated), or ‘#f’ to undo the effect of previous calls to of gtk-widget-modify-bg.
— Function: gtk-widget-modify-text (self <gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)
— Method: modify-text

Sets the text color for a widget in a particular state. All other style values are left untouched. The text color is the foreground color used along with the base color (see gtk-widget-modify-base) for widgets such as <gtk-entry> and <gtk-text-view>. See also gtk-widget-modify-style.

widget
a <gtk-widget>.
state
the state for which to set the text color.
color
the color to assign (does not need to be allocated), or ‘#f’ to undo the effect of previous calls to of gtk-widget-modify-text.
— Function: gtk-widget-modify-base (self <gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)
— Method: modify-base

Sets the base color for a widget in a particular state. All other style values are left untouched. The base color is the background color used along with the text color (see gtk-widget-modify-text) for widgets such as <gtk-entry> and <gtk-text-view>. See also gtk-widget-modify-style.

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

widget
a <gtk-widget>.
state
the state for which to set the base color.
color
the color to assign (does not need to be allocated), or ‘#f’ to undo the effect of previous calls to of gtk-widget-modify-base.
— Function: gtk-widget-modify-font (self <gtk-widget>) (font_desc <pango-font-description>)
— Method: modify-font

Sets the font to use for a widget. All other style values are left untouched. See also gtk-widget-modify-style.

widget
a <gtk-widget>
font-desc
the font description to use, or ‘#f’ to undo the effect of previous calls to gtk-widget-modify-font.
— Function: gtk-widget-create-pango-context (self <gtk-widget>) ⇒  (ret <pango-context>)
— Method: create-pango-context

Creates a new <pango-context> with the appropriate font map, font description, and base direction for drawing text for this widget. See also gtk-widget-get-pango-context.

widget
a <gtk-widget>
ret
the new <pango-context>
— Function: gtk-widget-get-pango-context (self <gtk-widget>) ⇒  (ret <pango-context>)
— Method: get-pango-context

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

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

widget
a <gtk-widget>
ret
the <pango-context> for the widget.
— Function: gtk-widget-create-pango-layout (self <gtk-widget>) (text mchars) ⇒  (ret <pango-layout>)
— Method: create-pango-layout

Creates a new <pango-layout> with the appropriate font map, font description, and base direction for drawing text for this widget.

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

widget
a <gtk-widget>
text
text to set on the layout (can be ‘#f’)
ret
the new <pango-layout>
— Function: gtk-widget-render-icon (self <gtk-widget>) (stock_id mchars) (size <gtk-icon-size>) (detail mchars) ⇒  (ret <gdk-pixbuf>)
— Method: render-icon

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

The pixels in the returned <gdk-pixbuf> are shared with the rest of the application and should not be modified. The pixbuf should be freed after use with g-object-unref.

widget
a <gtk-widget>
stock-id
a stock ID
size
a stock size. A size of (GtkIconSize)-1 means render at the size of the source and don't scale (if there are multiple source sizes, GTK+ picks one of the available sizes).
detail
render detail to pass to theme engine
ret
a new pixbuf, or ‘#f’ if the stock ID wasn't known
— Function: gtk-widget-pop-composite-child

Cancels the effect of a previous call to gtk-widget-push-composite-child.

— Function: gtk-widget-push-composite-child

Makes all newly-created widgets as composite children until the corresponding gtk-widget-pop-composite-child call.

A composite child is a child that's an implementation detail of the container it's inside and should not be visible to people using the container. Composite children aren't treated differently by GTK (but see gtk-container-foreach vs. gtk-container-forall), but e.g. GUI builders might want to treat them in a different way.

Here is a simple example:

          
            gtk_widget_push_composite_child ();
            scrolled_window->hscrollbar = gtk_hscrollbar_new (hadjustment);
            gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
            gtk_widget_pop_composite_child ();
            gtk_widget_set_parent (scrolled_window->hscrollbar,
                                   GTK_WIDGET (scrolled_window));
            g_object_ref (scrolled_window->hscrollbar);
— Function: gtk-widget-queue-draw-area (self <gtk-widget>) (int) (int) (width int) (height int)
— Method: queue-draw-area

Invalidates the rectangular area of widget defined by x, y, width and height by calling gdk-window-invalidate-rect on the widget's window and all its child windows. Once the main loop becomes idle (after the current batch of events has been processed, roughly), the window will receive expose events for the union of all regions that have been invalidated.

Normally you would only use this function in widget implementations. You might also use it, or gdk-window-invalidate-rect directly, to schedule a redraw of a <gtk-drawing-area> or some portion thereof.

Frequently you can just call gdk-window-invalidate-rect or gdk-window-invalidate-region instead of this function. Those functions will invalidate only a single window, instead of the widget and all its children.

The advantage of adding to the invalidated region compared to simply drawing immediately is efficiency; using an invalid region ensures that you only have to redraw one time.

widget
a <gtk-widget>
x
x coordinate of upper-left corner of rectangle to redraw
y
y coordinate of upper-left corner of rectangle to redraw
width
width of region to draw
height
height of region to draw
— Function: gtk-widget-reset-shapes (self <gtk-widget>)
— Method: reset-shapes

Recursively resets the shape on this widget and its descendants.

widget
a <gtk-widget>.
— Function: gtk-widget-set-app-paintable (self <gtk-widget>) (app_paintable bool)
— Method: set-app-paintable

Sets whether the application intends to draw on the widget in an ::expose-event handler.

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

Note that the background is still drawn when the widget is mapped. If this is not suitable (e.g. because you want to make a transparent window using an RGBA visual), you can work around this by doing:

          
           gtk_widget_realize (window);
           gdk_window_set_back_pixmap (window->window, NULL, FALSE);
           gtk_widget_show (window);
widget
a <gtk-widget>
app-paintable
#t’ if the application will paint on the widget
— Function: gtk-widget-set-double-buffered (self <gtk-widget>) (double_buffered bool)
— Method: set-double-buffered

Widgets are double buffered by default; you can use this function to turn off the buffering. "Double buffered" simply means that gdk-window-begin-paint-region and gdk-window-end-paint are called automatically around expose events sent to the widget. gdk-window-begin-paint diverts all drawing to a widget's window to an offscreen buffer, and gdk-window-end-paint draws the buffer to the screen. The result is that users see the window update in one smooth step, and don't see individual graphics primitives being rendered.

In very simple terms, double buffered widgets don't flicker, so you would only use this function to turn off double buffering if you had special needs and really knew what you were doing.

Note: if you turn off double-buffering, you have to handle expose events, since even the clearing to the background color or pixmap will not happen automatically (as it is done in gdk-window-begin-paint).

widget
a <gtk-widget>
double-buffered
#t’ to double-buffer a widget
— Function: gtk-widget-set-redraw-on-allocate (self <gtk-widget>) (redraw_on_allocate bool)
— Method: set-redraw-on-allocate

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

Note that for ‘NO_WINDOW’ widgets setting this flag to ‘#f’ turns off all allocation on resizing: the widget will not even redraw if its position changes; this is to allow containers that don't draw anything to avoid excess invalidations. If you set this flag on a ‘NO_WINDOW’ widget that does draw on widget->window, you are responsible for invalidating both the old and new allocation of the widget when the widget is moved and responsible for invalidating regions newly when the widget increases size.

widget
a <gtk-widget>
redraw-on-allocate
if ‘#t’, the entire widget will be redrawn when it is allocated to a new size. Otherwise, only the new portion of the widget will be redrawn.
— Function: gtk-widget-set-composite-name (self <gtk-widget>) (name mchars)
— Method: set-composite-name

Sets a widgets composite name. The widget must be a composite child of its parent; see gtk-widget-push-composite-child.

widget
a <gtk-widget>.
name
the name to set.
— Function: gtk-widget-set-scroll-adjustments (self <gtk-widget>) (hadjustment <gtk-adjustment>) (vadjustment <gtk-adjustment>) ⇒  (ret bool)
— Method: set-scroll-adjustments

For widgets that support scrolling, sets the scroll adjustments and returns ‘#t’. For widgets that don't support scrolling, does nothing and returns ‘#f’. Widgets that don't support scrolling can be scrolled by placing them in a <gtk-viewport>, which does support scrolling.

widget
a <gtk-widget>
hadjustment
an adjustment for horizontal scrolling, or ‘#f
vadjustment
an adjustment for vertical scrolling, or ‘#f
ret
#t’ if the widget supports scrolling
— Function: gtk-widget-mnemonic-activate (self <gtk-widget>) (group_cycling bool) ⇒  (ret bool)
— Method: mnemonic-activate
widget

group-cycling

ret
— Function: gtk-widget-region-intersect (self <gtk-widget>) (region <gdk-region>) ⇒  (ret <gdk-region>)
— Method: region-intersect

Computes the intersection of a widget's area and region, returning the intersection. The result may be empty, use gdk-region-empty to check.

widget
a <gtk-widget>
region
a <gdk-region>, in the same coordinate system as widget->allocation. That is, relative to widget->window for ‘NO_WINDOW’ widgets; relative to the parent window of widget->window for widgets with their own window.
ret
A newly allocated region holding the intersection of widget and region. The coordinates of the return value are relative to widget->window for ‘NO_WINDOW’ widgets, and relative to the parent window of widget->window for widgets with their own window.
— Function: gtk-widget-send-expose (self <gtk-widget>) (event <gdk-event>) ⇒  (ret int)
— Method: send-expose

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

If you want to force an area of a window to be redrawn, use gdk-window-invalidate-rect or gdk-window-invalidate-region. To cause the redraw to be done immediately, follow that call with a call to gdk-window-process-updates.

widget
a <gtk-widget>
event
a expose <gdk-event>
ret
return from the event signal emission (‘#t’ if the event was handled)
— Function: gtk-widget-style-get-property (self <gtk-widget>) (property_name mchars) (value <gvalue>)
— Method: style-get-property

Gets the value of a style property of widget.

widget
a <gtk-widget>
property-name
the name of a style property
value
location to return the property value
— Function: gtk-widget-get-accessible (self <gtk-widget>) ⇒  (ret <atk-object>)
— Method: get-accessible

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

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

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

widget
a <gtk-widget>
ret
the <atk-object> associated with widget
— Function: gtk-widget-child-focus (self <gtk-widget>) (direction <gtk-direction-type>) ⇒  (ret bool)
— Method: child-focus

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

gtk-widget-child-focus is called by containers as the user moves around the window using keyboard shortcuts. direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). gtk-widget-child-focus invokes the "focus" signal on <gtk-widget>; widgets override the default handler for this signal in order to implement appropriate focus behavior.

The "focus" default handler for a widget should return ‘#t’ if moving in direction left the focus on a focusable location inside that widget, and ‘#f’ if moving in direction moved the focus outside the widget. If returning ‘#t’, widgets normally call gtk-widget-grab-focus to place the focus accordingly; if returning ‘#f’, they don't modify the current focus location.

This function replaces gtk-container-focus from GTK+ 1.2. It was necessary to check that the child was visible, sensitive, and focusable before calling gtk-container-focus. gtk-widget-child-focus returns ‘#f’ if the widget is not currently in a focusable state, so there's no need for those checks.

widget
a <gtk-widget>
direction
direction of focus movement
ret
#t’ if focus ended up inside widget
— Function: gtk-widget-child-notify (self <gtk-widget>) (child_property mchars)
— Method: child-notify

Emits a "child-notify" signal for the child propertychild-property on widget.

This is the analogue of g-object-notify for child properties.

widget
a <gtk-widget>
child-property
the name of a child property installed on the class of widget's parent.
— Function: gtk-widget-freeze-child-notify (self <gtk-widget>)
— Method: freeze-child-notify

Stops emission of "child-notify" signals on widget. The signals are queued until gtk-widget-thaw-child-notify is called on widget.

This is the analogue of g-object-freeze-notify for child properties.

widget
a <gtk-widget>
— Function: gtk-widget-get-child-visible (self <gtk-widget>) ⇒  (ret bool)
— Method: get-child-visible

Gets the value set with gtk-widget-set-child-visible. If you feel a need to use this function, your code probably needs reorganization.

This function is only useful for container implementations and never should be called by an application.

widget
a <gtk-widget>
ret
#t’ if the widget is mapped with the parent.
— Function: gtk-widget-get-parent (self <gtk-widget>) ⇒  (ret <gtk-widget>)
— Method: get-parent

Returns the parent container of widget.

widget
a <gtk-widget>
ret
the parent container of widget, or ‘#f
— Function: gtk-widget-get-settings (self <gtk-widget>) ⇒  (ret <gtk-settings>)
— Method: get-settings

Gets the settings object holding the settings (global property settings, RC file information, etc) used for this widget.

Note that this function can only be called when the <gtk-widget> is attached to a toplevel, since the settings object is specific to a particular <gdk-screen>.

widget
a <gtk-widget>
ret
the relevant <gtk-settings> object
— Function: gtk-widget-get-clipboard (self <gtk-widget>) (selection <gdk-atom>) ⇒  (ret <gtk-clipboard>)
— Method: get-clipboard

Returns the clipboard object for the given selection to be used with widget. widget must have a <gdk-display> associated with it, so must be attached to a toplevel window.

widget
a <gtk-widget>
selection
a <gdk-atom> which identifies the clipboard to use. ‘GDK_SELECTION_CLIPBOARD’ gives the default clipboard. Another common value is ‘GDK_SELECTION_PRIMARY’, which gives the primary X selection.
ret
the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent for all time.

Since 2.2

— Function: gtk-widget-get-display (self <gtk-widget>) ⇒  (ret <gdk-display>)
— Method: get-display

Get the <gdk-display> for the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a <gtk-window> at the top.

In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

widget
a <gtk-widget>
ret
the <gdk-display> for the toplevel for this widget.

Since 2.2

— Function: gtk-widget-get-root-window (self <gtk-widget>) ⇒  (ret <gdk-window>)
— Method: get-root-window

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

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

widget
a <gtk-widget>
ret
the <gdk-window> root window for the toplevel for this widget.

Since 2.2

— Function: gtk-widget-get-screen (self <gtk-widget>) ⇒  (ret <gdk-screen>)
— Method: get-screen

Get the <gdk-screen> from the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a <gtk-window> at the top.

In general, you should only create screen specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

widget
a <gtk-widget>
ret
the <gdk-screen> for the toplevel for this widget.

Since 2.2

— Function: gtk-widget-has-screen (self <gtk-widget>) ⇒  (ret bool)
— Method: has-screen

Checks whether there is a <gdk-screen> is associated with this widget. All toplevel widgets have an associated screen, and all widgets added into a heirarchy with a toplevel window at the top.

widget
a <gtk-widget>
ret
#t’ if there is a <gdk-screen> associcated with the widget.

Since 2.2

— Function: gtk-widget-get-size-request (self <gtk-widget>) ⇒  (width int) (height int)
— Method: get-size-request

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

widget
a <gtk-widget>
width
return location for width, or ‘#f
height
return location for height, or ‘#f
— Function: gtk-widget-set-child-visible (self <gtk-widget>) (is_visible bool)
— Method: set-child-visible

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

The child visibility can be set for widget before it is added to a container with gtk-widget-set-parent, to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of ‘#t’ when the widget is removed from a container.

Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself.

This function is only useful for container implementations and never should be called by an application.

widget
a <gtk-widget>
is-visible
if ‘#t’, widget should be mapped along with its parent.
— Function: gtk-widget-set-size-request (self <gtk-widget>) (width int) (height int)
— Method: set-size-request

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

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

Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hardcode a size that will always be correct.

The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested.

If the size request in a given direction is -1 (unset), then the "natural" size request of the widget will be used instead.

Widgets can't actually be allocated a size less than 1 by 1, but you can pass 0,0 to this function to mean "as small as possible."

widget
a <gtk-widget>
width
width widget should request, or -1 to unset
height
height widget should request, or -1 to unset
— Function: gtk-widget-thaw-child-notify (self <gtk-widget>)
— Method: thaw-child-notify

Reverts the effect of a previous call to gtk-widget-freeze-child-notify. This causes all queued "child-notify" signals on widget to be emitted.

widget
a <gtk-widget>
— Function: gtk-widget-set-no-show-all (self <gtk-widget>) (no_show_all bool)
— Method: set-no-show-all

Sets the "no_show_all" property, which determines whether calls to gtk-widget-show-all and gtk-widget-hide-all will affect this widget.

This is mostly for use in constructing widget hierarchies with externally controlled visibility, see <gtk-ui-manager>.

widget
a <gtk-widget>
no-show-all
the new value for the "no_show_all" property

Since 2.4

— Function: gtk-widget-get-no-show-all (self <gtk-widget>) ⇒  (ret bool)
— Method: get-no-show-all

Returns the current value of the "no_show_all" property, which determines whether calls to gtk-widget-show-all and gtk-widget-hide-all will affect this widget.

widget
a <gtk-widget>
ret
the current value of the "no_show_all" property.

Since 2.4

— Function: gtk-widget-list-mnemonic-labels (self <gtk-widget>) ⇒  (ret glist-of)
— Method: list-mnemonic-labels

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

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

widget
a <gtk-widget>
ret
the list of mnemonic labels; free this list with g-list-free when you are done with it.

Since 2.4

— Function: gtk-widget-add-mnemonic-label (self <gtk-widget>) (label <gtk-widget>)
— Method: add-mnemonic-label

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

widget
a <gtk-widget>
label
a <gtk-widget> that acts as a mnemonic label for widget.

Since 2.4

— Function: gtk-widget-remove-mnemonic-label (self <gtk-widget>) (label <gtk-widget>)
— Method: remove-mnemonic-label

Removes a widget from the list of mnemonic labels for this widget. (See gtk-widget-list-mnemonic-labels). The widget must have previously been added to the list with gtk-widget-add-mnemonic-label.

widget
a <gtk-widget>
label
a <gtk-widget> that was previously set as a mnemnic label for widget with gtk-widget-add-mnemonic-label.

Since 2.4

— Function: gtk-widget-get-action (self <gtk-widget>) ⇒  (ret <gtk-action>)
— Method: get-action

Returns the <gtk-action> that widget is a proxy for. See also gtk-action-get-proxies.

widget
a <gtk-widget>
ret
the action that a widget is a proxy for, or ‘#f’, if it is not attached to an action.

Since 2.10

— Function: gtk-widget-is-composited (self <gtk-widget>) ⇒  (ret bool)
— Method: is-composited

Whether widget can rely on having its alpha channel drawn correctly. On X11 this function returns whether a compositing manager is running for widget's screen

widget
a <gtk-widget>
ret
#t’ if the widget can rely on its alpha channel being drawn correctly.

Since 2.10

— Function: gtk-requisition-copy (self <gtk-requisition>) ⇒  (ret <gtk-requisition>)

Copies a <gtk-requisition>.

requisition
a <gtk-requisition>.
ret
a copy of requisition.