Top |
Functions
Properties
gboolean | can-focus | Read / Write |
gboolean | can-target | Read / Write |
GStrv | css-classes | Read / Write |
char * | css-name | Read / Write / Construct Only |
GdkCursor * | cursor | Read / Write |
gboolean | focus-on-click | Read / Write |
gboolean | focusable | Read / Write |
GtkAlign | halign | Read / Write |
gboolean | has-default | Read |
gboolean | has-focus | Read |
gboolean | has-tooltip | Read / Write |
int | height-request | Read / Write |
gboolean | hexpand | Read / Write |
gboolean | hexpand-set | Read / Write |
GtkLayoutManager * | layout-manager | Read / Write |
int | margin-bottom | Read / Write |
int | margin-end | Read / Write |
int | margin-start | Read / Write |
int | margin-top | Read / Write |
char * | name | Read / Write |
double | opacity | Read / Write |
GtkOverflow | overflow | Read / Write |
GtkWidget * | parent | Read |
gboolean | receives-default | Read / Write |
GtkRoot * | root | Read |
int | scale-factor | Read |
gboolean | sensitive | Read / Write |
char * | tooltip-markup | Read / Write |
char * | tooltip-text | Read / Write |
GtkAlign | valign | Read / Write |
gboolean | vexpand | Read / Write |
gboolean | vexpand-set | Read / Write |
gboolean | visible | Read / Write |
int | width-request | Read / Write |
Signals
void | destroy | No Hooks |
void | direction-changed | Run First |
void | hide | Run First |
gboolean | keynav-failed | Run Last |
void | map | Run First |
gboolean | mnemonic-activate | Run Last |
void | move-focus | Action |
gboolean | query-tooltip | Run Last |
void | realize | Run First |
void | show | Run First |
void | state-flags-changed | Run First |
void | unmap | Run First |
void | unrealize | Run Last |
Types and Values
GtkWidget | |
struct | GtkWidgetClass |
GtkRequisition | |
typedef | GtkAllocation |
enum | GtkTextDirection |
enum | GtkPickFlags |
enum | GtkOverflow |
enum | GtkSizeRequestMode |
struct | GtkRequestedSize |
enum | GtkAlign |
Object Hierarchy
GObject ╰── GInitiallyUnowned ╰── GtkWidget ├── GtkWindow ├── GtkActionBar ├── GtkAppChooserButton ├── GtkAppChooserWidget ├── GtkAspectFrame ├── GtkBox ├── GtkButton ├── GtkCalendar ├── GtkCellView ├── GtkCenterBox ├── GtkCheckButton ├── GtkColorButton ├── GtkColorChooserWidget ├── GtkColumnView ├── GtkComboBox ├── GtkDragIcon ├── GtkDrawingArea ├── GtkDropDown ├── GtkEditableLabel ├── GtkPopover ├── GtkEntry ├── GtkExpander ├── GtkFileChooserWidget ├── GtkFixed ├── GtkFlowBox ├── GtkFlowBoxChild ├── GtkFontButton ├── GtkFontChooserWidget ├── GtkFrame ├── GtkGLArea ├── GtkGrid ├── GtkListBase ├── GtkHeaderBar ├── GtkIconView ├── GtkImage ├── GtkInfoBar ├── GtkLabel ├── GtkListBox ├── GtkListBoxRow ├── GtkMediaControls ├── GtkMenuButton ├── GtkNotebook ├── GtkOverlay ├── GtkPaned ├── GtkPasswordEntry ├── GtkPicture ├── GtkPopoverMenuBar ├── GtkProgressBar ├── GtkRange ├── GtkRevealer ├── GtkScaleButton ├── GtkScrollbar ├── GtkScrolledWindow ├── GtkSearchBar ├── GtkSearchEntry ├── GtkSeparator ├── GtkShortcutLabel ├── GtkShortcutsShortcut ├── GtkSpinButton ├── GtkSpinner ├── GtkStack ├── GtkStackSidebar ├── GtkStackSwitcher ├── GtkStatusbar ├── GtkSwitch ├── GtkLevelBar ├── GtkText ├── GtkTextView ├── GtkTreeExpander ├── GtkTreeView ├── GtkVideo ├── GtkViewport ├── GtkWindowControls ╰── GtkWindowHandle
Known Derived Interfaces
GtkWidget is required by GtkActionable, GtkAppChooser, GtkCellEditable, GtkEditable, GtkNative and GtkRoot.
Description
GtkWidget is the base class all widgets in GTK derive from. It manages the widget lifecycle, states and style.
Height-for-width Geometry Management
GTK uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height.
Height-for-width geometry management is implemented in GTK by way of two virtual methods:
There are some important things to keep in mind when implementing height-for-width and when using it in widget implementations.
If you implement a direct GtkWidget subclass that supports
height-for-width or width-for-height geometry management for
itself or its child widgets, the GtkWidgetClass.get_request_mode()
virtual function must be implemented as well and return the widget's
preferred request mode. The default implementation of this virtual function
returns GTK_SIZE_REQUEST_CONSTANT_SIZE
, which means that the widget will
only ever get -1 passed as the for_size value to its GtkWidgetClass.measure()
implementation.
The geometry management system will query a widget hierarchy in only one orientation at a time. When widgets are initially queried for their minimum sizes it is generally done in two initial passes in the GtkSizeRequestMode chosen by the toplevel.
For example, when queried in the normal
GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
mode:
First, the default minimum and natural width for each widget
in the interface will be computed using gtk_widget_measure()
with an
orientation of GTK_ORIENTATION_HORIZONTAL
and a for_size of -1.
Because the preferred widths for each widget depend on the preferred
widths of their children, this information propagates up the hierarchy,
and finally a minimum and natural width is determined for the entire
toplevel. Next, the toplevel will use the minimum width to query for the
minimum height contextual to that width using gtk_widget_measure()
with an
orientation of GTK_ORIENTATION_VERTICAL
and a for_size of the just computed
width. This will also be a highly recursive operation. The minimum height
for the minimum width is normally used to set the minimum size constraint
on the toplevel.
After the toplevel window has initially requested its size in both
dimensions it can go on to allocate itself a reasonable size (or a size
previously specified with gtk_window_set_default_size()
). During the
recursive allocation process it’s important to note that request cycles
will be recursively executed while widgets allocate their children.
Each widget, once allocated a size, will go on to first share the
space in one orientation among its children and then request each child's
height for its target allocated width or its width for allocated height,
depending. In this way a GtkWidget will typically be requested its size
a number of times before actually being allocated a size. The size a
widget is finally allocated can of course differ from the size it has
requested. For this reason, GtkWidget caches a small number of results
to avoid re-querying for the same sizes in one allocation cycle.
If a widget does move content around to intelligently use up the allocated size then it must support the request in both GtkSizeRequestModes even if the widget in question only trades sizes in a single orientation.
For instance, a GtkLabel that does height-for-width word wrapping
will not expect to have GtkWidgetClass.measure()
with an orientation of
GTK_ORIENTATION_VERTICAL
called because that call is specific to a
width-for-height request. In this
case the label must return the height required for its own minimum
possible width. By following this rule any widget that handles
height-for-width or width-for-height requests will always be allocated
at least enough space to fit its own content.
Here are some examples of how a GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
widget
generally deals with width-for-height requests:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
static void foo_widget_measure (GtkWidget *widget, GtkOrientation orientation, int for_size, int *minimum_size, int *natural_size, int *minimum_baseline, int *natural_baseline) { if (orientation == GTK_ORIENTATION_HORIZONTAL) { // Calculate minimum and natural width } else // VERTICAL { if (i_am_in_height_for_width_mode) { int min_width, dummy; // First, get the minimum width of our widget GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_HORIZONTAL, -1, &min_width, &dummy, &dummy, &dummy); // Now use the minimum width to retrieve the minimum and natural height to display // that width. GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_VERTICAL, min_width, minimum_size, natural_size, &dummy, &dummy); } else { // ... some widgets do both. } } } |
Often a widget needs to get its own request during size request or allocation. For example, when computing height it may need to also compute width. Or when deciding how to use an allocation, the widget may need to know its natural size. In these cases, the widget should be careful to call its virtual methods directly, like in the code example above.
It will not work to use the wrapper function gtk_widget_measure()
inside your own GtkWidgetClass.size-
implementation.
These return a request adjusted by GtkSizeGroup, the widget's align and expand flags
as well as its CSS style.
If a widget used the wrappers inside its virtual method implementations,
then the adjustments (such as widget margins) would be applied
twice. GTK therefore does not allow this and will warn if you try
to do it.allocate()
Of course if you are getting the size request for
another widget, such as a child widget, you must use gtk_widget_measure()
.
Otherwise, you would not properly consider widget margins,
GtkSizeGroup, and so forth.
GTK also supports baseline vertical alignment of widgets. This
means that widgets are positioned such that the typographical baseline of
widgets in the same row are aligned. This happens if a widget supports baselines,
has a vertical alignment of GTK_ALIGN_BASELINE
, and is inside a widget
that supports baselines and has a natural “row” that it aligns to the baseline,
or a baseline assigned to it by the grandparent.
Baseline alignment support for a widget is also done by the GtkWidgetClass.measure()
virtual function. It allows you to report both a minimum and natural size.
If a widget ends up baseline aligned it will be allocated all the space in the parent
as if it was GTK_ALIGN_FILL
, but the selected baseline can be found via gtk_widget_get_allocated_baseline()
.
If this has a value other than -1 you need to align the widget such that the baseline
appears at the position.
GtkWidget as GtkBuildable
The GtkWidget implementation of the GtkBuildable interface supports a custom elements to specify various aspects of widgets that are not directly expressed as properties.
If the parent widget uses a GtkLayoutManager, GtkWidget supports a
custom <layout>
element, used to define layout properties:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
<object class="MyGrid" id="grid1"> <child> <object class="GtkLabel" id="label1"> <property name="label">Description</property> <layout> <property name="column">0</property> <property name="row">0</property> <property name="row-span">1</property> <property name="column-span">1</property> </layout> </object> </child> <child> <object class="GtkEntry" id="description_entry"> <layout> <property name="column">1</property> <property name="row">0</property> <property name="row-span">1</property> <property name="column-span">1</property> </layout> </object> </child> </object> |
GtkWidget allows style information such as style classes to
be associated with widgets, using the custom <style>
element:
1 2 3 4 5 6 |
<object class="GtkButton" id="button1"> <style> <class name="my-special-button-class"/> <class name="dark-button"/> </style> </object> |
GtkWidget allows defining accessibility information, such as properties,
relations, and states, using the custom <accessibility>
element:
1 2 3 4 5 6 |
<object class="GtkButton" id="button1"> <accessibility> <property name="label">Download</property> <relation name="labelled-by">label1</relation> </accessibility> </object> |
Building composite widgets from template XML
GtkWidget exposes some facilities to automate the procedure of creating composite widgets using GtkBuilder interface description language.
To create composite widgets with GtkBuilder XML, one must associate
the interface description with the widget class at class initialization
time using gtk_widget_class_set_template()
.
The interface description semantics expected in composite template descriptions is slightly different from regular GtkBuilder XML.
Unlike regular interface descriptions, gtk_widget_class_set_template()
will
expect a <template>
tag as a direct child of the toplevel <interface>
tag. The <template>
tag must specify the “class” attribute which must be
the type name of the widget. Optionally, the “parent” attribute may be
specified to specify the direct parent type of the widget type, this is
ignored by the GtkBuilder but required for Glade to introspect what kind
of properties and internal children exist for a given type when the actual
type does not exist.
The XML which is contained inside the <template>
tag behaves as if it were
added to the <object>
tag defining widget
itself. You may set properties
on widget
by inserting <property>
tags into the <template>
tag, and also
add <child>
tags to add children and extend widget
in the normal way you
would with <object>
tags.
Additionally, <object>
tags can also be added before and after the initial
<template>
tag in the normal way, allowing one to define auxiliary objects
which might be referenced by other widgets declared as children of the
<template>
tag.
An example of a GtkBuilder Template Definition:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
<interface> <template class="FooWidget" parent="GtkBox"> <property name="orientation">horizontal</property> <property name="spacing">4</property> <child> <object class="GtkButton" id="hello_button"> <property name="label">Hello World</property> <signal name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/> </object> </child> <child> <object class="GtkButton" id="goodbye_button"> <property name="label">Goodbye World</property> </object> </child> </template> </interface> |
Typically, you'll place the template fragment into a file that is
bundled with your project, using GResource. In order to load the
template, you need to call gtk_widget_class_set_template_from_resource()
from the class initialization of your GtkWidget type:
1 2 3 4 5 6 7 8 |
static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); } |
You will also need to call gtk_widget_init_template()
from the instance
initialization function:
1 2 3 4 5 6 |
static void foo_widget_init (FooWidget *self) { // ... gtk_widget_init_template (GTK_WIDGET (self)); } |
You can access widgets defined in the template using the
gtk_widget_get_template_child()
function, but you will typically declare
a pointer in the instance private data structure of your type using the same
name as the widget in the template definition, and call
gtk_widget_class_bind_template_child_private()
with that name, e.g.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
typedef struct { GtkWidget *hello_button; GtkWidget *goodbye_button; } FooWidgetPrivate; G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX) static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, hello_button); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, goodbye_button); } static void foo_widget_init (FooWidget *widget) { } |
You can also use gtk_widget_class_bind_template_callback()
to connect a signal
callback defined in the template with a function visible in the scope of the
class, e.g.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
// the signal handler has the instance and user data swapped // because of the swapped="yes" attribute in the template XML static void hello_button_clicked (FooWidget *self, GtkButton *button) { g_print ("Hello, world!\n"); } static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked); } |
Functions
gtk_widget_in_destruction ()
gboolean
gtk_widget_in_destruction (GtkWidget *widget
);
Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work.
gtk_widget_unparent ()
void
gtk_widget_unparent (GtkWidget *widget
);
This function is only for use in widget implementations.
It should be called by parent widgets to dissociate widget
from the parent, typically in dispose.
gtk_widget_show ()
void
gtk_widget_show (GtkWidget *widget
);
Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen.
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.
gtk_widget_hide ()
void
gtk_widget_hide (GtkWidget *widget
);
Reverses the effects of gtk_widget_show()
, causing the widget to be
hidden (invisible to the user).
gtk_widget_map ()
void
gtk_widget_map (GtkWidget *widget
);
This function is only for use in widget implementations. Causes a widget to be mapped if it isn’t already.
gtk_widget_unmap ()
void
gtk_widget_unmap (GtkWidget *widget
);
This function is only for use in widget implementations. Causes a widget to be unmapped if it’s currently mapped.
gtk_widget_realize ()
void
gtk_widget_realize (GtkWidget *widget
);
Creates the GDK (windowing system) resources associated with a widget. 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 “realize”.
gtk_widget_unrealize ()
void
gtk_widget_unrealize (GtkWidget *widget
);
This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget).
gtk_widget_queue_draw ()
void
gtk_widget_queue_draw (GtkWidget *widget
);
Schedules this widget to be redrawn in paint phase of the
current or the next frame. This means widget
's GtkWidgetClass.snapshot()
implementation will be called.
gtk_widget_queue_resize ()
void
gtk_widget_queue_resize (GtkWidget *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 GtkLabel, GtkLabel queues a resize to ensure there’s enough space for the new text.
Note that you cannot call gtk_widget_queue_resize()
on a widget
from inside its implementation of the GtkWidgetClass::size_allocate
virtual method. Calls to gtk_widget_queue_resize()
from inside
GtkWidgetClass::size_allocate will be silently ignored.
gtk_widget_queue_allocate ()
void
gtk_widget_queue_allocate (GtkWidget *widget
);
This function is only for use in widget implementations.
Flags the widget for a rerun of the GtkWidgetClass::size_allocate
function. Use this function instead of gtk_widget_queue_resize()
when the widget
's size request didn't change but it wants to
reposition its contents.
An example user of this function is gtk_widget_set_halign()
.
gtk_widget_get_frame_clock ()
GdkFrameClock *
gtk_widget_get_frame_clock (GtkWidget *widget
);
Obtains the frame clock for a widget. The frame clock is a global
“ticker” that can be used to drive animations and repaints. The
most common reason to get the frame clock is to call
gdk_frame_clock_get_frame_time()
, in order to get a time to use for
animating. For example you might record the start of the animation
with an initial value from gdk_frame_clock_get_frame_time()
, and
then update the animation by calling
gdk_frame_clock_get_frame_time()
again during each repaint.
gdk_frame_clock_request_phase() will result in a new frame on the
clock, but won’t necessarily repaint any widgets. To repaint a
widget, you have to use gtk_widget_queue_draw()
which invalidates
the widget (thus scheduling it to receive a draw on the next
frame). gtk_widget_queue_draw()
will also end up requesting a frame
on the appropriate frame clock.
A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock.
Unrealized widgets do not have a frame clock.
gtk_widget_get_scale_factor ()
int
gtk_widget_get_scale_factor (GtkWidget *widget
);
Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2).
GtkTickCallback ()
gboolean (*GtkTickCallback) (GtkWidget *widget
,GdkFrameClock *frame_clock
,gpointer user_data
);
Callback type for adding a function to update animations. See gtk_widget_add_tick_callback()
.
Parameters
widget |
the widget |
|
frame_clock |
the frame clock for the widget (same as calling |
|
user_data |
user data passed to |
gtk_widget_add_tick_callback ()
guint gtk_widget_add_tick_callback (GtkWidget *widget
,GtkTickCallback callback
,gpointer user_data
,GDestroyNotify notify
);
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 GtkLabel),
then you will have to call gtk_widget_queue_resize()
or
gtk_widget_queue_draw()
yourself.
gdk_frame_clock_get_frame_time() should generally be used for timing
continuous animations and
gdk_frame_timings_get_predicted_presentation_time()
if you are
trying to display isolated frames at particular times.
This is a more convenient alternative to connecting directly to the “update” signal of GdkFrameClock, since you don't have to worry about when a GdkFrameClock is assigned to a widget.
Parameters
widget |
||
callback |
function to call for updating animations |
|
user_data |
data to pass to |
[closure] |
notify |
function to call to free |
Returns
an id for the connection of this callback. Remove the callback
by passing the id returned from this function to
gtk_widget_remove_tick_callback()
gtk_widget_remove_tick_callback ()
void gtk_widget_remove_tick_callback (GtkWidget *widget
,guint id
);
Removes a tick callback previously registered with
gtk_widget_add_tick_callback()
.
gtk_widget_size_allocate ()
void gtk_widget_size_allocate (GtkWidget *widget
,const GtkAllocation *allocation
,int baseline
);
This is a simple form of gtk_widget_allocate()
that takes the new position
of widget
as part of allocation
.
gtk_widget_allocate ()
void gtk_widget_allocate (GtkWidget *widget
,int width
,int height
,int baseline
,GskTransform *transform
);
This function is only used by GtkWidget subclasses, to assign a size, position and (optionally) baseline to their child widgets.
In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size.
For a version that does not take a transform, see gtk_widget_size_allocate()
gtk_widget_class_add_shortcut ()
void gtk_widget_class_add_shortcut (GtkWidgetClass *widget_class
,GtkShortcut *shortcut
);
Installs a shortcut in widget_class
. Every instance created for
widget_class
or its subclasses will inherit this shortcut and
trigger it.
Shortcuts added this way will be triggered in the GTK_PHASE_BUBBLE
phase, which means they may also trigger if child widgets have focus.
This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed.
Parameters
widget_class |
the class to add the shortcut to |
|
shortcut |
the GtkShortcut to add. |
[transfer none] |
gtk_widget_class_add_binding ()
void gtk_widget_class_add_binding (GtkWidgetClass *widget_class
,guint keyval
,GdkModifierType mods
,GtkShortcutFunc callback
,const char *format_string
,...
);
Creates a new shortcut for widget_class
that calls the given callback
with arguments read according to format_string
.
The arguments and format string must be provided in the same way as
with g_variant_new()
.
This function is a convenience wrapper around
gtk_widget_class_add_shortcut()
and must be called during class
initialization. It does not provide for user_data, if you need that,
you will have to use gtk_widget_class_add_shortcut()
with a custom
shortcut.
[skip]
Parameters
widget_class |
the class to add the binding to |
|
keyval |
key value of binding to install |
|
mods |
key modifier of binding to install |
|
callback |
the callback to call upon activation |
|
format_string |
GVariant format string for arguments or |
[nullable] |
... |
arguments, as given by format string. |
gtk_widget_class_add_binding_signal ()
void gtk_widget_class_add_binding_signal (GtkWidgetClass *widget_class
,guint keyval
,GdkModifierType mods
,const char *signal
,const char *format_string
,...
);
Creates a new shortcut for widget_class
that emits the given action
signal
with arguments read according to format_string
.
The arguments and format string must be provided in the same way as
with g_variant_new()
.
This function is a convenience wrapper around
gtk_widget_class_add_shortcut()
and must be called during class
initialization.
[skip]
gtk_widget_class_add_binding_action ()
void gtk_widget_class_add_binding_action (GtkWidgetClass *widget_class
,guint keyval
,GdkModifierType mods
,const char *action_name
,const char *format_string
,...
);
Creates a new shortcut for widget_class
that activates the given
action_name
with arguments read according to format_string
.
The arguments and format string must be provided in the same way as
with g_variant_new()
.
This function is a convenience wrapper around
gtk_widget_class_add_shortcut()
and must be called during class
initialization.
[skip]
gtk_widget_class_set_layout_manager_type ()
void gtk_widget_class_set_layout_manager_type (GtkWidgetClass *widget_class
,GType type
);
Sets the type to be used for creating layout managers for widgets of
widget_class
. The given type
must be a subtype of GtkLayoutManager.
This function should only be called from class init functions of widgets.
Parameters
widget_class |
class to set the layout manager type for |
|
type |
The object type that implements the GtkLayoutManager for |
gtk_widget_class_get_layout_manager_type ()
GType
gtk_widget_class_get_layout_manager_type
(GtkWidgetClass *widget_class
);
Retrieves the type of the GtkLayoutManager used by the GtkWidget class.
gtk_widget_class_set_activate_signal ()
void gtk_widget_class_set_activate_signal (GtkWidgetClass *widget_class
,guint signal_id
);
Sets the GtkWidgetClass.activate_signal field with the
given signal_id
; the signal will be emitted when calling
gtk_widget_activate()
.
The signal_id
must have been registered with g_signal_new()
or g_signal_newv()
before calling this function.
gtk_widget_class_set_activate_signal_from_name ()
void gtk_widget_class_set_activate_signal_from_name (GtkWidgetClass *widget_class
,const char *signal_name
);
Sets the GtkWidgetClass.activate_signal field with the signal id for
the given signal_name
; the signal will be emitted when calling
gtk_widget_activate()
.
The signal_name
of widget_type
must have been registered with
g_signal_new()
or g_signal_newv()
before calling this function.
gtk_widget_class_get_activate_signal ()
guint
gtk_widget_class_get_activate_signal (GtkWidgetClass *widget_class
);
Retrieves the signal id for the activation signal set using
gtk_widget_class_set_activate_signal()
.
gtk_widget_activate ()
gboolean
gtk_widget_activate (GtkWidget *widget
);
For widgets that can be “activated” (buttons, menu items, etc.)
this function activates them. The activation will emit the signal
set using gtk_widget_class_set_activate_signal()
during class
initialization.
Activation is what happens when you press Enter on a widget during key navigation.
If you wish to handle the activation keybinding yourself, it is
recommended to use gtk_widget_class_add_shortcut()
with an action
created with gtk_signal_action_new()
.
If widget
isn't activatable, the function returns FALSE
.
gtk_widget_is_focus ()
gboolean
gtk_widget_is_focus (GtkWidget *widget
);
Determines if the widget is the focus widget within its toplevel. (This does not mean that the “has-focus” property is necessarily set; “has-focus” will only be set if the toplevel widget additionally has the global input focus.)
gtk_widget_grab_focus ()
gboolean
gtk_widget_grab_focus (GtkWidget *widget
);
Causes widget
(or one of its descendents) to have the keyboard focus
for the GtkWindow it's inside.
If widget
is not focusable, or its ::grab_focus implementation cannot
transfer the focus to a descendant of widget
that is focusable, it will
not take focus and FALSE
will be returned.
Calling gtk_widget_grab_focus()
on an already focused widget is allowed,
should not have an effect, and return TRUE
.
gtk_widget_set_name ()
void gtk_widget_set_name (GtkWidget *widget
,const char *name
);
Widgets can be named, which allows you to refer to them from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for GtkStyleContext).
Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice.
gtk_widget_get_name ()
const char *
gtk_widget_get_name (GtkWidget *widget
);
Retrieves the name of a widget. See gtk_widget_set_name()
for the
significance of widget names.
gtk_widget_set_sensitive ()
void gtk_widget_set_sensitive (GtkWidget *widget
,gboolean 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.
gtk_widget_set_parent ()
void gtk_widget_set_parent (GtkWidget *widget
,GtkWidget *parent
);
This function is useful only when implementing subclasses of GtkWidget.
Sets parent
as the parent widget of widget
, and takes care of
some details such as updating the state and style of the child
to reflect its new location and resizing the parent. The opposite
function is gtk_widget_unparent()
.
gtk_widget_get_root ()
GtkRoot *
gtk_widget_get_root (GtkWidget *widget
);
Returns the GtkRoot widget of widget
or NULL
if the widget is not contained
inside a widget tree with a root widget.
GtkRoot widgets will return themselves here.
gtk_widget_get_native ()
GtkNative *
gtk_widget_get_native (GtkWidget *widget
);
Returns the GtkNative widget that contains widget
,
or NULL
if the widget is not contained inside a
widget tree with a native ancestor.
GtkNative widgets will return themselves here.
gtk_widget_get_ancestor ()
GtkWidget * gtk_widget_get_ancestor (GtkWidget *widget
,GType widget_type
);
Gets the first ancestor of widget
with type widget_type
. For example,
gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)
gets
the first GtkBox that’s an ancestor of widget
. No reference will be
added to the returned widget; it should not be unreferenced.
Note that unlike gtk_widget_is_ancestor()
, gtk_widget_get_ancestor()
considers widget
to be an ancestor of itself.
gtk_widget_is_ancestor ()
gboolean gtk_widget_is_ancestor (GtkWidget *widget
,GtkWidget *ancestor
);
Determines whether widget
is somewhere inside ancestor
, possibly with
intermediate containers.
gtk_widget_translate_coordinates ()
gboolean gtk_widget_translate_coordinates (GtkWidget *src_widget
,GtkWidget *dest_widget
,double src_x
,double src_y
,double *dest_x
,double *dest_y
);
Translate coordinates relative to src_widget
’s allocation to coordinates
relative to dest_widget
’s allocations. In order to perform this
operation, both widget must share a common toplevel.
gtk_widget_add_controller ()
void gtk_widget_add_controller (GtkWidget *widget
,GtkEventController *controller
);
Adds controller
to widget
so that it will receive events. You will
usually want to call this function right after creating any kind of
GtkEventController.
Parameters
widget |
||
controller |
a GtkEventController that hasn't been added to a widget yet. |
[transfer full] |
gtk_widget_remove_controller ()
void gtk_widget_remove_controller (GtkWidget *widget
,GtkEventController *controller
);
Removes controller
from widget
, so that it doesn't process
events anymore. It should not be used again.
Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function.
gtk_widget_set_direction ()
void gtk_widget_set_direction (GtkWidget *widget
,GtkTextDirection dir
);
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 explicitly 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.
gtk_widget_get_direction ()
GtkTextDirection
gtk_widget_get_direction (GtkWidget *widget
);
Gets the reading direction for a particular widget. See
gtk_widget_set_direction()
.
gtk_widget_set_default_direction ()
void
gtk_widget_set_default_direction (GtkTextDirection dir
);
Sets the default reading direction for widgets where the
direction has not been explicitly set by gtk_widget_set_direction()
.
gtk_widget_get_default_direction ()
GtkTextDirection
gtk_widget_get_default_direction (void
);
Obtains the current default reading direction. See
gtk_widget_set_default_direction()
.
gtk_widget_create_pango_context ()
PangoContext *
gtk_widget_create_pango_context (GtkWidget *widget
);
Creates a new PangoContext with the appropriate font map,
font options, font description, and base direction for drawing
text for this widget. See also gtk_widget_get_pango_context()
.
gtk_widget_get_pango_context ()
PangoContext *
gtk_widget_get_pango_context (GtkWidget *widget
);
Gets a PangoContext 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. This can be tracked
by listening to changes of the “root” property on the widget.
gtk_widget_set_font_options ()
void gtk_widget_set_font_options (GtkWidget *widget
,const cairo_font_options_t *options
);
Sets the cairo_font_options_t used for Pango rendering in this widget. When not set, the default font options for the GdkDisplay will be used.
Parameters
widget |
||
options |
a cairo_font_options_t, or |
[allow-none] |
gtk_widget_get_font_options ()
const cairo_font_options_t *
gtk_widget_get_font_options (GtkWidget *widget
);
Returns the cairo_font_options_t used for Pango rendering. When not set, the defaults font options for the GdkDisplay will be used.
gtk_widget_set_font_map ()
void gtk_widget_set_font_map (GtkWidget *widget
,PangoFontMap *font_map
);
Sets the font map to use for Pango rendering. The font map is the object that is used to look up fonts. Setting a custom font map can be useful in special situations, e.g. when you need to add application-specific fonts to the set of available fonts.
When not set, the widget will inherit the font map from its parent.
Parameters
widget |
||
font_map |
a PangoFontMap, or |
[allow-none] |
gtk_widget_get_font_map ()
PangoFontMap *
gtk_widget_get_font_map (GtkWidget *widget
);
Gets the font map that has been set with gtk_widget_set_font_map()
.
gtk_widget_create_pango_layout ()
PangoLayout * gtk_widget_create_pango_layout (GtkWidget *widget
,const char *text
);
Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget.
If you keep a PangoLayout created in this way around, you need to re-create it when the widget PangoContext is replaced. This can be tracked by listening to changes of the “root” property on the widget.
gtk_widget_get_cursor ()
GdkCursor *
gtk_widget_get_cursor (GtkWidget *widget
);
Queries the cursor set via gtk_widget_set_cursor()
. See that function for
details.
gtk_widget_set_cursor ()
void gtk_widget_set_cursor (GtkWidget *widget
,GdkCursor *cursor
);
Sets the cursor to be shown when pointer devices point towards widget
.
If the cursor
is NULL, widget
will use the cursor inherited from the
parent widget.
gtk_widget_set_cursor_from_name ()
void gtk_widget_set_cursor_from_name (GtkWidget *widget
,const char *name
);
Sets a named cursor to be shown when pointer devices point towards widget
.
This is a utility function that creates a cursor via
gdk_cursor_new_from_name()
and then sets it on widget
with
gtk_widget_set_cursor()
. See those 2 functions for details.
On top of that, this function allows name
to be NULL
, which will
do the same as calling gtk_widget_set_cursor()
with a NULL
cursor.
gtk_widget_mnemonic_activate ()
gboolean gtk_widget_mnemonic_activate (GtkWidget *widget
,gboolean group_cycling
);
Emits the “mnemonic-activate” signal.
gtk_widget_class_set_accessible_role ()
void gtk_widget_class_set_accessible_role (GtkWidgetClass *widget_class
,GtkAccessibleRole accessible_role
);
Sets the accessible role used by the given GtkWidget class.
Different accessible roles have different states, and are rendered differently by assistive technologies.
gtk_widget_class_get_accessible_role ()
GtkAccessibleRole
gtk_widget_class_get_accessible_role (GtkWidgetClass *widget_class
);
Retrieves the accessible role used by the given GtkWidget class.
Different accessible roles have different states, and are rendered differently by assistive technologies.
See also: gtk_accessible_get_accessible_role()
gtk_widget_child_focus ()
gboolean gtk_widget_child_focus (GtkWidget *widget
,GtkDirectionType direction
);
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.
gtk_widget_child_focus() is called by widgets 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()
calls the
GtkWidgetClass.focus()
vfunc; widgets override this vfunc
in order to implement appropriate focus behavior.
The default focus()
vfunc 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 gtk_widget_grab_focus()
to place the focus accordingly;
if returning FALSE
, they don’t modify the current focus location.
gtk_widget_get_child_visible ()
gboolean
gtk_widget_get_child_visible (GtkWidget *widget
);
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.
gtk_widget_get_parent ()
GtkWidget *
gtk_widget_get_parent (GtkWidget *widget
);
Returns the parent widget of widget
.
gtk_widget_get_settings ()
GtkSettings *
gtk_widget_get_settings (GtkWidget *widget
);
Gets the settings object holding the settings used for this widget.
Note that this function can only be called when the GtkWidget is attached to a toplevel, since the settings object is specific to a particular GdkDisplay. If you want to monitor the widget for changes in its settings, connect to notify::display.
gtk_widget_get_clipboard ()
GdkClipboard *
gtk_widget_get_clipboard (GtkWidget *widget
);
This is a utility function to get the clipboard object for the
GdkDisplay that widget
is using.
Note that this function always works, even when widget
is not
realized yet.
gtk_widget_get_primary_clipboard ()
GdkClipboard *
gtk_widget_get_primary_clipboard (GtkWidget *widget
);
This is a utility function to get the primary clipboard object
for the GdkDisplay that widget
is using.
Note that this function always works, even when widget
is not
realized yet.
gtk_widget_get_display ()
GdkDisplay *
gtk_widget_get_display (GtkWidget *widget
);
Get the GdkDisplay 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 GtkWindow 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.
gtk_widget_get_size_request ()
void gtk_widget_get_size_request (GtkWidget *widget
,int *width
,int *height
);
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 instead. See
gtk_widget_set_size_request()
. To get the size a widget will
actually request, call gtk_widget_measure()
instead of
this function.
gtk_widget_set_child_visible ()
void gtk_widget_set_child_visible (GtkWidget *widget
,gboolean 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 TRUE
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.
gtk_widget_set_size_request ()
void gtk_widget_set_size_request (GtkWidget *widget
,int width
,int height
);
Sets the minimum size of a widget; that is, the widget’s size
request will be at least width
by height
. You can use this
function to force a widget to be larger 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.
The size request set here does not include any margin from the GtkWidget properties margin-left, margin-right, margin-top, and margin-bottom, but it does include pretty much all other padding or border properties set by any subclass of GtkWidget.
gtk_widget_list_mnemonic_labels ()
GList *
gtk_widget_list_mnemonic_labels (GtkWidget *widget
);
Returns a newly allocated list of the widgets, normally labels, for
which this widget is 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.
gtk_widget_add_mnemonic_label ()
void gtk_widget_add_mnemonic_label (GtkWidget *widget
,GtkWidget *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.
gtk_widget_remove_mnemonic_label ()
void gtk_widget_remove_mnemonic_label (GtkWidget *widget
,GtkWidget *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()
.
Parameters
widget |
||
label |
a GtkWidget that was previously set as a mnemonic label for
|
gtk_widget_error_bell ()
void
gtk_widget_error_bell (GtkWidget *widget
);
Notifies the user about an input-related error on this widget.
If the “gtk-error-bell” setting is TRUE
, it calls
gdk_surface_beep()
, otherwise it does nothing.
Note that the effect of gdk_surface_beep()
can be configured in many
ways, depending on the windowing backend and the desktop environment
or window manager that is used.
gtk_widget_keynav_failed ()
gboolean gtk_widget_keynav_failed (GtkWidget *widget
,GtkDirectionType direction
);
This function should be called whenever keyboard navigation within
a single widget hits a boundary. The function emits the
“keynav-failed” signal on the widget and its return
value should be interpreted in a way similar to the return value of
gtk_widget_child_focus()
:
When TRUE
is returned, stay in the widget, the failed keyboard
navigation is OK and/or there is nowhere we can/should move the
focus to.
When FALSE
is returned, the caller should continue with keyboard
navigation outside the widget, e.g. by calling
gtk_widget_child_focus()
on the widget’s toplevel.
The default ::keynav-failed handler returns FALSE
for
GTK_DIR_TAB_FORWARD
and GTK_DIR_TAB_BACKWARD
. For the other
values of GtkDirectionType it returns TRUE
.
Whenever the default handler returns TRUE
, it also calls
gtk_widget_error_bell()
to notify the user of the failed keyboard
navigation.
A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys.
gtk_widget_get_tooltip_markup ()
const char *
gtk_widget_get_tooltip_markup (GtkWidget *widget
);
Gets the contents of the tooltip for widget
set using
gtk_widget_set_tooltip_markup()
.
gtk_widget_set_tooltip_markup ()
void gtk_widget_set_tooltip_markup (GtkWidget *widget
,const char *markup
);
Sets markup
as the contents of the tooltip, which is marked up with
the Pango text markup language.
This function will take care of setting the “has-tooltip” as a side effect, and of the default handler for the “query-tooltip” signal.
See also the “tooltip-markup” property and
gtk_tooltip_set_markup()
.
gtk_widget_get_tooltip_text ()
const char *
gtk_widget_get_tooltip_text (GtkWidget *widget
);
Gets the contents of the tooltip for widget
.
If the widget
's tooltip was set using gtk_widget_set_tooltip_markup()
,
this function will return the escaped text.
gtk_widget_set_tooltip_text ()
void gtk_widget_set_tooltip_text (GtkWidget *widget
,const char *text
);
Sets text
as the contents of the tooltip.
If text
contains any markup, it will be escaped.
This function will take care of setting “has-tooltip” as a side effect, and of the default handler for the “query-tooltip” signal.
See also the “tooltip-text” property and
gtk_tooltip_set_text()
.
gtk_widget_get_has_tooltip ()
gboolean
gtk_widget_get_has_tooltip (GtkWidget *widget
);
Returns the current value of the has-tooltip property. See “has-tooltip” for more information.
gtk_widget_set_has_tooltip ()
void gtk_widget_set_has_tooltip (GtkWidget *widget
,gboolean has_tooltip
);
Sets the has-tooltip property on widget
to has_tooltip
. See
“has-tooltip” for more information.
gtk_widget_trigger_tooltip_query ()
void
gtk_widget_trigger_tooltip_query (GtkWidget *widget
);
Triggers a tooltip query on the display where the toplevel
of widget
is located.
gtk_widget_get_allocated_width ()
int
gtk_widget_get_allocated_width (GtkWidget *widget
);
Returns the width that has currently been allocated to widget
.
gtk_widget_get_allocated_height ()
int
gtk_widget_get_allocated_height (GtkWidget *widget
);
Returns the height that has currently been allocated to widget
.
gtk_widget_get_allocation ()
void gtk_widget_get_allocation (GtkWidget *widget
,GtkAllocation *allocation
);
Retrieves the widget’s allocation.
Note, when implementing a layout container: a widget’s allocation
will be its “adjusted” allocation, that is, the widget’s parent
typically calls gtk_widget_size_allocate()
with an allocation,
and that allocation is then adjusted (to handle margin
and alignment for example) before assignment to the widget.
gtk_widget_get_allocation()
returns the adjusted allocation that
was actually assigned to the widget. The adjusted allocation is
guaranteed to be completely contained within the
gtk_widget_size_allocate()
allocation, however.
So a layout container is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned.
gtk_widget_get_allocated_baseline ()
int
gtk_widget_get_allocated_baseline (GtkWidget *widget
);
Returns the baseline that has currently been allocated to widget
.
This function is intended to be used when implementing handlers
for the GtkWidgetClass.snapshot()
function, and when allocating child
widgets in GtkWidgetClass.size_allocate()
.
gtk_widget_get_width ()
int
gtk_widget_get_width (GtkWidget *widget
);
Returns the content width of the widget, as passed to its size-allocate implementation.
This is the size you should be using in GtkWidgetClass.snapshot(). For pointer
events, see gtk_widget_contains()
.
gtk_widget_get_height ()
int
gtk_widget_get_height (GtkWidget *widget
);
Returns the content height of the widget, as passed to its size-allocate implementation.
This is the size you should be using in GtkWidgetClass.snapshot(). For pointer
events, see gtk_widget_contains()
.
gtk_widget_get_size ()
int gtk_widget_get_size (GtkWidget *widget
,GtkOrientation orientation
);
Returns the content width or height of the widget, depending on orientation
.
This is equivalent to calling gtk_widget_get_width()
for GTK_ORIENTATION_HORIZONTAL
or gtk_widget_get_height()
for GTK_ORIENTATION_VERTICAL
, but can be used when
writing orientation-independent code, such as when implementing GtkOrientable
widgets.
gtk_widget_compute_bounds ()
gboolean gtk_widget_compute_bounds (GtkWidget *widget
,GtkWidget *target
,graphene_rect_t *out_bounds
);
Computes the bounds for widget
in the coordinate space of target
.
FIXME: Explain what "bounds" are.
If the operation is successful, TRUE
is returned. If widget
has no
bounds or the bounds cannot be expressed in target
's coordinate space
(for example if both widgets are in different windows), FALSE
is
returned and bounds
is set to the zero rectangle.
It is valid for widget
and target
to be the same widget.
gtk_widget_compute_transform ()
gboolean gtk_widget_compute_transform (GtkWidget *widget
,GtkWidget *target
,graphene_matrix_t *out_transform
);
Computes a matrix suitable to describe a transformation from
widget
's coordinate system into target
's coordinate system.
gtk_widget_compute_point ()
gboolean gtk_widget_compute_point (GtkWidget *widget
,GtkWidget *target
,const graphene_point_t *point
,graphene_point_t *out_point
);
Translates the given point
in widget
's coordinates to coordinates
relative to target
’s coordinate system. In order to perform this
operation, both widgets must share a common root.
gtk_widget_contains ()
gboolean gtk_widget_contains (GtkWidget *widget
,double x
,double y
);
Tests if the point at (x
, y
) is contained in widget
.
The coordinates for (x
, y
) must be in widget coordinates, so
(0, 0) is assumed to be the top left of widget
's content area.
gtk_widget_pick ()
GtkWidget * gtk_widget_pick (GtkWidget *widget
,double x
,double y
,GtkPickFlags flags
);
Finds the descendant of widget
(including widget
itself) closest
to the screen at the point (x
, y
). The point must be given in
widget coordinates, so (0, 0) is assumed to be the top left of
widget
's content area.
Usually widgets will return NULL
if the given coordinate is not
contained in widget
checked via gtk_widget_contains()
. Otherwise
they will recursively try to find a child that does not return NULL
.
Widgets are however free to customize their picking algorithm.
This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events.
gtk_widget_get_can_focus ()
gboolean
gtk_widget_get_can_focus (GtkWidget *widget
);
Determines whether the input focus can enter widget
or any
of its children.
gtk_widget_set_can_focus ()
void gtk_widget_set_can_focus (GtkWidget *widget
,gboolean can_focus
);
Specifies whether the input focus can enter the widget or any of its children.
Applications should set can_focus
to FALSE
to mark a
widget as for pointer/touch use only.
Note that having can_focus
be TRUE
is only one of the
necessary conditions for being focusable. A widget must
also be sensitive and focusable and not have an ancestor
that is marked as not can-focus in order to receive input
focus.
See gtk_widget_grab_focus()
for actually setting the input
focus on a widget.
gtk_widget_get_focusable ()
gboolean
gtk_widget_get_focusable (GtkWidget *widget
);
Determines whether widget
can own the input focus.
See gtk_widget_set_focusable()
.
gtk_widget_set_focusable ()
void gtk_widget_set_focusable (GtkWidget *widget
,gboolean focusable
);
Specifies whether widget
can own the input focus.
Widget implementations should set focusable
to TRUE
in
their init()
function if they want to receive keyboard input.
Note that having focusable
be TRUE
is only one of the
necessary conditions for being focusable. A widget must
also be sensitive and can-focus and not have an ancestor
that is marked as not can-focus in order to receive input
focus.
See gtk_widget_grab_focus()
for actually setting the input
focus on a widget.
gtk_widget_get_focus_on_click ()
gboolean
gtk_widget_get_focus_on_click (GtkWidget *widget
);
Returns whether the widget should grab focus when it is clicked with the mouse.
See gtk_widget_set_focus_on_click()
.
gtk_widget_set_focus_on_click ()
void gtk_widget_set_focus_on_click (GtkWidget *widget
,gboolean focus_on_click
);
Sets whether the widget should grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application.
gtk_widget_get_focus_child ()
GtkWidget *
gtk_widget_get_focus_child (GtkWidget *widget
);
Returns the current focus child of widget
.
gtk_widget_set_focus_child ()
void gtk_widget_set_focus_child (GtkWidget *widget
,GtkWidget *child
);
Set child
as the current focus child of widget
. The previous
focus child will be unset.
This function is only suitable for widget implementations.
If you want a certain widget to get the input focus, call
gtk_widget_grab_focus()
on it.
gtk_widget_get_can_target ()
gboolean
gtk_widget_get_can_target (GtkWidget *widget
);
Queries whether widget
can be the target of pointer events.
gtk_widget_set_can_target ()
void gtk_widget_set_can_target (GtkWidget *widget
,gboolean can_target
);
Sets whether widget
can be the target of pointer events.
gtk_widget_get_sensitive ()
gboolean
gtk_widget_get_sensitive (GtkWidget *widget
);
Returns the widget’s sensitivity (in the sense of returning
the value that has been set using gtk_widget_set_sensitive()
).
The effective sensitivity of a widget is however determined by both its
own and its parent widget’s sensitivity. See gtk_widget_is_sensitive()
.
gtk_widget_is_sensitive ()
gboolean
gtk_widget_is_sensitive (GtkWidget *widget
);
Returns the widget’s effective sensitivity, which means it is sensitive itself and also its parent widget is sensitive
gtk_widget_get_visible ()
gboolean
gtk_widget_get_visible (GtkWidget *widget
);
Determines whether the widget is visible. If you want to
take into account whether the widget’s parent is also marked as
visible, use gtk_widget_is_visible()
instead.
This function does not check if the widget is obscured in any way.
gtk_widget_is_visible ()
gboolean
gtk_widget_is_visible (GtkWidget *widget
);
Determines whether the widget and all its parents are marked as visible.
This function does not check if the widget is obscured in any way.
See also gtk_widget_get_visible()
and gtk_widget_set_visible()
gtk_widget_set_visible ()
void gtk_widget_set_visible (GtkWidget *widget
,gboolean visible
);
Sets the visibility state of widget
. Note that setting this to
TRUE
doesn’t mean the widget is actually viewable, see
gtk_widget_get_visible()
.
This function simply calls gtk_widget_show()
or gtk_widget_hide()
but is nicer to use when the visibility of the widget depends on
some condition.
gtk_widget_set_state_flags ()
void gtk_widget_set_state_flags (GtkWidget *widget
,GtkStateFlags flags
,gboolean clear
);
This function is for use in widget implementations. Turns on flag values in the current widget state (insensitive, prelighted, etc.).
This function accepts the values GTK_STATE_FLAG_DIR_LTR
and
GTK_STATE_FLAG_DIR_RTL
but ignores them. If you want to set
the widget's direction, use gtk_widget_set_direction()
.
gtk_widget_unset_state_flags ()
void gtk_widget_unset_state_flags (GtkWidget *widget
,GtkStateFlags flags
);
This function is for use in widget implementations. Turns off flag
values for the current widget state (insensitive, prelighted, etc.).
See gtk_widget_set_state_flags()
.
gtk_widget_get_state_flags ()
GtkStateFlags
gtk_widget_get_state_flags (GtkWidget *widget
);
Returns the widget state as a flag set. It is worth mentioning
that the effective GTK_STATE_FLAG_INSENSITIVE
state will be
returned, that is, also based on parent insensitivity, even if
widget
itself is sensitive.
Also note that if you are looking for a way to obtain the
GtkStateFlags to pass to a GtkStyleContext method, you
should look at gtk_style_context_get_state()
.
gtk_widget_has_default ()
gboolean
gtk_widget_has_default (GtkWidget *widget
);
Determines whether widget
is the current default widget within its
toplevel.
gtk_widget_has_focus ()
gboolean
gtk_widget_has_focus (GtkWidget *widget
);
Determines if the widget has the global input focus. See
gtk_widget_is_focus()
for the difference between having the global
input focus, and only having the focus within a toplevel.
gtk_widget_has_visible_focus ()
gboolean
gtk_widget_has_visible_focus (GtkWidget *widget
);
Determines if the widget should show a visible indication that
it has the global input focus. This is a convenience function
that takes into account whether focus indication should currently
be shown in the toplevel window of widget
.
See gtk_window_get_focus_visible()
for more information
about focus indication.
To find out if the widget has the global input focus, use
gtk_widget_has_focus()
.
gtk_widget_is_drawable ()
gboolean
gtk_widget_is_drawable (GtkWidget *widget
);
Determines whether widget
can be drawn to. A widget can be drawn
if it is mapped and visible.
gtk_widget_set_receives_default ()
void gtk_widget_set_receives_default (GtkWidget *widget
,gboolean receives_default
);
Specifies whether widget
will be treated as the default
widget within its toplevel when it has the focus, even if
another widget is the default.
gtk_widget_get_receives_default ()
gboolean
gtk_widget_get_receives_default (GtkWidget *widget
);
Determines whether widget
is always treated as the default widget
within its toplevel when it has the focus, even if another widget
is the default.
gtk_widget_get_realized ()
gboolean
gtk_widget_get_realized (GtkWidget *widget
);
Determines whether widget
is realized.
gtk_widget_get_mapped ()
gboolean
gtk_widget_get_mapped (GtkWidget *widget
);
Whether the widget is mapped.
gtk_widget_get_opacity ()
double
gtk_widget_get_opacity (GtkWidget *widget
);
Fetches the requested opacity for this widget.
See gtk_widget_set_opacity()
.
gtk_widget_set_opacity ()
void gtk_widget_set_opacity (GtkWidget *widget
,double opacity
);
Request the widget
to be rendered partially transparent, with
opacity 0 being fully transparent and 1 fully opaque. (Opacity
values are clamped to the [0,1] range).
Opacity works on both toplevel widgets and child widgets, although
there are some limitations: For toplevel widgets, applying opacity
depends on the capabilities of the windowing system. On X11, this
has any effect only on X displays with a compositing manager,
see gdk_display_is_composited()
. On Windows and Wayland it should
always work, although setting a window’s opacity after the window
has been shown may cause some flicker.
Note that the opacity is inherited through inclusion — if you set a toplevel to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel. The opacity value itself is not inherited by child widgets (since that would make widgets deeper in the hierarchy progressively more translucent). As a consequence, GtkPopovers and other GtkNative widgets with their own surface will use their own opacity value, and thus by default appear non-translucent, even if they are attached to a toplevel that is translucent.
gtk_widget_get_overflow ()
GtkOverflow
gtk_widget_get_overflow (GtkWidget *widget
);
Returns the value set via gtk_widget_set_overflow()
.
gtk_widget_set_overflow ()
void gtk_widget_set_overflow (GtkWidget *widget
,GtkOverflow overflow
);
Sets how widget
treats content that is drawn outside the widget's content area.
See the definition of GtkOverflow for details.
This setting is provided for widget implementations and should not be used by application code.
The default value is GTK_OVERFLOW_VISIBLE
.
gtk_widget_measure ()
void gtk_widget_measure (GtkWidget *widget
,GtkOrientation orientation
,int for_size
,int *minimum
,int *natural
,int *minimum_baseline
,int *natural_baseline
);
Measures widget
in the orientation orientation
and for the given for_size
.
As an example, if orientation
is GTK_ORIENTATION_HORIZONTAL
and for_size
is 300,
this functions will compute the minimum and natural width of widget
if
it is allocated at a height of 300 pixels.
See GtkWidget’s geometry management section for
a more details on implementing GtkWidgetClass.measure()
.
Parameters
widget |
A GtkWidget instance |
|
orientation |
the orientation to measure |
|
for_size |
Size for the opposite of |
|
minimum |
location to store the minimum size, or |
[out][optional] |
natural |
location to store the natural size, or |
[out][optional] |
minimum_baseline |
location to store the baseline
position for the minimum size, or |
[out][optional] |
natural_baseline |
location to store the baseline
position for the natural size, or |
[out][optional] |
gtk_widget_snapshot_child ()
void gtk_widget_snapshot_child (GtkWidget *widget
,GtkWidget *child
,GtkSnapshot *snapshot
);
When a widget receives a call to the snapshot function, it must send
synthetic GtkWidgetClass.snapshot()
calls to all children. This function
provides a convenient way of doing this. A widget, when it receives
a call to its GtkWidgetClass.snapshot()
function, calls
gtk_widget_snapshot_child()
once for each child, passing in
the snapshot
the widget received.
gtk_widget_snapshot_child() takes care of translating the origin of
snapshot
, and deciding whether the child needs to be snapshot.
This function does nothing for children that implement GtkNative.
Parameters
widget |
||
child |
a child of |
|
snapshot |
GtkSnapshot as passed to the widget. In particular, no
calls to |
gtk_widget_get_next_sibling ()
GtkWidget *
gtk_widget_get_next_sibling (GtkWidget *widget
);
Returns the widgets next sibling.
This API is primarily meant for widget implementations.
gtk_widget_get_prev_sibling ()
GtkWidget *
gtk_widget_get_prev_sibling (GtkWidget *widget
);
Returns the widgets previous sibling.
This API is primarily meant for widget implementations.
gtk_widget_get_first_child ()
GtkWidget *
gtk_widget_get_first_child (GtkWidget *widget
);
Returns the widgets first child.
This API is primarily meant for widget implementations.
gtk_widget_get_last_child ()
GtkWidget *
gtk_widget_get_last_child (GtkWidget *widget
);
Returns the widgets last child.
This API is primarily meant for widget implementations.
gtk_widget_insert_before ()
void gtk_widget_insert_before (GtkWidget *widget
,GtkWidget *parent
,GtkWidget *next_sibling
);
Inserts widget
into the child widget list of parent
.
It will be placed before next_sibling
, or at the end if
next_sibling
is NULL
.
After calling this function, gtk_widget_get_next_sibling(widget)
will return next_sibling
.
If parent
is already set as the parent widget of widget
, this function
can also be used to reorder widget
in the child widget list of parent
.
This API is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children.
gtk_widget_insert_after ()
void gtk_widget_insert_after (GtkWidget *widget
,GtkWidget *parent
,GtkWidget *previous_sibling
);
Inserts widget
into the child widget list of parent
.
It will be placed after previous_sibling
, or at the beginning if
previous_sibling
is NULL
.
After calling this function, gtk_widget_get_prev_sibling(widget) will
return previous_sibling
.
If parent
is already set as the parent widget of widget
, this function
can also be used to reorder widget
in the child widget list of parent
.
This API is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children.
gtk_widget_set_layout_manager ()
void gtk_widget_set_layout_manager (GtkWidget *widget
,GtkLayoutManager *layout_manager
);
Sets the layout manager delegate instance that provides an implementation
for measuring and allocating the children of widget
.
gtk_widget_get_layout_manager ()
GtkLayoutManager *
gtk_widget_get_layout_manager (GtkWidget *widget
);
Retrieves the layout manager set using gtk_widget_set_layout_manager()
.
gtk_widget_should_layout ()
gboolean
gtk_widget_should_layout (GtkWidget *widget
);
Returns whether widget
should contribute to
the measuring and allocation of its parent.
This is FALSE
for invisible children, but also
for children that have their own surface.
gtk_widget_get_css_name ()
const char *
gtk_widget_get_css_name (GtkWidget *self
);
Returns the CSS name that is used for self
.
gtk_widget_add_css_class ()
void gtk_widget_add_css_class (GtkWidget *widget
,const char *css_class
);
Adds css_class
to widget
. After calling this function, widget
's
style will match for css_class
, after the CSS matching rules.
gtk_widget_remove_css_class ()
void gtk_widget_remove_css_class (GtkWidget *widget
,const char *css_class
);
Removes css_class
from widget
. After this, the style of widget
will stop matching for css_class
.
gtk_widget_has_css_class ()
gboolean gtk_widget_has_css_class (GtkWidget *widget
,const char *css_class
);
Returns whether css_class
is currently applied to widget
.
gtk_widget_get_css_classes ()
char **
gtk_widget_get_css_classes (GtkWidget *widget
);
Returns the list of css classes applied to widget
.
gtk_widget_set_css_classes ()
void gtk_widget_set_css_classes (GtkWidget *widget
,const char **classes
);
Will clear all css classes applied to widget
and replace them with classes
.
gtk_widget_get_style_context ()
GtkStyleContext *
gtk_widget_get_style_context (GtkWidget *widget
);
Returns the style context associated to widget
. The returned object is
guaranteed to be the same for the lifetime of widget
.
gtk_widget_class_get_css_name ()
const char *
gtk_widget_class_get_css_name (GtkWidgetClass *widget_class
);
Gets the name used by this class for matching in CSS code. See
gtk_widget_class_set_css_name()
for details.
gtk_widget_class_set_css_name ()
void gtk_widget_class_set_css_name (GtkWidgetClass *widget_class
,const char *name
);
Sets the name to be used for CSS matching of widgets.
If this function is not called for a given class, the name set on the parent class is used. By default, GtkWidget uses the name "widget".
gtk_requisition_new ()
GtkRequisition *
gtk_requisition_new (void
);
Allocates a new GtkRequisition and initializes its elements to zero.
Returns
a new empty GtkRequisition. The newly allocated GtkRequisition should
be freed with gtk_requisition_free()
.
gtk_requisition_copy ()
GtkRequisition *
gtk_requisition_copy (const GtkRequisition *requisition
);
Copies a GtkRequisition.
gtk_requisition_free ()
void
gtk_requisition_free (GtkRequisition *requisition
);
Frees a GtkRequisition.
gtk_widget_get_request_mode ()
GtkSizeRequestMode
gtk_widget_get_request_mode (GtkWidget *widget
);
Gets whether the widget prefers a height-for-width layout or a width-for-height layout.
GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities.
gtk_widget_get_preferred_size ()
void gtk_widget_get_preferred_size (GtkWidget *widget
,GtkRequisition *minimum_size
,GtkRequisition *natural_size
);
Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.
This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as GtkLayout.
Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width.
Use gtk_widget_measure()
if you want to support
baseline alignment.
Parameters
widget |
a GtkWidget instance |
|
minimum_size |
location for storing the minimum size, or |
[out][allow-none] |
natural_size |
location for storing the natural size, or |
[out][allow-none] |
gtk_distribute_natural_allocation ()
int gtk_distribute_natural_allocation (int extra_space
,guint n_requested_sizes
,GtkRequestedSize *sizes
);
Distributes extra_space
to child sizes
by bringing smaller
children up to natural size first.
The remaining space will be added to the minimum_size
member of the
GtkRequestedSize struct. If all sizes reach their natural size then
the remaining space is returned.
Parameters
extra_space |
Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation |
|
n_requested_sizes |
Number of requests to fit into the allocation |
|
sizes |
An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation. |
gtk_widget_get_halign ()
GtkAlign
gtk_widget_get_halign (GtkWidget *widget
);
Gets the value of the “halign” property.
For backwards compatibility reasons this method will never return
GTK_ALIGN_BASELINE
, but instead it will convert it to
GTK_ALIGN_FILL
. Baselines are not supported for horizontal
alignment.
gtk_widget_set_halign ()
void gtk_widget_set_halign (GtkWidget *widget
,GtkAlign align
);
Sets the horizontal alignment of widget
.
See the “halign” property.
gtk_widget_get_valign ()
GtkAlign
gtk_widget_get_valign (GtkWidget *widget
);
Gets the value of the “valign” property.
gtk_widget_set_valign ()
void gtk_widget_set_valign (GtkWidget *widget
,GtkAlign align
);
Sets the vertical alignment of widget
.
See the “valign” property.
gtk_widget_get_margin_start ()
int
gtk_widget_get_margin_start (GtkWidget *widget
);
Gets the value of the “margin-start” property.
gtk_widget_set_margin_start ()
void gtk_widget_set_margin_start (GtkWidget *widget
,int margin
);
Sets the start margin of widget
.
See the “margin-start” property.
gtk_widget_get_margin_end ()
int
gtk_widget_get_margin_end (GtkWidget *widget
);
Gets the value of the “margin-end” property.
gtk_widget_set_margin_end ()
void gtk_widget_set_margin_end (GtkWidget *widget
,int margin
);
Sets the end margin of widget
.
See the “margin-end” property.
gtk_widget_get_margin_top ()
int
gtk_widget_get_margin_top (GtkWidget *widget
);
Gets the value of the “margin-top” property.
gtk_widget_set_margin_top ()
void gtk_widget_set_margin_top (GtkWidget *widget
,int margin
);
Sets the top margin of widget
.
See the “margin-top” property.
gtk_widget_get_margin_bottom ()
int
gtk_widget_get_margin_bottom (GtkWidget *widget
);
Gets the value of the “margin-bottom” property.
gtk_widget_set_margin_bottom ()
void gtk_widget_set_margin_bottom (GtkWidget *widget
,int margin
);
Sets the bottom margin of widget
.
See the “margin-bottom” property.
gtk_widget_get_hexpand ()
gboolean
gtk_widget_get_hexpand (GtkWidget *widget
);
Gets whether the widget would like any available extra horizontal space. When a user resizes a GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand.
Containers should use gtk_widget_compute_expand()
rather than
this function, to see whether a widget, or any of its children,
has the expand flag set. If any child of a widget wants to
expand, the parent may ask to expand also.
This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand.
gtk_widget_set_hexpand ()
void gtk_widget_set_hexpand (GtkWidget *widget
,gboolean expand
);
Sets whether the widget would like any available extra horizontal space. When a user resizes a GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand.
Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room.
By default, widgets automatically expand if any of their children
want to expand. (To see if a widget will automatically expand given
its current children and state, call gtk_widget_compute_expand()
. A
container can decide how the expandability of children affects the
expansion of the container by overriding the compute_expand virtual
method on GtkWidget.).
Setting hexpand explicitly with this function will override the automatic expand behavior.
This function forces the widget to expand or not to expand,
regardless of children. The override occurs because
gtk_widget_set_hexpand()
sets the hexpand-set property (see
gtk_widget_set_hexpand_set()
) which causes the widget’s hexpand
value to be used, rather than looking at children and widget state.
gtk_widget_get_hexpand_set ()
gboolean
gtk_widget_get_hexpand_set (GtkWidget *widget
);
Gets whether gtk_widget_set_hexpand()
has been used to
explicitly set the expand flag on this widget.
If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand.
There are few reasons to use this function, but it’s here for completeness and consistency.
gtk_widget_set_hexpand_set ()
void gtk_widget_set_hexpand_set (GtkWidget *widget
,gboolean set
);
Sets whether the hexpand flag (see gtk_widget_get_hexpand()
) will
be used.
The hexpand-set property will be set automatically when you call
gtk_widget_set_hexpand()
to set hexpand, so the most likely
reason to use this function would be to unset an explicit expand
flag.
If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand.
There are few reasons to use this function, but it’s here for completeness and consistency.
gtk_widget_get_vexpand ()
gboolean
gtk_widget_get_vexpand (GtkWidget *widget
);
Gets whether the widget would like any available extra vertical space.
See gtk_widget_get_hexpand()
for more detail.
gtk_widget_set_vexpand ()
void gtk_widget_set_vexpand (GtkWidget *widget
,gboolean expand
);
Sets whether the widget would like any available extra vertical space.
See gtk_widget_set_hexpand()
for more detail.
gtk_widget_get_vexpand_set ()
gboolean
gtk_widget_get_vexpand_set (GtkWidget *widget
);
Gets whether gtk_widget_set_vexpand()
has been used to
explicitly set the expand flag on this widget.
See gtk_widget_get_hexpand_set()
for more detail.
gtk_widget_set_vexpand_set ()
void gtk_widget_set_vexpand_set (GtkWidget *widget
,gboolean set
);
Sets whether the vexpand flag (see gtk_widget_get_vexpand()
) will
be used.
See gtk_widget_set_hexpand_set()
for more detail.
gtk_widget_compute_expand ()
gboolean gtk_widget_compute_expand (GtkWidget *widget
,GtkOrientation orientation
);
Computes whether a container should give this widget extra space
when possible. Containers should check this, rather than
looking at gtk_widget_get_hexpand()
or gtk_widget_get_vexpand()
.
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.
gtk_widget_init_template ()
void
gtk_widget_init_template (GtkWidget *widget
);
Creates and initializes child widgets defined in templates. This
function must be called in the instance initializer for any
class which assigned itself a template using gtk_widget_class_set_template()
It is important to call this function in the instance initializer
of a GtkWidget subclass and not in GObject.constructed()
or
GObject.constructor()
for two reasons.
One reason is that generally derived widgets will assume that parent class composite widgets have been created in their instance initializers.
Another reason is that when calling g_object_new()
on a widget with
composite templates, it’s important to build the composite widgets
before the construct properties are set. Properties passed to g_object_new()
should take precedence over properties set in the private template XML.
gtk_widget_class_set_template ()
void gtk_widget_class_set_template (GtkWidgetClass *widget_class
,GBytes *template_bytes
);
This should be called at class initialization time to specify the GtkBuilder XML to be used to extend a widget.
For convenience, gtk_widget_class_set_template_from_resource()
is also provided.
Note that any class that installs templates must call gtk_widget_init_template()
in the widget’s instance initializer.
gtk_widget_class_set_template_from_resource ()
void gtk_widget_class_set_template_from_resource (GtkWidgetClass *widget_class
,const char *resource_name
);
A convenience function to call gtk_widget_class_set_template()
.
Note that any class that installs templates must call gtk_widget_init_template()
in the widget’s instance initializer.
gtk_widget_get_template_child ()
GObject * gtk_widget_get_template_child (GtkWidget *widget
,GType widget_type
,const char *name
);
Fetch an object build from the template XML for widget_type
in this widget
instance.
This will only report children which were previously declared with
gtk_widget_class_bind_template_child_full()
or one of its
variants.
This function is only meant to be called for code which is private to the widget_type
which
declared the child and is meant for language bindings which cannot easily make use
of the GObject structure offsets.
gtk_widget_class_bind_template_child()
#define gtk_widget_class_bind_template_child(widget_class, TypeName, member_name)
Binds a child widget defined in a template to the widget_class
.
This macro is a convenience wrapper around the
gtk_widget_class_bind_template_child_full()
function.
This macro will use the offset of the member_name
inside the TypeName
instance structure.
gtk_widget_class_bind_template_child_internal()
#define gtk_widget_class_bind_template_child_internal(widget_class, TypeName, member_name)
Binds a child widget defined in a template to the widget_class
, and
also makes it available as an internal child in GtkBuilder, under the
name member_name
.
This macro is a convenience wrapper around the
gtk_widget_class_bind_template_child_full()
function.
This macro will use the offset of the member_name
inside the TypeName
instance structure.
gtk_widget_class_bind_template_child_private()
#define gtk_widget_class_bind_template_child_private(widget_class, TypeName, member_name)
Binds a child widget defined in a template to the widget_class
.
This macro is a convenience wrapper around the
gtk_widget_class_bind_template_child_full()
function.
This macro will use the offset of the member_name
inside the TypeName
private data structure (it uses G_PRIVATE_OFFSET()
, so the private struct
must be added with G_ADD_PRIVATE()
).
gtk_widget_class_bind_template_child_internal_private()
#define gtk_widget_class_bind_template_child_internal_private(widget_class, TypeName, member_name)
Binds a child widget defined in a template to the widget_class
, and
also makes it available as an internal child in GtkBuilder, under the
name member_name
.
This macro is a convenience wrapper around the
gtk_widget_class_bind_template_child_full()
function.
This macro will use the offset of the member_name
inside the TypeName
private data structure.
gtk_widget_class_bind_template_child_full ()
void gtk_widget_class_bind_template_child_full (GtkWidgetClass *widget_class
,const char *name
,gboolean internal_child
,gssize struct_offset
);
Automatically assign an object declared in the class template XML to be set to a location
on a freshly built instance’s private data, or alternatively accessible via gtk_widget_get_template_child()
.
The struct can point either into the public instance, then you should use G_STRUCT_OFFSET(WidgetType, member)
for struct_offset
, or in the private struct, then you should use G_PRIVATE_OFFSET(WidgetType, member).
An explicit strong reference will be held automatically for the duration of your
instance’s life cycle, it will be released automatically when GObjectClass.dispose()
runs
on your instance and if a struct_offset
that is != 0 is specified, then the automatic location
in your instance public or private data will be set to NULL
. You can however access an automated child
pointer the first time your classes GObjectClass.dispose()
runs, or alternatively in
GtkWidgetClass.destroy()
.
If internal_child
is specified, GtkBuildableIface.get_internal_child()
will be automatically
implemented by the GtkWidget class so there is no need to implement it manually.
The wrapper macros gtk_widget_class_bind_template_child()
, gtk_widget_class_bind_template_child_internal()
,
gtk_widget_class_bind_template_child_private()
and gtk_widget_class_bind_template_child_internal_private()
might be more convenient to use.
Note that this must be called from a composite widget classes class
initializer after calling gtk_widget_class_set_template()
.
Parameters
widget_class |
||
name |
The “id” of the child defined in the template XML |
|
internal_child |
Whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML |
|
struct_offset |
The structure offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer. |
gtk_widget_class_bind_template_callback()
#define gtk_widget_class_bind_template_callback(widget_class, callback)
Binds a callback function defined in a template to the widget_class
.
This macro is a convenience wrapper around the
gtk_widget_class_bind_template_callback_full()
function. It is not
supported after gtk_widget_class_set_template_scope()
has been used
on widget_class
.
gtk_widget_class_bind_template_callback_full ()
void gtk_widget_class_bind_template_callback_full (GtkWidgetClass *widget_class
,const char *callback_name
,GCallback callback_symbol
);
Declares a callback_symbol
to handle callback_name
from the template XML
defined for widget_type
. This function is not supported after
gtk_widget_class_set_template_scope()
has been used on widget_class
.
See gtk_builder_cscope_add_callback_symbol()
.
Note that this must be called from a composite widget classes class
initializer after calling gtk_widget_class_set_template()
.
gtk_widget_class_set_template_scope ()
void gtk_widget_class_set_template_scope (GtkWidgetClass *widget_class
,GtkBuilderScope *scope
);
For use in language bindings, this will override the default GtkBuilderScope to be used when parsing GtkBuilder XML from this class’s template data.
Note that this must be called from a composite widget classes class
initializer after calling gtk_widget_class_set_template()
.
Parameters
widget_class |
||
scope |
The GtkBuilderScope to use when loading the class template. |
[transfer none] |
gtk_widget_observe_children ()
GListModel *
gtk_widget_observe_children (GtkWidget *widget
);
Returns a GListModel to track the children of widget
.
Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. It may slow down operations a lot.
Applications should try hard to avoid calling this function because of the slowdowns.
gtk_widget_observe_controllers ()
GListModel *
gtk_widget_observe_controllers (GtkWidget *widget
);
Returns a GListModel to track the GtkEventControllers of widget
.
Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. It may slow down operations a lot.
Applications should try hard to avoid calling this function because of the slowdowns.
gtk_widget_insert_action_group ()
void gtk_widget_insert_action_group (GtkWidget *widget
,const char *name
,GActionGroup *group
);
Inserts group
into widget
. Children of widget
that implement
GtkActionable can then be associated with actions in group
by
setting their “action-name” to prefix
.action-name
.
Note that inheritance is defined for individual actions. I.e.
even if you insert a group with prefix prefix
, actions with
the same prefix will still be inherited from the parent, unless
the group contains an action with the same name.
If group
is NULL
, a previously inserted group for name
is
removed from widget
.
gtk_widget_activate_action ()
gboolean gtk_widget_activate_action (GtkWidget *widget
,const char *name
,const char *format_string
,...
);
Looks up the action in the action groups associated
with widget
and its ancestors, and activates it.
This is a wrapper around gtk_widget_activate_action_variant()
that constructs the args
variant according to format_string
.
gtk_widget_activate_action_variant ()
gboolean gtk_widget_activate_action_variant (GtkWidget *widget
,const char *name
,GVariant *args
);
Looks up the action in the action groups associated
with widget
and its ancestors, and activates it.
If the action is in an action group added with
gtk_widget_insert_action_group()
, the name
is
expected to be prefixed with the prefix that was
used when the group was inserted.
The arguments must match the actions expected parameter
type, as returned by g_action_get_parameter_type()
.
[rename-to gtk_widget_activate_action]
gtk_widget_activate_default ()
void
gtk_widget_activate_default (GtkWidget *widget
);
Activate the default.activate action from widget
.
GtkWidgetActionActivateFunc ()
void (*GtkWidgetActionActivateFunc) (GtkWidget *widget
,const char *action_name
,GVariant *parameter
);
The type of the callback functions used for activating
actions installed with gtk_widget_class_install_action()
.
The parameter
must match the parameter_type
of the action.
gtk_widget_class_install_action ()
void gtk_widget_class_install_action (GtkWidgetClass *widget_class
,const char *action_name
,const char *parameter_type
,GtkWidgetActionActivateFunc activate
);
This should be called at class initialization time to specify actions to be added for all instances of this class.
Actions installed by this function are stateless. The only state they have is whether they are enabled or not.
gtk_widget_class_install_property_action ()
void gtk_widget_class_install_property_action (GtkWidgetClass *widget_class
,const char *action_name
,const char *property_name
);
Installs an action called action_name
on widget_class
and binds its
state to the value of the property_name
property.
This function will perform a few santity checks on the property selected
via property_name
. Namely, the property must exist, must be readable,
writable and must not be construct-only. There are also restrictions
on the type of the given property, it must be boolean, int, unsigned int,
double or string. If any of these conditions are not met, a critical
warning will be printed and no action will be added.
The state type of the action matches the property type.
If the property is boolean, the action will have no parameter and toggle the property value. Otherwise, the action will have a parameter of the same type as the property.
gtk_widget_class_query_action ()
gboolean gtk_widget_class_query_action (GtkWidgetClass *widget_class
,guint index_
,GType *owner
,const char **action_name
,const GVariantType **parameter_type
,const char **property_name
);
Queries the actions that have been installed for
a widget class using gtk_widget_class_install_action()
during class initialization.
Note that this function will also return actions defined
by parent classes. You can identify those by looking
at owner
.
Parameters
widget_class |
||
index_ |
position of the action to query |
|
owner |
return location for the type where the action was defined. |
[out] |
action_name |
return location for the action name. |
[out] |
parameter_type |
return location for the parameter type. |
[out] |
property_name |
return location for the property name. |
[out] |
gtk_widget_action_set_enabled ()
void gtk_widget_action_set_enabled (GtkWidget *widget
,const char *action_name
,gboolean enabled
);
Enable or disable an action installed with
gtk_widget_class_install_action()
.
Types and Values
struct GtkWidgetClass
struct GtkWidgetClass { GInitiallyUnownedClass parent_class; /* basics */ void (* show) (GtkWidget *widget); void (* hide) (GtkWidget *widget); void (* map) (GtkWidget *widget); void (* unmap) (GtkWidget *widget); void (* realize) (GtkWidget *widget); void (* unrealize) (GtkWidget *widget); void (* root) (GtkWidget *widget); void (* unroot) (GtkWidget *widget); void (* size_allocate) (GtkWidget *widget, int width, int height, int baseline); void (* state_flags_changed) (GtkWidget *widget, GtkStateFlags previous_state_flags); void (* direction_changed) (GtkWidget *widget, GtkTextDirection previous_direction); /* size requests */ GtkSizeRequestMode (* get_request_mode) (GtkWidget *widget); void (* measure) (GtkWidget *widget, GtkOrientation orientation, int for_size, int *minimum, int *natural, int *minimum_baseline, int *natural_baseline); /* Mnemonics */ gboolean (* mnemonic_activate) (GtkWidget *widget, gboolean group_cycling); /* explicit focus */ gboolean (* grab_focus) (GtkWidget *widget); gboolean (* focus) (GtkWidget *widget, GtkDirectionType direction); void (* set_focus_child) (GtkWidget *widget, GtkWidget *child); /* keyboard navigation */ void (* move_focus) (GtkWidget *widget, GtkDirectionType direction); gboolean (* keynav_failed) (GtkWidget *widget, GtkDirectionType direction); gboolean (* query_tooltip) (GtkWidget *widget, int x, int y, gboolean keyboard_tooltip, GtkTooltip *tooltip); void (* compute_expand) (GtkWidget *widget, gboolean *hexpand_p, gboolean *vexpand_p); void (* css_changed) (GtkWidget *widget, GtkCssStyleChange *change); void (* system_setting_changed) (GtkWidget *widget, GtkSystemSetting settings); void (* snapshot) (GtkWidget *widget, GtkSnapshot *snapshot); gboolean (* contains) (GtkWidget *widget, double x, double y); };
Members
Signal emitted when widget is shown |
||
Signal emitted when widget is hidden. |
||
Signal emitted when widget is going to be mapped, that is
when the widget is visible (which is controlled with
|
||
Signal emitted when widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden. |
||
Signal emitted when widget is associated with a
GdkSurface, which means that |
||
Signal emitted when the GdkSurface associated with
widget is destroyed, which means that |
||
Called when the widget gets added to a GtkRoot widget. Must chain up |
||
Called when the widget is about to be removed from its GtkRoot widget. Must chain up |
||
Called to set the allocation, if the widget does not have a layout manager. |
||
Signal emitted when the widget state changes,
see |
||
Signal emitted when the text direction of a widget changes. |
||
Called to get the request mode, if the widget
does not have a layout manager.
This allows a widget to tell its parent container whether
it prefers to be allocated in |
||
Called to obtain the minimum and natural size of the widget, if the widget does not have a layout manager. Depending on the orientation parameter, the passed for_size can be interpreted as width or height. A widget will never be allocated less than its minimum size. |
||
Activates the |
||
Causes |
||
Vfunc for |
||
Sets the focused child of a widget. Must chain up |
||
Signal emitted when a change of focus is requested |
||
Signal emitted if keyboard navigation fails. |
||
Signal emitted when “has-tooltip” is |
||
Computes whether a container should give this widget extra space when possible. |
||
Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up. |
||
Emitted when a system setting was changed. Must chain up. |
||
Vfunc called when a new snapshot of the widget has to be taken. |
||
Vfunc for |
GtkRequisition
typedef struct { int width; int height; } GtkRequisition;
A GtkRequisition represents the desired size of a widget. See GtkWidget’s geometry management section for more information.
GtkAllocation
typedef GdkRectangle GtkAllocation;
A GtkAllocation of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See GtkWidget’s geometry management section for more information.
enum GtkPickFlags
Flags that influence the behavior of gtk_widget_pick()
Members
The default behavior, include widgets that are receiving events |
||
Include widgets that are insensitive |
||
Include widgets that are marked as non-targetable. See “can-target” |
enum GtkOverflow
Defines how content overflowing a given area should be handled, such as
with gtk_widget_set_overflow()
. This property is modeled after the CSS overflow
property, but implements it only partially.
enum GtkSizeRequestMode
Specifies a preference for height-for-width or width-for-height geometry management.
struct GtkRequestedSize
struct GtkRequestedSize { gpointer data; int minimum_size; int natural_size; };
Represents a request of a screen object in a given orientation. These
are primarily used in container implementations when allocating a natural
size for children calling. See gtk_distribute_natural_allocation()
.
enum GtkAlign
Controls how a widget deals with extra space in a single (x or y) dimension.
Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the “hexpand” property inside a GtkBox, then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space.
Note that in horizontal context GTK_ALIGN_START
and GTK_ALIGN_END
are interpreted relative to text direction.
GTK_ALIGN_BASELINE
support is optional for containers and widgets, and
it is only supported for vertical alignment. When it's not supported by
a child or a container it is treated as GTK_ALIGN_FILL
.
Members
stretch to fill all space if possible, center if no meaningful way to stretch |
||
snap to left or top side, leaving space on right or bottom |
||
snap to right or bottom side, leaving space on left or top |
||
center natural width of widget inside the allocation |
||
align the widget according to the baseline. See GtkWidget |
Property Details
The “can-focus”
property
“can-focus” gboolean
Whether the widget or any of its descendents can accept the input focus.
This property is meant to be set by widget implementations, typically in their instance init function.
Owner: GtkWidget
Flags: Read / Write
Default value: TRUE
The “can-target”
property
“can-target” gboolean
Whether the widget can receive pointer events.
Owner: GtkWidget
Flags: Read / Write
Default value: TRUE
The “css-classes”
property
“css-classes” GStrv
A list of css classes applied to this widget.
Owner: GtkWidget
Flags: Read / Write
The “css-name”
property
“css-name” char *
The name of this widget in the CSS tree.
This property is meant to be set by widget implementations, typically in their instance init function.
Owner: GtkWidget
Flags: Read / Write / Construct Only
Default value: NULL
The “cursor”
property
“cursor” GdkCursor *
The cursor used by widget
. See gtk_widget_set_cursor()
for details.
Owner: GtkWidget
Flags: Read / Write
The “focus-on-click”
property
“focus-on-click” gboolean
Whether the widget should grab focus when it is clicked with the mouse.
This property is only relevant for widgets that can take focus.
Owner: GtkWidget
Flags: Read / Write
Default value: TRUE
The “focusable”
property
“focusable” gboolean
Whether this widget itself will accept the input focus.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “halign”
property
“halign” GtkAlign
How to distribute horizontal space if widget gets extra space, see GtkAlign
Owner: GtkWidget
Flags: Read / Write
Default value: GTK_ALIGN_FILL
The “has-default”
property
“has-default” gboolean
Whether the widget is the default widget.
Owner: GtkWidget
Flags: Read
Default value: FALSE
The “has-focus”
property
“has-focus” gboolean
Whether the widget has the input focus.
Owner: GtkWidget
Flags: Read
Default value: FALSE
The “has-tooltip”
property
“has-tooltip” gboolean
Enables or disables the emission of “query-tooltip” on widget
.
A value of TRUE
indicates that widget
can have a tooltip, in this case
the widget will be queried using “query-tooltip” to determine
whether it will provide a tooltip or not.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “height-request”
property
“height-request” int
Override for height request of the widget, or -1 if natural request should be used.
Owner: GtkWidget
Flags: Read / Write
Allowed values: >= -1
Default value: -1
The “hexpand”
property
“hexpand” gboolean
Whether to expand horizontally. See gtk_widget_set_hexpand()
.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “hexpand-set”
property
“hexpand-set” gboolean
Whether to use the “hexpand” property. See gtk_widget_get_hexpand_set()
.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “layout-manager”
property
“layout-manager” GtkLayoutManager *
The GtkLayoutManager instance to use to compute the preferred size of the widget, and allocate its children.
This property is meant to be set by widget implementations, typically in their instance init function.
Owner: GtkWidget
Flags: Read / Write
The “margin-bottom”
property
“margin-bottom” int
Margin on bottom side of widget.
This property adds margin outside of the widget's normal size
request, the margin will be added in addition to the size from
gtk_widget_set_size_request()
for example.
Owner: GtkWidget
Flags: Read / Write
Allowed values: [0,32767]
Default value: 0
The “margin-end”
property
“margin-end” int
Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions.
This property adds margin outside of the widget's normal size
request, the margin will be added in addition to the size from
gtk_widget_set_size_request()
for example.
Owner: GtkWidget
Flags: Read / Write
Allowed values: [0,32767]
Default value: 0
The “margin-start”
property
“margin-start” int
Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions.
This property adds margin outside of the widget's normal size
request, the margin will be added in addition to the size from
gtk_widget_set_size_request()
for example.
Owner: GtkWidget
Flags: Read / Write
Allowed values: [0,32767]
Default value: 0
The “margin-top”
property
“margin-top” int
Margin on top side of widget.
This property adds margin outside of the widget's normal size
request, the margin will be added in addition to the size from
gtk_widget_set_size_request()
for example.
Owner: GtkWidget
Flags: Read / Write
Allowed values: [0,32767]
Default value: 0
The “name”
property
“name” char *
The name of the widget.
Owner: GtkWidget
Flags: Read / Write
Default value: NULL
The “opacity”
property
“opacity” double
The requested opacity of the widget. See gtk_widget_set_opacity()
for
more details about window opacity.
Owner: GtkWidget
Flags: Read / Write
Allowed values: [0,1]
Default value: 1
The “overflow”
property
“overflow” GtkOverflow
How content outside the widget's content area is treated.
This property is meant to be set by widget implementations, typically in their instance init function.
Owner: GtkWidget
Flags: Read / Write
Default value: GTK_OVERFLOW_VISIBLE
The “parent”
property
“parent” GtkWidget *
The parent widget of this widget.
Owner: GtkWidget
Flags: Read
The “receives-default”
property
“receives-default” gboolean
If TRUE, the widget will receive the default action when it is focused.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “root”
property
“root” GtkRoot *
The GtkRoot widget of the widget tree containing this widget or NULL
if
the widget is not contained in a root widget.
Owner: GtkWidget
Flags: Read
The “scale-factor”
property
“scale-factor” int
The scale factor of the widget. See gtk_widget_get_scale_factor()
for
more details about widget scaling.
Owner: GtkWidget
Flags: Read
Allowed values: >= 1
Default value: 1
The “sensitive”
property
“sensitive” gboolean
Whether the widget responds to input.
Owner: GtkWidget
Flags: Read / Write
Default value: TRUE
The “tooltip-markup”
property
“tooltip-markup” char *
Sets the text of tooltip to be the given string, which is marked up
with the Pango text markup language.
Also see gtk_tooltip_set_markup()
.
This is a convenience property which will take care of getting the
tooltip shown if the given string is not NULL
: “has-tooltip”
will automatically be set to TRUE
and there will be taken care of
“query-tooltip” in the default signal handler.
Note that if both “tooltip-text” and “tooltip-markup” are set, the last one wins.
Owner: GtkWidget
Flags: Read / Write
Default value: NULL
The “tooltip-text”
property
“tooltip-text” char *
Sets the text of tooltip to be the given string.
Also see gtk_tooltip_set_text()
.
This is a convenience property which will take care of getting the
tooltip shown if the given string is not NULL
: “has-tooltip”
will automatically be set to TRUE
and there will be taken care of
“query-tooltip” in the default signal handler.
Note that if both “tooltip-text” and “tooltip-markup” are set, the last one wins.
Owner: GtkWidget
Flags: Read / Write
Default value: NULL
The “valign”
property
“valign” GtkAlign
How to distribute vertical space if widget gets extra space, see GtkAlign
Owner: GtkWidget
Flags: Read / Write
Default value: GTK_ALIGN_FILL
The “vexpand”
property
“vexpand” gboolean
Whether to expand vertically. See gtk_widget_set_vexpand()
.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “vexpand-set”
property
“vexpand-set” gboolean
Whether to use the “vexpand” property. See gtk_widget_get_vexpand_set()
.
Owner: GtkWidget
Flags: Read / Write
Default value: FALSE
The “visible”
property
“visible” gboolean
Whether the widget is visible.
Owner: GtkWidget
Flags: Read / Write
Default value: TRUE
Signal Details
The “destroy”
signal
void user_function (GtkWidget *object, gpointer user_data)
Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released.
This signal is not suitable for saving widget state.
Parameters
object |
the object which received the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: No Hooks
The “direction-changed”
signal
void user_function (GtkWidget *widget, GtkTextDirection previous_direction, gpointer user_data)
The ::direction-changed signal is emitted when the text direction of a widget changes.
Parameters
widget |
the object on which the signal is emitted |
|
previous_direction |
the previous text direction of |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “hide”
signal
void user_function (GtkWidget *widget, gpointer user_data)
The ::hide signal is emitted when widget
is hidden, for example with
gtk_widget_hide()
.
Parameters
widget |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “keynav-failed”
signal
gboolean user_function (GtkWidget *widget, GtkDirectionType direction, gpointer user_data)
Gets emitted if keyboard navigation fails.
See gtk_widget_keynav_failed()
for details.
Parameters
widget |
the object which received the signal |
|
direction |
the direction of movement |
|
user_data |
user data set when the signal handler was connected. |
Returns
TRUE
if stopping keyboard navigation is fine, FALSE
if the emitting widget should try to handle the keyboard
navigation attempt in its parent widget(s).
Flags: Run Last
The “map”
signal
void user_function (GtkWidget *widget, gpointer user_data)
The ::map signal is emitted when widget
is going to be mapped, that is
when the widget is visible (which is controlled with
gtk_widget_set_visible()
) and all its parents up to the toplevel widget
are also visible.
The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of “unmap”.
Parameters
widget |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “mnemonic-activate”
signal
gboolean user_function (GtkWidget *widget, gboolean group_cycling, gpointer user_data)
The default handler for this signal activates widget
if group_cycling
is FALSE
, or just makes widget
grab focus if group_cycling
is TRUE
.
Parameters
widget |
the object which received the signal. |
|
group_cycling |
|
|
user_data |
user data set when the signal handler was connected. |
Returns
TRUE
to stop other handlers from being invoked for the event.
FALSE
to propagate the event further.
Flags: Run Last
The “move-focus”
signal
void user_function (GtkWidget *widget, GtkDirectionType direction, gpointer user_data)
Emitted when the focus is moved.
Parameters
widget |
the object which received the signal. |
|
direction |
the direction of the focus move |
|
user_data |
user data set when the signal handler was connected. |
Flags: Action
The “query-tooltip”
signal
gboolean user_function (GtkWidget *widget, int x, int y, gboolean keyboard_mode, GtkTooltip *tooltip, gpointer user_data)
Emitted when “has-tooltip” is TRUE
and the hover timeout
has expired with the cursor hovering "above" widget
; or emitted when widget
got
focus in keyboard mode.
Using the given coordinates, the signal handler should determine
whether a tooltip should be shown for widget
. If this is the case
TRUE
should be returned, FALSE
otherwise. Note that if
keyboard_mode
is TRUE
, the values of x
and y
are undefined and
should not be used.
The signal handler is free to manipulate tooltip
with the therefore
destined function calls.
Parameters
widget |
the object which received the signal |
|
x |
the x coordinate of the cursor position where the request has
been emitted, relative to |
|
y |
the y coordinate of the cursor position where the request has
been emitted, relative to |
|
keyboard_mode |
|
|
tooltip |
||
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “realize”
signal
void user_function (GtkWidget *widget, gpointer user_data)
The ::realize signal is emitted when widget
is associated with a
GdkSurface, which means that gtk_widget_realize()
has been called or the
widget has been mapped (that is, it is going to be drawn).
Parameters
widget |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “show”
signal
void user_function (GtkWidget *widget, gpointer user_data)
The ::show signal is emitted when widget
is shown, for example with
gtk_widget_show()
.
Parameters
widget |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “state-flags-changed”
signal
void user_function (GtkWidget *widget, GtkStateFlags flags, gpointer user_data)
The ::state-flags-changed signal is emitted when the widget state
changes, see gtk_widget_get_state_flags()
.
Parameters
widget |
the object which received the signal. |
|
flags |
The previous state flags. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “unmap”
signal
void user_function (GtkWidget *widget, gpointer user_data)
The ::unmap signal is emitted when widget
is going to be unmapped, which
means that either it or any of its parents up to the toplevel widget have
been set as hidden.
As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.
Parameters
widget |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “unrealize”
signal
void user_function (GtkWidget *widget, gpointer user_data)
The ::unrealize signal is emitted when the GdkSurface associated with
widget
is destroyed, which means that gtk_widget_unrealize()
has been
called or the widget has been unmapped (that is, it is going to be
hidden).
Parameters
widget |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last