Base class for all widgets
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.
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
<gtk-widget>)The parent-set signal is emitted when a new parent has been set on a widget.
<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.
<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-basealso cause this signal to be emitted.
<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-addwhen the topmost grab widget in the grab stack of its window group is not its ancestor.
<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.
<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-deleteto this signal will cause the window to be hidden instead, so that it can later be shown again without reconstructing it.
<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.
<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
<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.
<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.
<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.
<gdk-drag-context>) (arg1 <gtk-drag-result>) ⇒ <gboolean>undocumented
<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 callinggdk-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 callinggtk-drag-get-dataand defer thegdk-drag-statuscall 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 */ } }
<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 thatgtk-drag-finishis called to let the source know that the drop is done. The call togtk-drag-finishcan be done either directly or in a ::drag-data-received handler which gets triggered by callinggtk-drop-get-datato receive the data for one or more of the supported targets.
<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-setandgtk-selection-data-set-text.
<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-statusand 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 callgtk-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); }
<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
<gint>) (arg1 <gint>) (arg2 <gboolean>) (arg3 <gtk-tooltip>) ⇒ <gboolean>undocumented
<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.
<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.
<gtk-widget>)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 withg-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>
<gtk-widget>)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>
<gtk-widget>)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-allon 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>
<gtk-widget>)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>
<gtk-widget>)Reverses the effects of
gtk-widget-show, causing the widget to be hidden (invisible to the user).
- widget
- a
<gtk-widget>
<gtk-widget>)Recursively shows a widget, and any child widgets (if the widget is a container).
- widget
- a
<gtk-widget>
<gtk-widget>)Recursively hides a widget and any child widgets.
- widget
- a
<gtk-widget>
<gtk-widget>)This function is only for use in widget implementations. Causes a widget to be mapped if it isn't already.
- widget
- a
<gtk-widget>
<gtk-widget>)This function is only for use in widget implementations. Causes a widget to be unmapped if it's currently mapped.
- widget
- a
<gtk-widget>
<gtk-widget>)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-realizerealizes 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-afterto the "realize" signal.
- widget
- a
<gtk-widget>
<gtk-widget>)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>
<gtk-widget>)Equivalent to calling
gtk-widget-queue-draw-areafor the entire area of a widget.
- widget
- a
<gtk-widget>
<gtk-widget>)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>
<gtk-widget>)This function works like
gtk-widget-queue-resize, except that the widget is not invalidated.
- widget
- a
<gtk-widget>Since 2.4
<gtk-widget>) (requisition <gtk-requisition>)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 withgtk-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
<gtk-widget>) (requisition <gtk-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-requestin that it retrieves the last size request value from widget->requisition, whilegtk-widget-size-requestactually 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-requesthas been called since the last time a resize was queued. In general, only container implementations have this information; applications should usegtk-widget-size-request.
- widget
- a
<gtk-widget>- requisition
- a
<gtk-requisition>to be filled in
<gtk-widget>) (allocation <gdk-rectangle>)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
<gtk-widget>) (accel_signal mchars) (accel_group <gtk-accel-group>) (accel_key unsigned-int) (accel_mods <gdk-modifier-type>) (accel_flags <gtk-accel-flags>)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, usegtk-accel-map-add-entryandgtk-widget-set-accel-pathorgtk-menu-item-set-accel-pathinstead.
- 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’
<gtk-widget>) (accel_group <gtk-accel-group>) (accel_key unsigned-int) (accel_mods <gdk-modifier-type>) ⇒ (ret bool)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
<gtk-widget>) (accel_path mchars) (accel_group <gtk-accel-group>)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. (Seegtk-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 itemsgtk-menu-item-set-accel-pathprovides a somewhat more convenient interface.
- widget
- a
<gtk-widget>- accel-path
- path used to look up the accelerator
- accel-group
- a
<gtk-accel-group>.
<gtk-widget>) ⇒ (ret glist-of)Lists the closures used by widget for accelerator group connections with
gtk-accel-group-connect-by-pathorgtk-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 withgtk-accel-group-from-accel-closure.
- widget
- widget to list accelerator closures for
- ret
- a newly allocated
<g-list>of closures
<gtk-widget>) (signal_id unsigned-int) ⇒ (ret bool)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
<gtk-widget>) (event <gdk-event>) ⇒ (ret bool)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-eventso the event will behave as if it were in the event queue. Don't synthesize expose events; instead, usegdk-window-invalidate-rectto 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)
<gtk-widget>) ⇒ (ret bool)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
<gtk-widget>) (new_parent <gtk-widget>)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
<gtk-widget>) ⇒ (ret bool)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.
<gtk-widget>)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>
<gtk-widget>)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-activateshould affect them.
- widget
- a
<gtk-widget>
<gtk-widget>) (name mchars)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
<gtk-widget>) ⇒ (ret mchars)Retrieves the name of a widget. See
gtk-widget-set-namefor 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
<gtk-widget>) (state <gtk-state-type>)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
<gtk-widget>) (sensitive bool)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
<gtk-widget>) (parent <gtk-widget>)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 isgtk-widget-unparent.
- widget
- a
<gtk-widget>- parent
- parent container
<gtk-widget>) (parent_window <gdk-window>)Sets a non default parent window for widget.
- widget
- a
<gtk-widget>.- parent-window
- the new parent window.
<gtk-widget>) ⇒ (ret <gdk-window>)Gets widget's parent window.
- widget
- a
<gtk-widget>.- ret
- the parent window of widget.
<gtk-widget>) (events <gdk-event-mask>)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. Considergtk-widget-add-eventsfor 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
<gtk-widget>) (events <gdk-event-mask>)Adds the events in the bitfield events to the event mask for widget. See
gtk-widget-set-eventsfor details.
- widget
- a
<gtk-widget>- events
- an event mask, see
<gdk-event-mask>
<gtk-widget>) (mode <gdk-extension-mode>)Sets the extension events mask to mode. See
<gdk-extension-mode>andgdk-input-set-extension-events.
- widget
- a
<gtk-widget>- mode
- bitfield of extension events to receive
<gtk-widget>) ⇒ (ret <gdk-extension-mode>)Retrieves the extension events the widget will receive; see
gdk-input-set-extension-events.
- widget
- a
<gtk-widget>- ret
- extension events for widget
<gtk-widget>) ⇒ (ret <gtk-widget>)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>, usegtk-widget-get-topleveland 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.
<gtk-widget>) (widget_type <gtype>) ⇒ (ret <gtk-widget>)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 forgtk-widget-get-toplevel.Note that unlike
gtk-widget-is-ancestor,gtk-widget-get-ancestorconsiders widget to be an ancestor of itself.
- widget
- a
<gtk-widget>- widget-type
- ancestor type
- ret
- the ancestor widget, or ‘
#f’ if not found
<gtk-widget>) ⇒ (ret <gdk-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
<gtk-widget>) (colormap <gdk-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
initfunction (i.e. from the constructor for the widget).
- widget
- a
<gtk-widget>- colormap
- a colormap
<gtk-widget>) ⇒ (ret <gdk-visual>)Gets the visual that will be used to render widget.
- widget
- a
<gtk-widget>- ret
- the visual for widget
<gtk-widget>) ⇒ (ret int)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
<gtk-widget>) ⇒ (x int) (y int)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’
<gtk-widget>) (ancestor <gtk-widget>) ⇒ (ret bool)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.
<gtk-widget>) (dest_widget <gtk-widget>) (src_x int) (src_y int) ⇒ (ret bool) (dest_x int) (dest_y int)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’.
<gtk-widget>) ⇒ (ret bool)Utility function; intended to be connected to the "delete_event" signal on a
<gtk-window>. The function callsgtk-widget-hideon 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’
<gtk-widget>) (style <gtk-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, usegtk-widget-modify-style.
- widget
- a
<gtk-widget>- style
- a
<gtk-style>, or ‘#f’ to remove the effect of a previousgtk-widget-set-styleand go back to the default style
<gtk-widget>)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>
<gtk-widget>) ⇒ (ret <gtk-style>)Simply an accessor function that returns widget->style.
- widget
- a
<gtk-widget>- ret
- the widget's
<gtk-style>
<gtk-widget>)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>.
<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>
<gdk-colormap>)Sets the default colormap to use when creating widgets.
gtk-widget-push-colormapis a better function to use if you only want to affect a few widgets, rather than all widgets.
- colormap
- a
<gdk-colormap>
<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.
<gdk-colormap>)Obtains the default colormap used to create widgets.
- ret
- default widget colormap
<gdk-visual>)Obtains the visual of the default colormap. Not really useful; used to be useful before
gdk-colormap-get-visualexisted.
- ret
- visual of the default colormap
<gtk-widget>) (dir <gtk-text-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-directionwill be used.
- widget
- a
<gtk-widget>- dir
- the new direction
<gtk-widget>) ⇒ (ret <gtk-text-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.
<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’.
<gtk-text-direction>)Obtains the current default reading direction. See
gtk-widget-set-default-direction.
- ret
- the current default direction.
<gtk-widget>) (shape_mask <gdk-drawable>) (offset_x int) (offset_y int)Sets a shape for this widget's GDK window. This allows for transparent windows etc., see
gdk-window-shape-combine-maskfor 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.
<gtk-widget>) (shape_mask <gdk-drawable>) (offset_x int) (offset_y int)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-maskfor 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
<gtk-widget>) ⇒ (path_length unsigned-int) (path mchars) (path_reversed mchars)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 withgtk-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’
<gtk-widget>) ⇒ (path_length unsigned-int) (path mchars) (path_reversed mchars)Same as
gtk-widget-path, but always uses the name of a widget's type, never uses a custom name set withgtk-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’
<gtk-widget>) ⇒ (ret mchars)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.
<gtk-widget>) (style <gtk-rc-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-styleor with such functions asgtk-widget-modify-fg. If you wish to retain previous values, you must first callgtk-widget-get-modifier-style, make your modifications to the returned style, then callgtk-widget-modify-stylewith that style. On the other hand, if you first callgtk-widget-modify-style, subsequent calls to such functionsgtk-widget-modify-fgwill have a cumulative effect with the initial modifications.
- widget
- a
<gtk-widget>- style
- the
<gtk-rc-style>holding the style modifications
<gtk-widget>) ⇒ (ret <gtk-rc-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 callgtk-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-stylewill normally end up destroying it, becausegtk-widget-modify-stylecopies 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.
<gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)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 ofgtk-widget-modify-fg.
<gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)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 ofgtk-widget-modify-bg.
<gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)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 alsogtk-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 ofgtk-widget-modify-text.
<gtk-widget>) (state <gtk-state-type>) (color <gdk-color>)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 alsogtk-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 ofgtk-widget-modify-base.
<gtk-widget>) (font_desc <pango-font-description>)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 togtk-widget-modify-font.
<gtk-widget>) ⇒ (ret <pango-context>)Creates a new
<pango-context>with the appropriate font map, font description, and base direction for drawing text for this widget. See alsogtk-widget-get-pango-context.
- widget
- a
<gtk-widget>- ret
- the new
<pango-context>
<gtk-widget>) ⇒ (ret <pango-context>)Gets a
<pango-context>with the appropriate font map, font description, and base direction for this widget. Unlike the context returned bygtk-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 callingpango-layout-context-changedon 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.
<gtk-widget>) (text mchars) ⇒ (ret <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 callpango-layout-context-changedin 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>
<gtk-widget>) (stock_id mchars) (size <gtk-icon-size>) (detail mchars) ⇒ (ret <gdk-pixbuf>)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 withg-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
Cancels the effect of a previous call to
gtk-widget-push-composite-child.
Makes all newly-created widgets as composite children until the corresponding
gtk-widget-pop-composite-childcall.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-foreachvs.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);
<gtk-widget>) (x int) (y int) (width int) (height int)Invalidates the rectangular area of widget defined by x, y, width and height by calling
gdk-window-invalidate-recton 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-rectdirectly, to schedule a redraw of a<gtk-drawing-area>or some portion thereof.Frequently you can just call
gdk-window-invalidate-rectorgdk-window-invalidate-regioninstead 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
<gtk-widget>)Recursively resets the shape on this widget and its descendants.
- widget
- a
<gtk-widget>.
<gtk-widget>) (app_paintable bool)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
<gtk-widget>) (double_buffered bool)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-regionandgdk-window-end-paintare called automatically around expose events sent to the widget.gdk-window-begin-paintdiverts all drawing to a widget's window to an offscreen buffer, andgdk-window-end-paintdraws 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
<gtk-widget>) (redraw_on_allocate bool)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.
<gtk-widget>) (name mchars)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.
<gtk-widget>) (hadjustment <gtk-adjustment>) (vadjustment <gtk-adjustment>) ⇒ (ret bool)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
<gtk-widget>) (group_cycling bool) ⇒ (ret bool)
- widget
- group-cycling
- ret
<gtk-widget>) (region <gdk-region>) ⇒ (ret <gdk-region>)Computes the intersection of a widget's area and region, returning the intersection. The result may be empty, use
gdk-region-emptyto 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.
<gtk-widget>) (event <gdk-event>) ⇒ (ret int)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-rectorgdk-window-invalidate-region. To cause the redraw to be done immediately, follow that call with a call togdk-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)
<gtk-widget>) (property_name mchars) (value <gvalue>)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
<gtk-widget>) ⇒ (ret <atk-object>)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
<gtk-widget>) (direction <gtk-direction-type>) ⇒ (ret bool)This function is used by custom widget implementations; if you're writing an app, you'd use
gtk-widget-grab-focusto move the focus to a particular widget, andgtk-container-set-focus-chainto change the focus tab order. So you may want to investigate those functions instead.
gtk-widget-child-focusis 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-focusinvokes 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 callgtk-widget-grab-focusto place the focus accordingly; if returning ‘#f’, they don't modify the current focus location.This function replaces
gtk-container-focusfrom GTK+ 1.2. It was necessary to check that the child was visible, sensitive, and focusable before callinggtk-container-focus.gtk-widget-child-focusreturns ‘#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
<gtk-widget>) (child_property mchars)Emits a "child-notify" signal for the child propertychild-property on widget.
This is the analogue of
g-object-notifyfor child properties.
- widget
- a
<gtk-widget>- child-property
- the name of a child property installed on the class of widget's parent.
<gtk-widget>)Stops emission of "child-notify" signals on widget. The signals are queued until
gtk-widget-thaw-child-notifyis called on widget.This is the analogue of
g-object-freeze-notifyfor child properties.
- widget
- a
<gtk-widget>
<gtk-widget>) ⇒ (ret bool)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.
<gtk-widget>) ⇒ (ret <gtk-widget>)Returns the parent container of widget.
- widget
- a
<gtk-widget>- ret
- the parent container of widget, or ‘
#f’
<gtk-widget>) ⇒ (ret <gtk-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
<gtk-widget>) (selection <gdk-atom>) ⇒ (ret <gtk-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
<gtk-widget>) ⇒ (ret <gdk-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
<gtk-widget>) ⇒ (ret <gdk-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
<gtk-widget>) ⇒ (ret <gdk-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
<gtk-widget>) ⇒ (ret bool)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
<gtk-widget>) ⇒ (width int) (height int)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. Seegtk-widget-set-size-request. To get the size a widget will actually use, callgtk-widget-size-requestinstead of this function.
- widget
- a
<gtk-widget>- width
- return location for width, or ‘
#f’- height
- return location for height, or ‘
#f’
<gtk-widget>) (is_visible bool)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.
<gtk-widget>) (width int) (height int)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-sizeis 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-hintscan 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
<gtk-widget>)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>
<gtk-widget>) (no_show_all bool)Sets the "no_show_all" property, which determines whether calls to
gtk-widget-show-allandgtk-widget-hide-allwill 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
<gtk-widget>) ⇒ (ret bool)Returns the current value of the "no_show_all" property, which determines whether calls to
gtk-widget-show-allandgtk-widget-hide-allwill affect this widget.
- widget
- a
<gtk-widget>- ret
- the current value of the "no_show_all" property.
Since 2.4
<gtk-widget>) ⇒ (ret glist-of)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-freewhen you are done with it.Since 2.4
<gtk-widget>) (label <gtk-widget>)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
<gtk-widget>) (label <gtk-widget>)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 withgtk-widget-add-mnemonic-label.
- widget
- a
<gtk-widget>- label
- a
<gtk-widget>that was previously set as a mnemnic label for widget withgtk-widget-add-mnemonic-label.Since 2.4
<gtk-widget>) ⇒ (ret <gtk-action>)Returns the
<gtk-action>that widget is a proxy for. See alsogtk-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
<gtk-widget>) ⇒ (ret bool)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