Memory-managed wrapper type.

Type class for types which can be safely cast to Widget, for instance with toWidget.

Cast to Widget, for types for which this is known to be safe. For general casts, use castTo.

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

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

Adds the device events in the bitfield events to the event mask for widget. See widgetSetDeviceEvents for details.

Since: 3.0

Adds the events in the bitfield events to the event mask for widget. See widgetSetEvents and the [input handling overview][event-masks] for details.

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

Since: 2.4

Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a Label), then you will have to call widgetQueueResize or widgetQueueDrawArea yourself.

frameClockGetFrameTime should generally be used for timing continuous animations and frameTimingsGetPredictedPresentationTime if you are trying to display isolated frames at particular times.

This is a more convenient alternative to connecting directly to the FrameClock::update signal of FrameClock, since you don't have to worry about when a FrameClock is assigned to a widget.

Since: 3.8

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

Since: 2.4

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

widgetChildFocus 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). widgetChildFocus emits the Widget::focus signal; widgets override the default handler for this signal in order to implement appropriate focus behavior.

The default focus handler for a widget should return True if moving in direction left the focus on a focusable location inside that widget, and False if moving in direction moved the focus outside the widget. If returning True, widgets normally call widgetGrabFocus to place the focus accordingly; if returning False, they don’t modify the current focus location.

Emits a Widget::childNotify signal for the [child property][child-properties] childProperty on widget.

This is the analogue of objectNotify for child properties.

Also see containerChildNotify.

Same as widgetPath, but always uses the name of a widget’s type, never uses a custom name set with widgetSetName.

Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at widgetGetHexpand or widgetGetVexpand.

This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded.

The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do.

Creates a new Context with the appropriate font map, font options, font description, and base direction for drawing text for this widget. See also widgetGetPangoContext.

Creates a new Layout with the appropriate font map, font description, and base direction for drawing text for this widget.

If you keep a Layout created in this way around, you need to re-create it when the widget Context is replaced. This can be tracked by using the Widget::screenChanged signal on the widget.

Destroys a widget.

When a widget is destroyed all references it holds on other objects will be released:

• if the widget is inside a container, it will be removed from its parent
• if the widget is a container, all its children will be destroyed, recursively
• if the widget is a top level, it will be removed from the list of top level widgets that GTK+ maintains internally

It's expected that all references held on the widget will also be released; you should connect to the Widget::destroy signal if you hold a reference to widget and you wish to remove it when this function is called. It is not necessary to do so if you are implementing a Container, as you'll be able to use the ContainerClass.remove() virtual function for that.

It's important to notice that widgetDestroy will only cause the widget to be finalized if no additional references, acquired using objectRef, are held on it. In case additional references are in place, the widget will be in an "inert" state after calling this function; widget will still point to valid memory, allowing you to release the references you hold, but you may not query the widget's own state.

You should typically call this function on top level widgets, and rarely on child widgets.

See also: containerRemove

This function sets *widgetPointer to Nothing if widgetPointer != Nothing. It’s intended to be used as a callback connected to the “destroy” signal of a widget. You connect widgetDestroyed as a signal handler, and pass the address of your widget variable as user data. Then when the widget is destroyed, the variable will be set to Nothing. Useful for example to avoid multiple copies of the same dialog.

Returns True if device has been shadowed by a GTK+ device grab on another widget, so it would stop sending events to widget. This may be used in the Widget::grabNotify signal to check for specific devices. See deviceGrabAdd.

Since: 3.0

This function is equivalent to widgetDragBeginWithCoordinates, passing -1, -1 as coordinates.

Initiates a drag on the source side. The function only needs to be used when the application is starting drags itself, and is not needed when widgetDragSourceSet is used.

The event is used to retrieve the timestamp that will be used internally to grab the pointer. If event is Nothing, then CURRENT_TIME will be used. However, you should try to pass a real event in all cases, since that can be used to get information about the drag.

Generally there are three cases when you want to start a drag by hand by calling this function:

1. During a Widget::buttonPressEvent handler, if you want to start a drag immediately when the user presses the mouse button. Pass the event that you have in your Widget::buttonPressEvent handler.
2. During a Widget::motionNotifyEvent handler, if you want to start a drag when the mouse moves past a certain threshold distance after a button-press. Pass the event that you have in your Widget::motionNotifyEvent handler.
3. During a timeout handler, if you want to start a drag after the mouse button is held down for some time. Try to save the last event that you got from the mouse, using eventCopy, and pass it to this function (remember to free the event with eventFree when you are done). If you really cannot pass a real event, pass Nothing instead.

Since: 3.10

Checks to see if a mouse drag starting at (startX, startY) and ending at (currentX, currentY) has passed the GTK+ drag threshold, and thus should trigger the beginning of a drag-and-drop operation.

Add the image targets supported by SelectionData to the target list of the drag destination. The targets are added with info = 0. If you need another value, use targetListAddImageTargets and widgetDragDestSetTargetList.

Since: 2.6

Add the text targets supported by SelectionData to the target list of the drag destination. The targets are added with info = 0. If you need another value, use targetListAddTextTargets and widgetDragDestSetTargetList.

Since: 2.6

Add the URI targets supported by SelectionData to the target list of the drag destination. The targets are added with info = 0. If you need another value, use targetListAddUriTargets and widgetDragDestSetTargetList.

Since: 2.6

Looks for a match between the supported targets of context and the destTargetList, returning the first matching target, otherwise returning GDK_NONE. destTargetList should usually be the return value from widgetDragDestGetTargetList, but some widgets may have different valid targets for different parts of the widget; in that case, they will have to implement a drag_motion handler that passes the correct target list to this function.

Returns the list of targets this widget can accept from drag-and-drop.

Returns whether the widget has been configured to always emit Widget::dragMotion signals.

Since: 2.10

Sets a widget as a potential drop destination, and adds default behaviors.

The default behaviors listed in flags have an effect similar to installing default handlers for the widget’s drag-and-drop signals (Widget::dragMotion, Widget::dragDrop, ...). They all exist for convenience. When passing GTK_DEST_DEFAULT_ALL for instance it is sufficient to connect to the widget’s Widget::dragDataReceived signal to get primitive, but consistent drag-and-drop support.

Things become more complicated when you try to preview the dragged data, as described in the documentation for Widget::dragMotion. The default behaviors described by flags make some assumptions, that can conflict with your own signal handlers. For instance GTK_DEST_DEFAULT_DROP causes invokations of dragStatus in the context of Widget::dragMotion, and invokations of dragFinish in Widget::dragDataReceived. Especially the later is dramatic, when your own Widget::dragMotion handler calls widgetDragGetData to inspect the dragged data.

There’s no way to set a default action here, you can use the Widget::dragMotion callback for that. Here’s an example which selects the action to use depending on whether the control key is pressed or not:

C code

static void
drag_motion (GtkWidget *widget,
             GdkDragContext *context,
             gint x,
             gint y,
             guint time)
{
  GdkModifierType mask;

  gdk_window_get_pointer (gtk_widget_get_window (widget),
                          NULL, NULL, &mask);
  if (mask & GDK_CONTROL_MASK)
    gdk_drag_status (context, GDK_ACTION_COPY, time);
  else
    gdk_drag_status (context, GDK_ACTION_MOVE, time);
}

Sets this widget as a proxy for drops to another window.

Sets the target types that this widget can accept from drag-and-drop. The widget must first be made into a drag destination with widgetDragDestSet.

Tells the widget to emit Widget::dragMotion and Widget::dragLeave events regardless of the targets and the DestDefaultsMotion flag.

This may be used when a widget wants to do generic actions regardless of the targets that the source offers.

Since: 2.10

Clears information about a drop destination set with widgetDragDestSet. The widget will no longer receive notification of drags.

Gets the data associated with a drag. When the data is received or the retrieval fails, GTK+ will emit a Widget::dragDataReceived signal. Failure of the retrieval is indicated by the length field of the selectionData signal parameter being negative. However, when widgetDragGetData is called implicitely because the DestDefaultsDrop was set, then the widget will not receive notification of failed drops.

Highlights a widget as a currently hovered drop target. To end the highlight, call widgetDragUnhighlight. GTK+ calls this automatically if DestDefaultsHighlight is set.

Add the writable image targets supported by SelectionData to the target list of the drag source. The targets are added with info = 0. If you need another value, use targetListAddImageTargets and widgetDragSourceSetTargetList.

Since: 2.6

Add the text targets supported by SelectionData to the target list of the drag source. The targets are added with info = 0. If you need another value, use targetListAddTextTargets and widgetDragSourceSetTargetList.

Since: 2.6

Add the URI targets supported by SelectionData to the target list of the drag source. The targets are added with info = 0. If you need another value, use targetListAddUriTargets and widgetDragSourceSetTargetList.

Since: 2.6

Gets the list of targets this widget can provide for drag-and-drop.

Since: 2.4

Sets up a widget so that GTK+ will start a drag operation when the user clicks and drags on the widget. The widget must have a window.

Sets the icon that will be used for drags from a particular source to icon. See the docs for IconTheme for more details.

Since: 3.2

Sets the icon that will be used for drags from a particular source to a themed icon. See the docs for IconTheme for more details.

Since: 2.8

Sets the icon that will be used for drags from a particular widget from a Pixbuf. GTK+ retains a reference for pixbuf and will release it when it is no longer needed.

Sets the icon that will be used for drags from a particular source to a stock icon.

Changes the target types that this widget offers for drag-and-drop. The widget must first be made into a drag source with widgetDragSourceSet.

Since: 2.4

Undoes the effects of widgetDragSourceSet.

Removes a highlight set by widgetDragHighlight from a widget.

Draws widget to cr. The top left corner of the widget will be drawn to the currently set origin point of cr.

You should pass a cairo context as cr argument that is in an original state. Otherwise the resulting drawing is undefined. For example changing the operator using cairo_set_operator() or the line width using cairo_set_line_width() might have unwanted side effects. You may however change the context’s transform matrix - like with cairo_scale(), cairo_translate() or cairo_set_matrix() and clip region with cairo_clip() prior to calling this function. Also, it is fine to modify the context with cairo_save() and cairo_push_group() prior to calling this function.

Note that special-purpose widgets may contain special code for rendering to the screen and might appear differently on screen and when rendered using widgetDraw.

Since: 3.0

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.

Notifies the user about an input-related error on this widget. If the Settings:gtkErrorBell setting is True, it calls windowBeep, otherwise it does nothing.

Note that the effect of windowBeep can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.

Since: 2.12

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

Stops emission of Widget::childNotify signals on widget. The signals are queued until widgetThawChildNotify is called on widget.

This is the analogue of objectFreezeNotify for child properties.

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

If accessibility support is not available, this Object instance may be a no-op. Likewise, if no class-specific Object implementation is available for the widget instance in question, it will inherit an Object implementation from the first ancestor class for which such an implementation is defined.

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

Retrieves the ActionGroup that was registered using prefix. The resulting ActionGroup may have been registered to widget or any Widget in its ancestry.

If no action group was found matching prefix, then Nothing is returned.

Since: 3.16

Returns the baseline that has currently been allocated to widget. This function is intended to be used when implementing handlers for the Widget::draw function, and when allocating child widgets in Widget::size_allocate.

Since: 3.10

Returns the height that has currently been allocated to widget. This function is intended to be used when implementing handlers for the Widget::draw function.

Retrieves the widget’s allocated size.

This function returns the last values passed to widgetSizeAllocateWithBaseline. The value differs from the size returned in widgetGetAllocation in that functions like widgetSetHalign can adjust the allocation, but not the value returned by this function.

If a widget is not visible, its allocated size is 0.

Since: 3.20

Returns the width that has currently been allocated to widget. This function is intended to be used when implementing handlers for the Widget::draw function.

Retrieves the widget’s allocation.

Note, when implementing a Container: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent container typically calls widgetSizeAllocate with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. widgetGetAllocation returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the widgetSizeAllocate allocation, however. So a Container is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned. There is no way to get the original allocation assigned by widgetSizeAllocate, since it isn’t stored; if a container implementation needs that information it will have to track it itself.

Since: 2.18

Gets the first ancestor of widget with type widgetType. For example, gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first 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 Window in the docs for widgetGetToplevel.

Note that unlike widgetIsAncestor, widgetGetAncestor considers widget to be an ancestor of itself.

Determines whether the application intends to draw on the widget in an Widget::draw handler.

See widgetSetAppPaintable

Since: 2.18

Determines whether widget can be a default widget. See widgetSetCanDefault.

Since: 2.18

Determines whether widget can own the input focus. See widgetSetCanFocus.

Since: 2.18

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 widgetSetSizeRequest), in which case it returns that geometry instead of the widget's requisition.

This function differs from widgetSizeRequest in that it retrieves the last size request value from widget->requisition, while widgetSizeRequest 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, widgetSizeRequest has been called since the last time a resize was queued. In general, only container implementations have this information; applications should use widgetSizeRequest.

Gets the value set with widgetSetChildVisible. 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.

Retrieves the widget’s clip area.

The clip area is the area in which all of widget's drawing will happen. Other toolkits call it the bounding box.

Historically, in GTK+ the clip area has been equal to the allocation retrieved via widgetGetAllocation.

Since: 3.14

Returns the clipboard object for the given selection to be used with widget. widget must have a Display associated with it, so must be attached to a toplevel window.

Since: 2.2

Obtains the composite name of a widget.

Obtains the current default reading direction. See widgetSetDefaultDirection.