<!-- file * -->
<!-- struct AboutDialog -->
The `AboutDialog` offers a simple way to display information about
a program like its logo, name, copyright, website and license. It is
also possible to give credits to the authors, documenters, translators
and artists who have worked on the program. An about dialog is typically
opened when the user selects the `About` option from the `Help` menu.
All parts of the dialog are optional.

About dialogs often contain links and email addresses. `AboutDialog`
displays these as clickable links. By default, it calls `gtk_show_uri_on_window`
when a user clicks one. The behaviour can be overridden with the
`AboutDialog::activate-link` signal.

To specify a person with an email address, use a string like
"Edgar Allan Poe <edgar\@poe.com>". To specify a website with a title,
use a string like "GTK+ team http://www.gtk.org".

To make constructing a `AboutDialog` as convenient as possible, you can
use the function `gtk_show_about_dialog` which constructs and shows a dialog
and keeps it around so that it can be shown again.

Note that GTK+ sets a default title of `_("About %s")` on the dialog
window (where \%s is replaced by the name of the application, but in
order to ensure proper translation of the title, applications should
set the title property explicitly when constructing a `AboutDialog`,
as shown in the following example:

```C
GdkPixbuf *example_logo = gdk_pixbuf_new_from_file ("./logo.png", NULL);
gtk_show_about_dialog (NULL,
                       "program-name", "ExampleCode",
                       "logo", example_logo,
                       "title", _("About ExampleCode"),
                       NULL);
```

It is also possible to show a `AboutDialog` like any other `Dialog`,
e.g. using `DialogExt::run`. In this case, you might need to know that
the “Close” button returns the `ResponseType::Cancel` response id.

# Implements

[`AboutDialogExt`](trait.AboutDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AboutDialogExt -->
Trait containing all `AboutDialog` methods.

# Implementors

[`AboutDialog`](struct.AboutDialog.html)
<!-- impl AboutDialog::fn new -->
Creates a new `AboutDialog`.

# Returns

a newly created `AboutDialog`
<!-- trait AboutDialogExt::fn add_credit_section -->
Creates a new section in the Credits page.
## `section_name`
The name of the section
## `people`
The people who belong to that section
<!-- trait AboutDialogExt::fn get_artists -->
Returns the string which are displayed in the artists tab
of the secondary credits dialog.

# Returns

A
 `None`-terminated string array containing the artists. The array is
 owned by the about dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_authors -->
Returns the string which are displayed in the authors tab
of the secondary credits dialog.

# Returns

A
 `None`-terminated string array containing the authors. The array is
 owned by the about dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_comments -->
Returns the comments string.

# Returns

The comments. The string is owned by the about
 dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_copyright -->
Returns the copyright string.

# Returns

The copyright string. The string is owned by the about
 dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_documenters -->
Returns the string which are displayed in the documenters
tab of the secondary credits dialog.

# Returns

A
 `None`-terminated string array containing the documenters. The
 array is owned by the about dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_license -->
Returns the license information.

# Returns

The license information. The string is owned by the about
 dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_license_type -->
Retrieves the license set using `AboutDialogExt::set_license_type`

# Returns

a `License` value
<!-- trait AboutDialogExt::fn get_logo -->
Returns the pixbuf displayed as logo in the about dialog.

# Returns

the pixbuf displayed as logo. The
 pixbuf is owned by the about dialog. If you want to keep a
 reference to it, you have to call `gobject::ObjectExt::ref` on it.
<!-- trait AboutDialogExt::fn get_logo_icon_name -->
Returns the icon name displayed as logo in the about dialog.

# Returns

the icon name displayed as logo. The string is
 owned by the dialog. If you want to keep a reference
 to it, you have to call `g_strdup` on it.
<!-- trait AboutDialogExt::fn get_program_name -->
Returns the program name displayed in the about dialog.

# Returns

The program name. The string is owned by the about
 dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_translator_credits -->
Returns the translator credits string which is displayed
in the translators tab of the secondary credits dialog.

# Returns

The translator credits string. The string is
 owned by the about dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_version -->
Returns the version string.

# Returns

The version string. The string is owned by the about
 dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_website -->
Returns the website URL.

# Returns

The website URL. The string is owned by the about
 dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_website_label -->
Returns the label used for the website link.

# Returns

The label used for the website link. The string is
 owned by the about dialog and must not be modified.
<!-- trait AboutDialogExt::fn get_wrap_license -->
Returns whether the license text in `self` is
automatically wrapped.

# Returns

`true` if the license text is wrapped
<!-- trait AboutDialogExt::fn set_artists -->
Sets the strings which are displayed in the artists tab
of the secondary credits dialog.
## `artists`
a `None`-terminated array of strings
<!-- trait AboutDialogExt::fn set_authors -->
Sets the strings which are displayed in the authors tab
of the secondary credits dialog.
## `authors`
a `None`-terminated array of strings
<!-- trait AboutDialogExt::fn set_comments -->
Sets the comments string to display in the about dialog.
This should be a short string of one or two lines.
## `comments`
a comments string
<!-- trait AboutDialogExt::fn set_copyright -->
Sets the copyright string to display in the about dialog.
This should be a short string of one or two lines.
## `copyright`
the copyright string
<!-- trait AboutDialogExt::fn set_documenters -->
Sets the strings which are displayed in the documenters tab
of the secondary credits dialog.
## `documenters`
a `None`-terminated array of strings
<!-- trait AboutDialogExt::fn set_license -->
Sets the license information to be displayed in the secondary
license dialog. If `license` is `None`, the license button is
hidden.
## `license`
the license information or `None`
<!-- trait AboutDialogExt::fn set_license_type -->
Sets the license of the application showing the `self` dialog from a
list of known licenses.

This function overrides the license set using
`AboutDialogExt::set_license`.
## `license_type`
the type of license
<!-- trait AboutDialogExt::fn set_logo -->
Sets the pixbuf to be displayed as logo in the about dialog.
If it is `None`, the default window icon set with
`Window::set_default_icon` will be used.
## `logo`
a `gdk_pixbuf::Pixbuf`, or `None`
<!-- trait AboutDialogExt::fn set_logo_icon_name -->
Sets the pixbuf to be displayed as logo in the about dialog.
If it is `None`, the default window icon set with
`Window::set_default_icon` will be used.
## `icon_name`
an icon name, or `None`
<!-- trait AboutDialogExt::fn set_program_name -->
Sets the name to display in the about dialog.
If this is not set, it defaults to `g_get_application_name`.
## `name`
the program name
<!-- trait AboutDialogExt::fn set_translator_credits -->
Sets the translator credits string which is displayed in
the translators tab of the secondary credits dialog.

The intended use for this string is to display the translator
of the language which is currently used in the user interface.
Using `gettext`, a simple way to achieve that is to mark the
string for translation:

```C
GtkWidget *about = gtk_about_dialog_new ();
gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about),
                                         _("translator-credits"));
```
It is a good idea to use the customary msgid “translator-credits” for this
purpose, since translators will already know the purpose of that msgid, and
since `AboutDialog` will detect if “translator-credits” is untranslated
and hide the tab.
## `translator_credits`
the translator credits
<!-- trait AboutDialogExt::fn set_version -->
Sets the version string to display in the about dialog.
## `version`
the version string
<!-- trait AboutDialogExt::fn set_website -->
Sets the URL to use for the website link.
## `website`
a URL string starting with "http://"
<!-- trait AboutDialogExt::fn set_website_label -->
Sets the label to be used for the website link.
## `website_label`
the label used for the website link
<!-- trait AboutDialogExt::fn set_wrap_license -->
Sets whether the license text in `self` is
automatically wrapped.
## `wrap_license`
whether to wrap the license
<!-- trait AboutDialogExt::fn connect_activate_link -->
The signal which gets emitted to activate a URI.
Applications may connect to it to override the default behaviour,
which is to call `gtk_show_uri_on_window`.
## `uri`
the URI that is activated

# Returns

`true` if the link has been activated
<!-- trait AboutDialogExt::fn get_property_artists -->
The people who contributed artwork to the program, as a `None`-terminated
array of strings. Each string may contain email addresses and URLs, which
will be displayed as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn set_property_artists -->
The people who contributed artwork to the program, as a `None`-terminated
array of strings. Each string may contain email addresses and URLs, which
will be displayed as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn get_property_authors -->
The authors of the program, as a `None`-terminated array of strings.
Each string may contain email addresses and URLs, which will be displayed
as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn set_property_authors -->
The authors of the program, as a `None`-terminated array of strings.
Each string may contain email addresses and URLs, which will be displayed
as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn get_property_comments -->
Comments about the program. This string is displayed in a label
in the main dialog, thus it should be a short explanation of
the main purpose of the program, not a detailed list of features.
<!-- trait AboutDialogExt::fn set_property_comments -->
Comments about the program. This string is displayed in a label
in the main dialog, thus it should be a short explanation of
the main purpose of the program, not a detailed list of features.
<!-- trait AboutDialogExt::fn get_property_copyright -->
Copyright information for the program.
<!-- trait AboutDialogExt::fn set_property_copyright -->
Copyright information for the program.
<!-- trait AboutDialogExt::fn get_property_documenters -->
The people documenting the program, as a `None`-terminated array of strings.
Each string may contain email addresses and URLs, which will be displayed
as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn set_property_documenters -->
The people documenting the program, as a `None`-terminated array of strings.
Each string may contain email addresses and URLs, which will be displayed
as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn get_property_license -->
The license of the program. This string is displayed in a
text view in a secondary dialog, therefore it is fine to use
a long multi-paragraph text. Note that the text is only wrapped
in the text view if the "wrap-license" property is set to `true`;
otherwise the text itself must contain the intended linebreaks.
When setting this property to a non-`None` value, the
`AboutDialog:license-type` property is set to `License::Custom`
as a side effect.
<!-- trait AboutDialogExt::fn set_property_license -->
The license of the program. This string is displayed in a
text view in a secondary dialog, therefore it is fine to use
a long multi-paragraph text. Note that the text is only wrapped
in the text view if the "wrap-license" property is set to `true`;
otherwise the text itself must contain the intended linebreaks.
When setting this property to a non-`None` value, the
`AboutDialog:license-type` property is set to `License::Custom`
as a side effect.
<!-- trait AboutDialogExt::fn get_property_license_type -->
The license of the program, as a value of the `License` enumeration.

The `AboutDialog` will automatically fill out a standard disclaimer
and link the user to the appropriate online resource for the license
text.

If `License::Unknown` is used, the link used will be the same
specified in the `AboutDialog:website` property.

If `License::Custom` is used, the current contents of the
`AboutDialog:license` property are used.

For any other `License` value, the contents of the
`AboutDialog:license` property are also set by this property as
a side effect.
<!-- trait AboutDialogExt::fn set_property_license_type -->
The license of the program, as a value of the `License` enumeration.

The `AboutDialog` will automatically fill out a standard disclaimer
and link the user to the appropriate online resource for the license
text.

If `License::Unknown` is used, the link used will be the same
specified in the `AboutDialog:website` property.

If `License::Custom` is used, the current contents of the
`AboutDialog:license` property are used.

For any other `License` value, the contents of the
`AboutDialog:license` property are also set by this property as
a side effect.
<!-- trait AboutDialogExt::fn get_property_logo -->
A logo for the about box. If it is `None`, the default window icon
set with `Window::set_default_icon` will be used.
<!-- trait AboutDialogExt::fn set_property_logo -->
A logo for the about box. If it is `None`, the default window icon
set with `Window::set_default_icon` will be used.
<!-- trait AboutDialogExt::fn get_property_logo_icon_name -->
A named icon to use as the logo for the about box. This property
overrides the `AboutDialog:logo` property.
<!-- trait AboutDialogExt::fn set_property_logo_icon_name -->
A named icon to use as the logo for the about box. This property
overrides the `AboutDialog:logo` property.
<!-- trait AboutDialogExt::fn get_property_program_name -->
The name of the program.
If this is not set, it defaults to `g_get_application_name`.
<!-- trait AboutDialogExt::fn set_property_program_name -->
The name of the program.
If this is not set, it defaults to `g_get_application_name`.
<!-- trait AboutDialogExt::fn get_property_translator_credits -->
Credits to the translators. This string should be marked as translatable.
The string may contain email addresses and URLs, which will be displayed
as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn set_property_translator_credits -->
Credits to the translators. This string should be marked as translatable.
The string may contain email addresses and URLs, which will be displayed
as links, see the introduction for more details.
<!-- trait AboutDialogExt::fn get_property_version -->
The version of the program.
<!-- trait AboutDialogExt::fn set_property_version -->
The version of the program.
<!-- trait AboutDialogExt::fn get_property_website -->
The URL for the link to the website of the program.
This should be a string starting with "http://.
<!-- trait AboutDialogExt::fn set_property_website -->
The URL for the link to the website of the program.
This should be a string starting with "http://.
<!-- trait AboutDialogExt::fn get_property_website_label -->
The label for the link to the website of the program.
<!-- trait AboutDialogExt::fn set_property_website_label -->
The label for the link to the website of the program.
<!-- trait AboutDialogExt::fn get_property_wrap_license -->
Whether to wrap the text in the license dialog.
<!-- trait AboutDialogExt::fn set_property_wrap_license -->
Whether to wrap the text in the license dialog.
<!-- struct AccelFlags -->
Accelerator flags used with `AccelGroup::connect`.
<!-- struct AccelFlags::const VISIBLE -->
Accelerator is visible
<!-- struct AccelFlags::const LOCKED -->
Accelerator not removable
<!-- struct AccelFlags::const MASK -->
Mask
<!-- struct AccelGroup -->
A `AccelGroup` represents a group of keyboard accelerators,
typically attached to a toplevel `Window` (with
`GtkWindowExt::add_accel_group`). Usually you won’t need to create a
`AccelGroup` directly; instead, when using `UIManager`, GTK+
automatically sets up the accelerators for your menus in the ui
manager’s `AccelGroup`.

Note that “accelerators” are different from
“mnemonics”. Accelerators are shortcuts for
activating a menu item; they appear alongside the menu item they’re a
shortcut for. For example “Ctrl+Q” might appear alongside the “Quit”
menu item. Mnemonics are shortcuts for GUI elements such as text
entries or buttons; they appear as underlined characters. See
`Label::new_with_mnemonic`. Menu items can have both accelerators
and mnemonics, of course.

# Implements

[`AccelGroupExt`](trait.AccelGroupExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AccelGroupExtManual`](prelude/trait.AccelGroupExtManual.html)
<!-- trait AccelGroupExt -->
Trait containing all `AccelGroup` methods.

# Implementors

[`AccelGroup`](struct.AccelGroup.html)
<!-- impl AccelGroup::fn new -->
Creates a new `AccelGroup`.

# Returns

a new `AccelGroup` object
<!-- impl AccelGroup::fn from_accel_closure -->
Finds the `AccelGroup` to which `closure` is connected;
see `AccelGroup::connect`.
## `closure`
a `gobject::Closure`

# Returns

the `AccelGroup` to which `closure`
 is connected, or `None`
<!-- trait AccelGroupExt::fn activate -->
Finds the first accelerator in `self` that matches
`accel_key` and `accel_mods`, and activates it.
## `accel_quark`
the quark for the accelerator name
## `acceleratable`
the `gobject::Object`, usually a `Window`, on which
 to activate the accelerator
## `accel_key`
accelerator keyval from a key event
## `accel_mods`
keyboard state mask from a key event

# Returns

`true` if an accelerator was activated and handled
 this keypress
<!-- trait AccelGroupExt::fn connect -->
Installs an accelerator in this group. When `self` is being
activated in response to a call to `gtk_accel_groups_activate`,
`closure` will be invoked if the `accel_key` and `accel_mods` from
`gtk_accel_groups_activate` match those of this connection.

The signature used for the `closure` is that of ``GtkAccelGroupActivate``.

Note that, due to implementation details, a single closure can
only be connected to one accelerator group.
## `accel_key`
key value of the accelerator
## `accel_mods`
modifier combination of the accelerator
## `accel_flags`
a flag mask to configure this accelerator
## `closure`
closure to be executed upon accelerator activation
<!-- trait AccelGroupExt::fn connect_by_path -->
Installs an accelerator in this group, using an accelerator path
to look up the appropriate key and modifiers (see
`AccelMap::add_entry`). When `self` is being activated
in response to a call to `gtk_accel_groups_activate`, `closure` will
be invoked if the `accel_key` and `accel_mods` from
`gtk_accel_groups_activate` match the key and modifiers for the path.

The signature used for the `closure` is that of ``GtkAccelGroupActivate``.

Note that `accel_path` string will be stored in a `glib::Quark`. Therefore,
if you pass a static string, you can save some memory by interning it
first with `g_intern_static_string`.
## `accel_path`
path used for determining key and modifiers
## `closure`
closure to be executed upon accelerator activation
<!-- trait AccelGroupExt::fn disconnect -->
Removes an accelerator previously installed through
`AccelGroup::connect`.

Since 2.20 `closure` can be `None`.
## `closure`
the closure to remove from this accelerator
 group, or `None` to remove all closures

# Returns

`true` if the closure was found and got disconnected
<!-- trait AccelGroupExt::fn disconnect_key -->
Removes an accelerator previously installed through
`AccelGroup::connect`.
## `accel_key`
key value of the accelerator
## `accel_mods`
modifier combination of the accelerator

# Returns

`true` if there was an accelerator which could be
 removed, `false` otherwise
<!-- trait AccelGroupExt::fn find -->
Finds the first entry in an accelerator group for which
`find_func` returns `true` and returns its `AccelKey`.
## `find_func`
a function to filter the entries
 of `self` with
## `data`
data to pass to `find_func`

# Returns

the key of the first entry passing
 `find_func`. The key is owned by GTK+ and must not be freed.
<!-- trait AccelGroupExt::fn get_is_locked -->
Locks are added and removed using `AccelGroupExt::lock` and
`AccelGroupExt::unlock`.

# Returns

`true` if there are 1 or more locks on the `self`,
 `false` otherwise.
<!-- trait AccelGroupExt::fn get_modifier_mask -->
Gets a `gdk::ModifierType` representing the mask for this
`self`. For example, `gdk::ModifierType::ControlMask`, `gdk::ModifierType::ShiftMask`, etc.

# Returns

the modifier mask for this accel group.
<!-- trait AccelGroupExt::fn lock -->
Locks the given accelerator group.

Locking an acelerator group prevents the accelerators contained
within it to be changed during runtime. Refer to
`AccelMap::change_entry` about runtime accelerator changes.

If called more than once, `self` remains locked until
`AccelGroupExt::unlock` has been called an equivalent number
of times.
<!-- trait AccelGroupExt::fn query -->
Queries an accelerator group for all entries matching `accel_key`
and `accel_mods`.
## `accel_key`
key value of the accelerator
## `accel_mods`
modifier combination of the accelerator
## `n_entries`
location to return the number
 of entries found, or `None`

# Returns

an array of
 `n_entries` `AccelGroupEntry` elements, or `None`. The array
 is owned by GTK+ and must not be freed.
<!-- trait AccelGroupExt::fn unlock -->
Undoes the last call to `AccelGroupExt::lock` on this `self`.
<!-- trait AccelGroupExt::fn connect_accel_activate -->
The accel-activate signal is an implementation detail of
`AccelGroup` and not meant to be used by applications.
## `acceleratable`
the object on which the accelerator was activated
## `keyval`
the accelerator keyval
## `modifier`
the modifier combination of the accelerator

# Returns

`true` if the accelerator was activated
<!-- trait AccelGroupExt::fn connect_accel_changed -->
The accel-changed signal is emitted when an entry
is added to or removed from the accel group.

Widgets like `AccelLabel` which display an associated
accelerator should connect to this signal, and rebuild
their visual representation if the `accel_closure` is theirs.
## `keyval`
the accelerator keyval
## `modifier`
the modifier combination of the accelerator
## `accel_closure`
the `gobject::Closure` of the accelerator
<!-- struct AccelLabel -->
The `AccelLabel` widget is a subclass of `Label` that also displays an
accelerator key on the right of the label text, e.g. “Ctrl+S”.
It is commonly used in menus to show the keyboard short-cuts for commands.

The accelerator key to display is typically not set explicitly (although it
can be, with `AccelLabelExt::set_accel`). Instead, the `AccelLabel` displays
the accelerators which have been added to a particular widget. This widget is
set by calling `AccelLabelExt::set_accel_widget`.

For example, a `MenuItem` widget may have an accelerator added to emit
the “activate” signal when the “Ctrl+S” key combination is pressed.
A `AccelLabel` is created and added to the `MenuItem`, and
`AccelLabelExt::set_accel_widget` is called with the `MenuItem` as the
second argument. The `AccelLabel` will now display “Ctrl+S” after its label.

Note that creating a `MenuItem` with `MenuItem::new_with_label` (or
one of the similar functions for `CheckMenuItem` and `RadioMenuItem`)
automatically adds a `AccelLabel` to the `MenuItem` and calls
`AccelLabelExt::set_accel_widget` to set it up for you.

A `AccelLabel` will only display accelerators which have `AccelFlags::Visible`
set (see `AccelFlags`).
A `AccelLabel` can display multiple accelerators and even signal names,
though it is almost always used to display just one accelerator key.

## Creating a simple menu item with an accelerator key.


```C
  GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  GtkWidget *menu = gtk_menu_new ();
  GtkWidget *save_item;
  GtkAccelGroup *accel_group;

  // Create a GtkAccelGroup and add it to the window.
  accel_group = gtk_accel_group_new ();
  gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);

  // Create the menu item using the convenience function.
  save_item = gtk_menu_item_new_with_label ("Save");
  gtk_widget_show (save_item);
  gtk_container_add (GTK_CONTAINER (menu), save_item);

  // Now add the accelerator to the GtkMenuItem. Note that since we
  // called gtk_menu_item_new_with_label() to create the GtkMenuItem
  // the GtkAccelLabel is automatically set up to display the
  // GtkMenuItem accelerators. We just need to make sure we use
  // GTK_ACCEL_VISIBLE here.
  gtk_widget_add_accelerator (save_item, "activate", accel_group,
                              GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
```

# CSS nodes


```plain
label
╰── accelerator
```

Like `Label`, `AccelLabel` has a main CSS node with the name label.
It adds a subnode with name accelerator.

# Implements

[`AccelLabelExt`](trait.AccelLabelExt.html), [`LabelExt`](trait.LabelExt.html), [`MiscExt`](trait.MiscExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AccelLabelExt -->
Trait containing all `AccelLabel` methods.

# Implementors

[`AccelLabel`](struct.AccelLabel.html)
<!-- impl AccelLabel::fn new -->
Creates a new `AccelLabel`.
## `string`
the label string. Must be non-`None`.

# Returns

a new `AccelLabel`.
<!-- trait AccelLabelExt::fn get_accel -->
Gets the keyval and modifier mask set with
`AccelLabelExt::set_accel`.
## `accelerator_key`
return location for the keyval
## `accelerator_mods`
return location for the modifier mask
<!-- trait AccelLabelExt::fn get_accel_widget -->
Fetches the widget monitored by this accelerator label. See
`AccelLabelExt::set_accel_widget`.

# Returns

the object monitored by the accelerator label, or `None`.
<!-- trait AccelLabelExt::fn get_accel_width -->
Returns the width needed to display the accelerator key(s).
This is used by menus to align all of the `MenuItem` widgets, and shouldn't
be needed by applications.

# Returns

the width needed to display the accelerator key(s).
<!-- trait AccelLabelExt::fn refetch -->
Recreates the string representing the accelerator keys.
This should not be needed since the string is automatically updated whenever
accelerators are added or removed from the associated widget.

# Returns

always returns `false`.
<!-- trait AccelLabelExt::fn set_accel -->
Manually sets a keyval and modifier mask as the accelerator rendered
by `self`.

If a keyval and modifier are explicitly set then these values are
used regardless of any associated accel closure or widget.

Providing an `accelerator_key` of 0 removes the manual setting.
## `accelerator_key`
a keyval, or 0
## `accelerator_mods`
the modifier mask for the accel
<!-- trait AccelLabelExt::fn set_accel_closure -->
Sets the closure to be monitored by this accelerator label. The closure
must be connected to an accelerator group; see `AccelGroup::connect`.
Passing `None` for `accel_closure` will dissociate `self` from its
current closure, if any.
## `accel_closure`
the closure to monitor for accelerator changes,
or `None`
<!-- trait AccelLabelExt::fn set_accel_widget -->
Sets the widget to be monitored by this accelerator label. Passing `None` for
`accel_widget` will dissociate `self` from its current widget, if any.
## `accel_widget`
the widget to be monitored, or `None`
<!-- struct ActionBar -->
`ActionBar` is designed to present contextual actions. It is
expected to be displayed below the content and expand horizontally
to fill the area.

It allows placing children at the start or the end. In addition, it
contains an internal centered box which is centered with respect to
the full width of the box, even if the children at either side take
up different amounts of space.

# CSS nodes

`ActionBar` has a single CSS node with name actionbar.

# Implements

[`ActionBarExt`](trait.ActionBarExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ActionBarExt -->
Trait containing all `ActionBar` methods.

# Implementors

[`ActionBar`](struct.ActionBar.html)
<!-- impl ActionBar::fn new -->
Creates a new `ActionBar` widget.

# Returns

a new `ActionBar`
<!-- trait ActionBarExt::fn get_center_widget -->
Retrieves the center bar widget of the bar.

# Returns

the center `Widget` or `None`.
<!-- trait ActionBarExt::fn pack_end -->
Adds `child` to `self`, packed with reference to the
end of the `self`.
## `child`
the `Widget` to be added to `self`
<!-- trait ActionBarExt::fn pack_start -->
Adds `child` to `self`, packed with reference to the
start of the `self`.
## `child`
the `Widget` to be added to `self`
<!-- trait ActionBarExt::fn set_center_widget -->
Sets the center widget for the `ActionBar`.
## `center_widget`
a widget to use for the center
<!-- struct Actionable -->
This interface provides a convenient way of associating widgets with
actions on a `ApplicationWindow` or `Application`.

It primarily consists of two properties: `Actionable:action-name`
and `Actionable:action-target`. There are also some convenience APIs
for setting these properties.

The action will be looked up in action groups that are found among
the widgets ancestors. Most commonly, these will be the actions with
the “win.” or “app.” prefix that are associated with the `ApplicationWindow`
or `Application`, but other action groups that are added with
`WidgetExt::insert_action_group` will be consulted as well.

# Implements

[`ActionableExt`](trait.ActionableExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ActionableExt -->
Trait containing all `Actionable` methods.

# Implementors

[`Actionable`](struct.Actionable.html), [`Button`](struct.Button.html), [`CheckButton`](struct.CheckButton.html), [`CheckMenuItem`](struct.CheckMenuItem.html), [`ColorButton`](struct.ColorButton.html), [`FontButton`](struct.FontButton.html), [`LinkButton`](struct.LinkButton.html), [`ListBoxRow`](struct.ListBoxRow.html), [`LockButton`](struct.LockButton.html), [`MenuButton`](struct.MenuButton.html), [`MenuItem`](struct.MenuItem.html), [`MenuToolButton`](struct.MenuToolButton.html), [`ModelButton`](struct.ModelButton.html), [`RadioButton`](struct.RadioButton.html), [`RadioMenuItem`](struct.RadioMenuItem.html), [`RadioToolButton`](struct.RadioToolButton.html), [`ScaleButton`](struct.ScaleButton.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html), [`Switch`](struct.Switch.html), [`ToggleButton`](struct.ToggleButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html), [`VolumeButton`](struct.VolumeButton.html)
<!-- trait ActionableExt::fn get_action_name -->
Gets the action name for `self`.

See `Actionable::set_action_name` for more information.

# Returns

the action name, or `None` if none is set
<!-- trait ActionableExt::fn get_action_target_value -->
Gets the current target value of `self`.

See `Actionable::set_action_target_value` for more information.

# Returns

the current target value
<!-- trait ActionableExt::fn set_action_name -->
Specifies the name of the action with which this widget should be
associated. If `action_name` is `None` then the widget will be
unassociated from any previous action.

Usually this function is used when the widget is located (or will be
located) within the hierarchy of a `ApplicationWindow`.

Names are of the form “win.save” or “app.quit” for actions on the
containing `ApplicationWindow` or its associated `Application`,
respectively. This is the same form used for actions in the `gio::Menu`
associated with the window.
## `action_name`
an action name, or `None`
<!-- trait ActionableExt::fn set_action_target -->
Sets the target of an actionable widget.

This is a convenience function that calls `glib::Variant::new` for
`format_string` and uses the result to call
`Actionable::set_action_target_value`.

If you are setting a string-valued target and want to set the action
name at the same time, you can use
gtk_actionable_set_detailed_action_name ().
## `format_string`
a GVariant format string
<!-- trait ActionableExt::fn set_action_target_value -->
Sets the target value of an actionable widget.

If `target_value` is `None` then the target value is unset.

The target value has two purposes. First, it is used as the
parameter to activation of the action associated with the
`Actionable` widget. Second, it is used to determine if the widget
should be rendered as “active” — the widget is active if the state
is equal to the given target.

Consider the example of associating a set of buttons with a `gio::Action`
with string state in a typical “radio button” situation. Each button
will be associated with the same action, but with a different target
value for that action. Clicking on a particular button will activate
the action with the target of that button, which will typically cause
the action’s state to change to that value. Since the action’s state
is now equal to the target value of the button, the button will now
be rendered as active (and the other buttons, with different targets,
rendered inactive).
## `target_value`
a `glib::Variant` to set as the target value, or `None`
<!-- trait ActionableExt::fn set_detailed_action_name -->
Sets the action-name and associated string target value of an
actionable widget.

`detailed_action_name` is a string in the format accepted by
`gio::Action::parse_detailed_name`.

(Note that prior to version 3.22.25,
this function is only usable for actions with a simple "s" target, and
`detailed_action_name` must be of the form `"action::target"` where
`action` is the action name and `target` is the string to use
as the target.)
## `detailed_action_name`
the detailed action name
<!-- struct Adjustment -->
The `Adjustment` object represents a value which has an associated lower
and upper bound, together with step and page increments, and a page size.
It is used within several GTK+ widgets, including `SpinButton`, `Viewport`,
and `Range` (which is a base class for `Scrollbar` and `Scale`).

The `Adjustment` object does not update the value itself. Instead
it is left up to the owner of the `Adjustment` to control the value.

# Implements

[`AdjustmentExt`](trait.AdjustmentExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait AdjustmentExt -->
Trait containing all `Adjustment` methods.

# Implementors

[`Adjustment`](struct.Adjustment.html)
<!-- impl Adjustment::fn new -->
Creates a new `Adjustment`.
## `value`
the initial value
## `lower`
the minimum value
## `upper`
the maximum value
## `step_increment`
the step increment
## `page_increment`
the page increment
## `page_size`
the page size

# Returns

a new `Adjustment`
<!-- trait AdjustmentExt::fn changed -->
Emits a `Adjustment::changed` signal from the `Adjustment`.
This is typically called by the owner of the `Adjustment` after it has
changed any of the `Adjustment` properties other than the value.

# Deprecated since 3.18

GTK+ emits `Adjustment::changed` itself whenever any
 of the properties (other than value) change
<!-- trait AdjustmentExt::fn clamp_page -->
Updates the `Adjustment:value` property to ensure that the range
between `lower` and `upper` is in the current page (i.e. between
`Adjustment:value` and `Adjustment:value` + `Adjustment:page-size`).
If the range is larger than the page size, then only the start of it will
be in the current page.

A `Adjustment::value-changed` signal will be emitted if the value is changed.
## `lower`
the lower value
## `upper`
the upper value
<!-- trait AdjustmentExt::fn configure -->
Sets all properties of the adjustment at once.

Use this function to avoid multiple emissions of the
`Adjustment::changed` signal. See `AdjustmentExt::set_lower`
for an alternative way of compressing multiple emissions of
`Adjustment::changed` into one.
## `value`
the new value
## `lower`
the new minimum value
## `upper`
the new maximum value
## `step_increment`
the new step increment
## `page_increment`
the new page increment
## `page_size`
the new page size
<!-- trait AdjustmentExt::fn get_lower -->
Retrieves the minimum value of the adjustment.

# Returns

The current minimum value of the adjustment
<!-- trait AdjustmentExt::fn get_minimum_increment -->
Gets the smaller of step increment and page increment.

# Returns

the minimum increment of `self`
<!-- trait AdjustmentExt::fn get_page_increment -->
Retrieves the page increment of the adjustment.

# Returns

The current page increment of the adjustment
<!-- trait AdjustmentExt::fn get_page_size -->
Retrieves the page size of the adjustment.

# Returns

The current page size of the adjustment
<!-- trait AdjustmentExt::fn get_step_increment -->
Retrieves the step increment of the adjustment.

# Returns

The current step increment of the adjustment.
<!-- trait AdjustmentExt::fn get_upper -->
Retrieves the maximum value of the adjustment.

# Returns

The current maximum value of the adjustment
<!-- trait AdjustmentExt::fn get_value -->
Gets the current value of the adjustment.
See `AdjustmentExt::set_value`.

# Returns

The current value of the adjustment
<!-- trait AdjustmentExt::fn set_lower -->
Sets the minimum value of the adjustment.

When setting multiple adjustment properties via their individual
setters, multiple `Adjustment::changed` signals will be emitted.
However, since the emission of the `Adjustment::changed` signal
is tied to the emission of the `gobject::Object::notify` signals of the changed
properties, it’s possible to compress the `Adjustment::changed`
signals into one by calling `gobject::ObjectExt::freeze_notify` and
`gobject::ObjectExt::thaw_notify` around the calls to the individual setters.

Alternatively, using a single `gobject::ObjectExt::set` for all the properties
to change, or using `AdjustmentExt::configure` has the same effect
of compressing `Adjustment::changed` emissions.
## `lower`
the new minimum value
<!-- trait AdjustmentExt::fn set_page_increment -->
Sets the page increment of the adjustment.

See `AdjustmentExt::set_lower` about how to compress multiple
emissions of the `Adjustment::changed` signal when setting
multiple adjustment properties.
## `page_increment`
the new page increment
<!-- trait AdjustmentExt::fn set_page_size -->
Sets the page size of the adjustment.

See `AdjustmentExt::set_lower` about how to compress multiple
emissions of the `Adjustment`::changed signal when setting
multiple adjustment properties.
## `page_size`
the new page size
<!-- trait AdjustmentExt::fn set_step_increment -->
Sets the step increment of the adjustment.

See `AdjustmentExt::set_lower` about how to compress multiple
emissions of the `Adjustment::changed` signal when setting
multiple adjustment properties.
## `step_increment`
the new step increment
<!-- trait AdjustmentExt::fn set_upper -->
Sets the maximum value of the adjustment.

Note that values will be restricted by `upper - page-size`
if the page-size property is nonzero.

See `AdjustmentExt::set_lower` about how to compress multiple
emissions of the `Adjustment::changed` signal when setting
multiple adjustment properties.
## `upper`
the new maximum value
<!-- trait AdjustmentExt::fn set_value -->
Sets the `Adjustment` value. The value is clamped to lie between
`Adjustment:lower` and `Adjustment:upper`.

Note that for adjustments which are used in a `Scrollbar`, the
effective range of allowed values goes from `Adjustment:lower` to
`Adjustment:upper` - `Adjustment:page-size`.
## `value`
the new value
<!-- trait AdjustmentExt::fn value_changed -->
Emits a `Adjustment::value-changed` signal from the `Adjustment`.
This is typically called by the owner of the `Adjustment` after it has
changed the `Adjustment:value` property.

# Deprecated since 3.18

GTK+ emits `Adjustment::value-changed` itself whenever
 the value changes
<!-- trait AdjustmentExt::fn connect_changed -->
Emitted when one or more of the `Adjustment` properties have been
changed, other than the `Adjustment:value` property.
<!-- trait AdjustmentExt::fn connect_value_changed -->
Emitted when the `Adjustment:value` property has been changed.
<!-- trait AdjustmentExt::fn get_property_lower -->
The minimum value of the adjustment.
<!-- trait AdjustmentExt::fn set_property_lower -->
The minimum value of the adjustment.
<!-- trait AdjustmentExt::fn get_property_page_increment -->
The page increment of the adjustment.
<!-- trait AdjustmentExt::fn set_property_page_increment -->
The page increment of the adjustment.
<!-- trait AdjustmentExt::fn get_property_page_size -->
The page size of the adjustment.
Note that the page-size is irrelevant and should be set to zero
if the adjustment is used for a simple scalar value, e.g. in a
`SpinButton`.
<!-- trait AdjustmentExt::fn set_property_page_size -->
The page size of the adjustment.
Note that the page-size is irrelevant and should be set to zero
if the adjustment is used for a simple scalar value, e.g. in a
`SpinButton`.
<!-- trait AdjustmentExt::fn get_property_step_increment -->
The step increment of the adjustment.
<!-- trait AdjustmentExt::fn set_property_step_increment -->
The step increment of the adjustment.
<!-- trait AdjustmentExt::fn get_property_upper -->
The maximum value of the adjustment.
Note that values will be restricted by
`upper - page-size` if the page-size
property is nonzero.
<!-- trait AdjustmentExt::fn set_property_upper -->
The maximum value of the adjustment.
Note that values will be restricted by
`upper - page-size` if the page-size
property is nonzero.
<!-- trait AdjustmentExt::fn get_property_value -->
The value of the adjustment.
<!-- trait AdjustmentExt::fn set_property_value -->
The value of the adjustment.
<!-- enum Align -->
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 `Widget:expand`
flag inside a `Box`, 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 `Align::Start` and `Align::End`
are interpreted relative to text direction.

GTK_ALIGN_BASELINE support for it is optional for containers and widgets, and
it is only supported for vertical alignment. When its not supported by
a child or a container it is treated as `Align::Fill`.
<!-- enum Align::variant Fill -->
stretch to fill all space if possible, center if
 no meaningful way to stretch
<!-- enum Align::variant Start -->
snap to left or top side, leaving space on right
 or bottom
<!-- enum Align::variant End -->
snap to right or bottom side, leaving space on left
 or top
<!-- enum Align::variant Center -->
center natural width of widget inside the
 allocation
<!-- enum Align::variant Baseline -->
align the widget according to the baseline. Since 3.10.
<!-- struct AppChooser -->
`AppChooser` is an interface that can be implemented by widgets which
allow the user to choose an application (typically for the purpose of
opening a file). The main objects that implement this interface are
`AppChooserWidget`, `AppChooserDialog` and `AppChooserButton`.

Applications are represented by GIO `gio::AppInfo` objects here.
GIO has a concept of recommended and fallback applications for a
given content type. Recommended applications are those that claim
to handle the content type itself, while fallback also includes
applications that handle a more generic content type. GIO also
knows the default and last-used application for a given content
type. The `AppChooserWidget` provides detailed control over
whether the shown list of applications should include default,
recommended or fallback applications.

To obtain the application that has been selected in a `AppChooser`,
use `AppChooser::get_app_info`.

# Implements

[`AppChooserExt`](trait.AppChooserExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AppChooserExt -->
Trait containing all `AppChooser` methods.

# Implementors

[`AppChooserButton`](struct.AppChooserButton.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`AppChooserWidget`](struct.AppChooserWidget.html), [`AppChooser`](struct.AppChooser.html)
<!-- trait AppChooserExt::fn get_app_info -->
Returns the currently selected application.

# Returns

a `gio::AppInfo` for the currently selected
 application, or `None` if none is selected. Free with `gobject::ObjectExt::unref`
<!-- trait AppChooserExt::fn get_content_type -->
Returns the current value of the `AppChooser:content-type` property.

# Returns

the content type of `self`. Free with `g_free`
<!-- trait AppChooserExt::fn refresh -->
Reloads the list of applications.
<!-- trait AppChooserExt::fn get_property_content_type -->
The content type of the `AppChooser` object.

See [GContentType][gio-GContentType]
for more information about content types.
<!-- trait AppChooserExt::fn set_property_content_type -->
The content type of the `AppChooser` object.

See [GContentType][gio-GContentType]
for more information about content types.
<!-- struct AppChooserButton -->
The `AppChooserButton` is a widget that lets the user select
an application. It implements the `AppChooser` interface.

Initially, a `AppChooserButton` selects the first application
in its list, which will either be the most-recently used application
or, if `AppChooserButton:show-default-item` is `true`, the
default application.

The list of applications shown in a `AppChooserButton` includes
the recommended applications for the given content type. When
`AppChooserButton:show-default-item` is set, the default application
is also included. To let the user chooser other applications,
you can set the `AppChooserButton:show-dialog-item` property,
which allows to open a full `AppChooserDialog`.

It is possible to add custom items to the list, using
`AppChooserButtonExt::append_custom_item`. These items cause
the `AppChooserButton::custom-item-activated` signal to be
emitted when they are selected.

To track changes in the selected application, use the
`ComboBox::changed` signal.

# Implements

[`AppChooserButtonExt`](trait.AppChooserButtonExt.html), [`ComboBoxExt`](trait.ComboBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`AppChooserExt`](trait.AppChooserExt.html), [`ComboBoxExtManual`](prelude/trait.ComboBoxExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AppChooserButtonExt -->
Trait containing all `AppChooserButton` methods.

# Implementors

[`AppChooserButton`](struct.AppChooserButton.html)
<!-- impl AppChooserButton::fn new -->
Creates a new `AppChooserButton` for applications
that can handle content of the given type.
## `content_type`
the content type to show applications for

# Returns

a newly created `AppChooserButton`
<!-- trait AppChooserButtonExt::fn append_custom_item -->
Appends a custom item to the list of applications that is shown
in the popup; the item name must be unique per-widget.
Clients can use the provided name as a detail for the
`AppChooserButton::custom-item-activated` signal, to add a
callback for the activation of a particular custom item in the list.
See also `AppChooserButtonExt::append_separator`.
## `name`
the name of the custom item
## `label`
the label for the custom item
## `icon`
the icon for the custom item
<!-- trait AppChooserButtonExt::fn append_separator -->
Appends a separator to the list of applications that is shown
in the popup.
<!-- trait AppChooserButtonExt::fn get_heading -->
Returns the text to display at the top of the dialog.

# Returns

the text to display at the top of the dialog,
 or `None`, in which case a default text is displayed
<!-- trait AppChooserButtonExt::fn get_show_default_item -->
Returns the current value of the `AppChooserButton:show-default-item`
property.

# Returns

the value of `AppChooserButton:show-default-item`
<!-- trait AppChooserButtonExt::fn get_show_dialog_item -->
Returns the current value of the `AppChooserButton:show-dialog-item`
property.

# Returns

the value of `AppChooserButton:show-dialog-item`
<!-- trait AppChooserButtonExt::fn set_active_custom_item -->
Selects a custom item previously added with
`AppChooserButtonExt::append_custom_item`.

Use `AppChooser::refresh` to bring the selection
to its initial state.
## `name`
the name of the custom item
<!-- trait AppChooserButtonExt::fn set_heading -->
Sets the text to display at the top of the dialog.
If the heading is not set, the dialog displays a default text.
## `heading`
a string containing Pango markup
<!-- trait AppChooserButtonExt::fn set_show_default_item -->
Sets whether the dropdown menu of this button should show the
default application for the given content type at top.
## `setting`
the new value for `AppChooserButton:show-default-item`
<!-- trait AppChooserButtonExt::fn set_show_dialog_item -->
Sets whether the dropdown menu of this button should show an
entry to trigger a `AppChooserDialog`.
## `setting`
the new value for `AppChooserButton:show-dialog-item`
<!-- trait AppChooserButtonExt::fn connect_custom_item_activated -->
Emitted when a custom item, previously added with
`AppChooserButtonExt::append_custom_item`, is activated from the
dropdown menu.
## `item_name`
the name of the activated item
<!-- trait AppChooserButtonExt::fn get_property_heading -->
The text to show at the top of the dialog that can be
opened from the button. The string may contain Pango markup.
<!-- trait AppChooserButtonExt::fn set_property_heading -->
The text to show at the top of the dialog that can be
opened from the button. The string may contain Pango markup.
<!-- trait AppChooserButtonExt::fn get_property_show_default_item -->
The `AppChooserButton:show-default-item` property determines
whether the dropdown menu should show the default application
on top for the provided content type.
<!-- trait AppChooserButtonExt::fn set_property_show_default_item -->
The `AppChooserButton:show-default-item` property determines
whether the dropdown menu should show the default application
on top for the provided content type.
<!-- trait AppChooserButtonExt::fn get_property_show_dialog_item -->
The `AppChooserButton:show-dialog-item` property determines
whether the dropdown menu should show an item that triggers
a `AppChooserDialog` when clicked.
<!-- trait AppChooserButtonExt::fn set_property_show_dialog_item -->
The `AppChooserButton:show-dialog-item` property determines
whether the dropdown menu should show an item that triggers
a `AppChooserDialog` when clicked.
<!-- struct AppChooserDialog -->
`AppChooserDialog` shows a `AppChooserWidget` inside a `Dialog`.

Note that `AppChooserDialog` does not have any interesting methods
of its own. Instead, you should get the embedded `AppChooserWidget`
using `AppChooserDialogExt::get_widget` and call its methods if
the generic `AppChooser` interface is not sufficient for your needs.

To set the heading that is shown above the `AppChooserWidget`,
use `AppChooserDialogExt::set_heading`.

# Implements

[`AppChooserDialogExt`](trait.AppChooserDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`AppChooserExt`](trait.AppChooserExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AppChooserDialogExt -->
Trait containing all `AppChooserDialog` methods.

# Implementors

[`AppChooserDialog`](struct.AppChooserDialog.html)
<!-- impl AppChooserDialog::fn new -->
Creates a new `AppChooserDialog` for the provided `gio::File`,
to allow the user to select an application for it.
## `parent`
a `Window`, or `None`
## `flags`
flags for this dialog
## `file`
a `gio::File`

# Returns

a newly created `AppChooserDialog`
<!-- impl AppChooserDialog::fn new_for_content_type -->
Creates a new `AppChooserDialog` for the provided content type,
to allow the user to select an application for it.
## `parent`
a `Window`, or `None`
## `flags`
flags for this dialog
## `content_type`
a content type string

# Returns

a newly created `AppChooserDialog`
<!-- trait AppChooserDialogExt::fn get_heading -->
Returns the text to display at the top of the dialog.

# Returns

the text to display at the top of the dialog, or `None`, in which
 case a default text is displayed
<!-- trait AppChooserDialogExt::fn get_widget -->
Returns the `AppChooserWidget` of this dialog.

# Returns

the `AppChooserWidget` of `self`
<!-- trait AppChooserDialogExt::fn set_heading -->
Sets the text to display at the top of the dialog.
If the heading is not set, the dialog displays a default text.
## `heading`
a string containing Pango markup
<!-- trait AppChooserDialogExt::fn get_property_gfile -->
The GFile used by the `AppChooserDialog`.
The dialog's `AppChooserWidget` content type will be guessed from the
file, if present.
<!-- trait AppChooserDialogExt::fn set_property_gfile -->
The GFile used by the `AppChooserDialog`.
The dialog's `AppChooserWidget` content type will be guessed from the
file, if present.
<!-- trait AppChooserDialogExt::fn get_property_heading -->
The text to show at the top of the dialog.
The string may contain Pango markup.
<!-- trait AppChooserDialogExt::fn set_property_heading -->
The text to show at the top of the dialog.
The string may contain Pango markup.
<!-- struct AppChooserWidget -->
`AppChooserWidget` is a widget for selecting applications.
It is the main building block for `AppChooserDialog`. Most
applications only need to use the latter; but you can use
this widget as part of a larger widget if you have special needs.

`AppChooserWidget` offers detailed control over what applications
are shown, using the
`AppChooserWidget:show-default`,
`AppChooserWidget:show-recommended`,
`AppChooserWidget:show-fallback`,
`AppChooserWidget:show-other` and
`AppChooserWidget:show-all`
properties. See the `AppChooser` documentation for more information
about these groups of applications.

To keep track of the selected application, use the
`AppChooserWidget::application-selected` and `AppChooserWidget::application-activated` signals.

# CSS nodes

`AppChooserWidget` has a single CSS node with name appchooser.

# Implements

[`AppChooserWidgetExt`](trait.AppChooserWidgetExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`AppChooserExt`](trait.AppChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AppChooserWidgetExt -->
Trait containing all `AppChooserWidget` methods.

# Implementors

[`AppChooserWidget`](struct.AppChooserWidget.html)
<!-- impl AppChooserWidget::fn new -->
Creates a new `AppChooserWidget` for applications
that can handle content of the given type.
## `content_type`
the content type to show applications for

# Returns

a newly created `AppChooserWidget`
<!-- trait AppChooserWidgetExt::fn get_default_text -->
Returns the text that is shown if there are not applications
that can handle the content type.

# Returns

the value of `AppChooserWidget:default-text`
<!-- trait AppChooserWidgetExt::fn get_show_all -->
Returns the current value of the `AppChooserWidget:show-all`
property.

# Returns

the value of `AppChooserWidget:show-all`
<!-- trait AppChooserWidgetExt::fn get_show_default -->
Returns the current value of the `AppChooserWidget:show-default`
property.

# Returns

the value of `AppChooserWidget:show-default`
<!-- trait AppChooserWidgetExt::fn get_show_fallback -->
Returns the current value of the `AppChooserWidget:show-fallback`
property.

# Returns

the value of `AppChooserWidget:show-fallback`
<!-- trait AppChooserWidgetExt::fn get_show_other -->
Returns the current value of the `AppChooserWidget:show-other`
property.

# Returns

the value of `AppChooserWidget:show-other`
<!-- trait AppChooserWidgetExt::fn get_show_recommended -->
Returns the current value of the `AppChooserWidget:show-recommended`
property.

# Returns

the value of `AppChooserWidget:show-recommended`
<!-- trait AppChooserWidgetExt::fn set_default_text -->
Sets the text that is shown if there are not applications
that can handle the content type.
## `text`
the new value for `AppChooserWidget:default-text`
<!-- trait AppChooserWidgetExt::fn set_show_all -->
Sets whether the app chooser should show all applications
in a flat list.
## `setting`
the new value for `AppChooserWidget:show-all`
<!-- trait AppChooserWidgetExt::fn set_show_default -->
Sets whether the app chooser should show the default handler
for the content type in a separate section.
## `setting`
the new value for `AppChooserWidget:show-default`
<!-- trait AppChooserWidgetExt::fn set_show_fallback -->
Sets whether the app chooser should show related applications
for the content type in a separate section.
## `setting`
the new value for `AppChooserWidget:show-fallback`
<!-- trait AppChooserWidgetExt::fn set_show_other -->
Sets whether the app chooser should show applications
which are unrelated to the content type.
## `setting`
the new value for `AppChooserWidget:show-other`
<!-- trait AppChooserWidgetExt::fn set_show_recommended -->
Sets whether the app chooser should show recommended applications
for the content type in a separate section.
## `setting`
the new value for `AppChooserWidget:show-recommended`
<!-- trait AppChooserWidgetExt::fn connect_application_activated -->
Emitted when an application item is activated from the widget's list.

This usually happens when the user double clicks an item, or an item
is selected and the user presses one of the keys Space, Shift+Space,
Return or Enter.
## `application`
the activated `gio::AppInfo`
<!-- trait AppChooserWidgetExt::fn connect_application_selected -->
Emitted when an application item is selected from the widget's list.
## `application`
the selected `gio::AppInfo`
<!-- trait AppChooserWidgetExt::fn connect_populate_popup -->
Emitted when a context menu is about to popup over an application item.
Clients can insert menu items into the provided `Menu` object in the
callback of this signal; the context menu will be shown over the item
if at least one item has been added to the menu.
## `menu`
the `Menu` to populate
## `application`
the current `gio::AppInfo`
<!-- trait AppChooserWidgetExt::fn get_property_default_text -->
The `AppChooserWidget:default-text` property determines the text
that appears in the widget when there are no applications for the
given content type.
See also `AppChooserWidgetExt::set_default_text`.
<!-- trait AppChooserWidgetExt::fn set_property_default_text -->
The `AppChooserWidget:default-text` property determines the text
that appears in the widget when there are no applications for the
given content type.
See also `AppChooserWidgetExt::set_default_text`.
<!-- trait AppChooserWidgetExt::fn get_property_show_all -->
If the `AppChooserWidget:show-all` property is `true`, the app
chooser presents all applications in a single list, without
subsections for default, recommended or related applications.
<!-- trait AppChooserWidgetExt::fn set_property_show_all -->
If the `AppChooserWidget:show-all` property is `true`, the app
chooser presents all applications in a single list, without
subsections for default, recommended or related applications.
<!-- trait AppChooserWidgetExt::fn get_property_show_default -->
The ::show-default property determines whether the app chooser
should show the default handler for the content type in a
separate section. If `false`, the default handler is listed
among the recommended applications.
<!-- trait AppChooserWidgetExt::fn set_property_show_default -->
The ::show-default property determines whether the app chooser
should show the default handler for the content type in a
separate section. If `false`, the default handler is listed
among the recommended applications.
<!-- trait AppChooserWidgetExt::fn get_property_show_fallback -->
The `AppChooserWidget:show-fallback` property determines whether
the app chooser should show a section for fallback applications.
If `false`, the fallback applications are listed among the other
applications.
<!-- trait AppChooserWidgetExt::fn set_property_show_fallback -->
The `AppChooserWidget:show-fallback` property determines whether
the app chooser should show a section for fallback applications.
If `false`, the fallback applications are listed among the other
applications.
<!-- trait AppChooserWidgetExt::fn get_property_show_other -->
The `AppChooserWidget:show-other` property determines whether
the app chooser should show a section for other applications.
<!-- trait AppChooserWidgetExt::fn set_property_show_other -->
The `AppChooserWidget:show-other` property determines whether
the app chooser should show a section for other applications.
<!-- trait AppChooserWidgetExt::fn get_property_show_recommended -->
The `AppChooserWidget:show-recommended` property determines
whether the app chooser should show a section for recommended
applications. If `false`, the recommended applications are listed
among the other applications.
<!-- trait AppChooserWidgetExt::fn set_property_show_recommended -->
The `AppChooserWidget:show-recommended` property determines
whether the app chooser should show a section for recommended
applications. If `false`, the recommended applications are listed
among the other applications.
<!-- struct Application -->
`Application` is a class that handles many important aspects
of a GTK+ application in a convenient fashion, without enforcing
a one-size-fits-all application model.

Currently, `Application` handles GTK+ initialization, application
uniqueness, session management, provides some basic scriptability and
desktop shell integration by exporting actions and menus and manages a
list of toplevel windows whose life-cycle is automatically tied to the
life-cycle of your application.

While `Application` works fine with plain ``GtkWindows``, it is recommended
to use it together with `ApplicationWindow`.

When GDK threads are enabled, `Application` will acquire the GDK
lock when invoking actions that arrive from other processes. The GDK
lock is not touched for local action invocations. In order to have
actions invoked in a predictable context it is therefore recommended
that the GDK lock be held while invoking actions locally with
`gio::ActionGroup::activate_action`. The same applies to actions
associated with `ApplicationWindow` and to the “activate” and
“open” `gio::Application` methods.

## Automatic resources ## {`automatic`-resources}

`Application` will automatically load menus from the `Builder`
resource located at "gtk/menus.ui", relative to the application's
resource base path (see `gio::ApplicationExt::set_resource_base_path`). The
menu with the ID "app-menu" is taken as the application's app menu
and the menu with the ID "menubar" is taken as the application's
menubar. Additional menus (most interesting submenus) can be named
and accessed via `GtkApplicationExt::get_menu_by_id` which allows for
dynamic population of a part of the menu structure.

If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are
present then these files will be used in preference, depending on the value
of `GtkApplicationExt::prefers_app_menu`. If the resource "gtk/menus-common.ui"
is present it will be loaded as well. This is useful for storing items that
are referenced from both "gtk/menus-appmenu.ui" and
"gtk/menus-traditional.ui".

It is also possible to provide the menus manually using
`GtkApplicationExt::set_app_menu` and `GtkApplicationExt::set_menubar`.

`Application` will also automatically setup an icon search path for
the default icon theme by appending "icons" to the resource base
path. This allows your application to easily store its icons as
resources. See `IconThemeExt::add_resource_path` for more
information.

If there is a resource located at "gtk/help-overlay.ui" which
defines a `ShortcutsWindow` with ID "help_overlay" then `Application`
associates an instance of this shortcuts window with each
`ApplicationWindow` and sets up keyboard accelerators (Control-F1
and Control-?) to open it. To create a menu item that displays the
shortcuts window, associate the item with the action win.show-help-overlay.

## A simple application ## {`gtkapplication`}

[A simple example](https://git.gnome.org/browse/gtk+/tree/examples/bp/bloatpad.c)

`Application` optionally registers with a session manager
of the users session (if you set the `Application:register-session`
property) and offers various functionality related to the session
life-cycle.

An application can block various ways to end the session with
the `GtkApplicationExt::inhibit` function. Typical use cases for
this kind of inhibiting are long-running, uninterruptible operations,
such as burning a CD or performing a disk backup. The session
manager may not honor the inhibitor, but it can be expected to
inform the user about the negative consequences of ending the
session while inhibitors are present.

## See Also ## {`seealso`}
[HowDoI: Using `Application`](https://wiki.gnome.org/HowDoI/`Application`),
[Getting Started with GTK+: Basics](https://developer.gnome.org/gtk3/stable/gtk-getting-started.html`id`-1.2.3.3)

# Implements

[`GtkApplicationExt`](trait.GtkApplicationExt.html), [`gio::ApplicationExt`](../gio/trait.ApplicationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`gio::ActionGroupExt`](../gio/trait.ActionGroupExt.html), [`gio::ActionMapExt`](../gio/trait.ActionMapExt.html), [`gio::ApplicationExtManual`](../gio/prelude/trait.ApplicationExtManual.html)
<!-- trait GtkApplicationExt -->
Trait containing all `Application` methods.

# Implementors

[`Application`](struct.Application.html)
<!-- impl Application::fn new -->
Creates a new `Application` instance.

When using `Application`, it is not necessary to call `gtk_init`
manually. It is called as soon as the application gets registered as
the primary instance.

Concretely, `gtk_init` is called in the default handler for the
`gio::Application::startup` signal. Therefore, `Application` subclasses should
chain up in their `gio::Application::startup` handler before using any GTK+ API.

Note that commandline arguments are not passed to `gtk_init`.
All GTK+ functionality that is available via commandline arguments
can also be achieved by setting suitable environment variables
such as `G_DEBUG`, so this should not be a big
problem. If you absolutely must support GTK+ commandline arguments,
you can explicitly call `gtk_init` before creating the application
instance.

If non-`None`, the application ID must be valid. See
`gio::Application::id_is_valid`.

If no application ID is given then some features (most notably application
uniqueness) will be disabled. A null application ID is only allowed with
GTK+ 3.6 or later.
## `application_id`
The application ID.
## `flags`
the application flags

# Returns

a new `Application` instance
<!-- trait GtkApplicationExt::fn add_window -->
Adds a window to `self`.

This call can only happen after the `self` has started;
typically, you should add new application windows in response
to the emission of the `gio::Application::activate` signal.

This call is equivalent to setting the `Window:application`
property of `window` to `self`.

Normally, the connection between the application and the window
will remain until the window is destroyed, but you can explicitly
remove it with `GtkApplicationExt::remove_window`.

GTK+ will keep the `self` running as long as it has
any windows.
## `window`
a `Window`
<!-- trait GtkApplicationExt::fn get_accels_for_action -->
Gets the accelerators that are currently associated with
the given action.
## `detailed_action_name`
a detailed action name, specifying an action
 and target to obtain accelerators for

# Returns

accelerators for `detailed_action_name`, as
 a `None`-terminated array. Free with `g_strfreev` when no longer needed
<!-- trait GtkApplicationExt::fn get_actions_for_accel -->
Returns the list of actions (possibly empty) that `accel` maps to.
Each item in the list is a detailed action name in the usual form.

This might be useful to discover if an accel already exists in
order to prevent installation of a conflicting accelerator (from
an accelerator editor or a plugin system, for example). Note that
having more than one action per accelerator may not be a bad thing
and might make sense in cases where the actions never appear in the
same context.

In case there are no actions for a given accelerator, an empty array
is returned. `None` is never returned.

It is a programmer error to pass an invalid accelerator string.
If you are unsure, check it with `gtk_accelerator_parse` first.
## `accel`
an accelerator that can be parsed by `gtk_accelerator_parse`

# Returns

a `None`-terminated array of actions for `accel`
<!-- trait GtkApplicationExt::fn get_active_window -->
Gets the “active” window for the application.

The active window is the one that was most recently focused (within
the application). This window may not have the focus at the moment
if another application has it — this is just the most
recently-focused window within this application.

# Returns

the active window, or `None` if
 there isn't one.
<!-- trait GtkApplicationExt::fn get_app_menu -->
Returns the menu model that has been set with
`GtkApplicationExt::set_app_menu`.

# Returns

the application menu of `self`
 or `None` if no application menu has been set.
<!-- trait GtkApplicationExt::fn get_menu_by_id -->
Gets a menu from automatically loaded resources.
See [Automatic resources][automatic-resources]
for more information.
## `id`
the id of the menu to look up

# Returns

Gets the menu with the
 given id from the automatically loaded resources
<!-- trait GtkApplicationExt::fn get_menubar -->
Returns the menu model that has been set with
`GtkApplicationExt::set_menubar`.

# Returns

the menubar for windows of `self`
<!-- trait GtkApplicationExt::fn get_window_by_id -->
Returns the `ApplicationWindow` with the given ID.

The ID of a `ApplicationWindow` can be retrieved with
`ApplicationWindowExt::get_id`.
## `id`
an identifier number

# Returns

the window with ID `id`, or
 `None` if there is no window with this ID
<!-- trait GtkApplicationExt::fn get_windows -->
Gets a list of the ``GtkWindows`` associated with `self`.

The list is sorted by most recently focused window, such that the first
element is the currently focused window. (Useful for choosing a parent
for a transient window.)

The list that is returned should not be modified in any way. It will
only remain valid until the next focus change or window creation or
deletion.

# Returns

a `glib::List` of `Window`
<!-- trait GtkApplicationExt::fn inhibit -->
Inform the session manager that certain types of actions should be
inhibited. This is not guaranteed to work on all platforms and for
all types of actions.

Applications should invoke this method when they begin an operation
that should not be interrupted, such as creating a CD or DVD. The
types of actions that may be blocked are specified by the `flags`
parameter. When the application completes the operation it should
call `GtkApplicationExt::uninhibit` to remove the inhibitor. Note that
an application can have multiple inhibitors, and all of them must
be individually removed. Inhibitors are also cleared when the
application exits.

Applications should not expect that they will always be able to block
the action. In most cases, users will be given the option to force
the action to take place.

Reasons should be short and to the point.

If `window` is given, the session manager may point the user to
this window to find out more about why the action is inhibited.
## `window`
a `Window`, or `None`
## `flags`
what types of actions should be inhibited
## `reason`
a short, human-readable string that explains
 why these operations are inhibited

# Returns

A non-zero cookie that is used to uniquely identify this
 request. It should be used as an argument to `GtkApplicationExt::uninhibit`
 in order to remove the request. If the platform does not support
 inhibiting or the request failed for some reason, 0 is returned.
<!-- trait GtkApplicationExt::fn is_inhibited -->
Determines if any of the actions specified in `flags` are
currently inhibited (possibly by another application).

Note that this information may not be available (for example
when the application is running in a sandbox).
## `flags`
what types of actions should be queried

# Returns

`true` if any of the actions specified in `flags` are inhibited
<!-- trait GtkApplicationExt::fn list_action_descriptions -->
Lists the detailed action names which have associated accelerators.
See `GtkApplicationExt::set_accels_for_action`.

# Returns

a `None`-terminated array of strings,
 free with `g_strfreev` when done
<!-- trait GtkApplicationExt::fn prefers_app_menu -->
Determines if the desktop environment in which the application is
running would prefer an application menu be shown.

If this function returns `true` then the application should call
`GtkApplicationExt::set_app_menu` with the contents of an application
menu, which will be shown by the desktop environment. If it returns
`false` then you should consider using an alternate approach, such as
a menubar.

The value returned by this function is purely advisory and you are
free to ignore it. If you call `GtkApplicationExt::set_app_menu` even
if the desktop environment doesn't support app menus, then a fallback
will be provided.

Applications are similarly free not to set an app menu even if the
desktop environment wants to show one. In that case, a fallback will
also be created by the desktop environment (GNOME, for example, uses
a menu with only a "Quit" item in it).

The value returned by this function never changes. Once it returns a
particular value, it is guaranteed to always return the same value.

You may only call this function after the application has been
registered and after the base startup handler has run. You're most
likely to want to use this from your own startup handler. It may
also make sense to consult this function while constructing UI (in
activate, open or an action activation handler) in order to determine
if you should show a gear menu or not.

This function will return `false` on Mac OS and a default app menu
will be created automatically with the "usual" contents of that menu
typical to most Mac OS applications. If you call
`GtkApplicationExt::set_app_menu` anyway, then this menu will be
replaced with your own.

# Returns

`true` if you should set an app menu
<!-- trait GtkApplicationExt::fn remove_window -->
Remove a window from `self`.

If `window` belongs to `self` then this call is equivalent to
setting the `Window:application` property of `window` to
`None`.

The application may stop running as a result of a call to this
function.
## `window`
a `Window`
<!-- trait GtkApplicationExt::fn set_accels_for_action -->
Sets zero or more keyboard accelerators that will trigger the
given action. The first item in `accels` will be the primary
accelerator, which may be displayed in the UI.

To remove all accelerators for an action, use an empty, zero-terminated
array for `accels`.

For the `detailed_action_name`, see `gio::Action::parse_detailed_name` and
`gio::Action::print_detailed_name`.
## `detailed_action_name`
a detailed action name, specifying an action
 and target to associate accelerators with
## `accels`
a list of accelerators in the format
 understood by `gtk_accelerator_parse`
<!-- trait GtkApplicationExt::fn set_app_menu -->
Sets or unsets the application menu for `self`.

This can only be done in the primary instance of the application,
after it has been registered. `gio::Application::startup` is a good place
to call this.

The application menu is a single menu containing items that typically
impact the application as a whole, rather than acting on a specific
window or document. For example, you would expect to see
“Preferences” or “Quit” in an application menu, but not “Save” or
“Print”.

If supported, the application menu will be rendered by the desktop
environment.

Use the base `gio::ActionMap` interface to add actions, to respond to the user
selecting these menu items.
## `app_menu`
a `gio::MenuModel`, or `None`
<!-- trait GtkApplicationExt::fn set_menubar -->
Sets or unsets the menubar for windows of `self`.

This is a menubar in the traditional sense.

This can only be done in the primary instance of the application,
after it has been registered. `gio::Application::startup` is a good place
to call this.

Depending on the desktop environment, this may appear at the top of
each window, or at the top of the screen. In some environments, if
both the application menu and the menubar are set, the application
menu will be presented as if it were the first item of the menubar.
Other environments treat the two as completely separate — for example,
the application menu may be rendered by the desktop shell while the
menubar (if set) remains in each individual window.

Use the base `gio::ActionMap` interface to add actions, to respond to the
user selecting these menu items.
## `menubar`
a `gio::MenuModel`, or `None`
<!-- trait GtkApplicationExt::fn uninhibit -->
Removes an inhibitor that has been established with `GtkApplicationExt::inhibit`.
Inhibitors are also cleared when the application exits.
## `cookie`
a cookie that was returned by `GtkApplicationExt::inhibit`
<!-- trait GtkApplicationExt::fn connect_query_end -->
Emitted when the session manager is about to end the session, only
if `Application::register-session` is `true`. Applications can
connect to this signal and call `GtkApplicationExt::inhibit` with
`ApplicationInhibitFlags::Logout` to delay the end of the session
until state has been saved.

Feature: `v3_24_8`

<!-- trait GtkApplicationExt::fn connect_window_added -->
Emitted when a `Window` is added to `application` through
`GtkApplicationExt::add_window`.
## `window`
the newly-added `Window`
<!-- trait GtkApplicationExt::fn connect_window_removed -->
Emitted when a `Window` is removed from `application`,
either as a side-effect of being destroyed or explicitly
through `GtkApplicationExt::remove_window`.
## `window`
the `Window` that is being removed
<!-- trait GtkApplicationExt::fn get_property_register_session -->
Set this property to `true` to register with the session manager.
<!-- trait GtkApplicationExt::fn set_property_register_session -->
Set this property to `true` to register with the session manager.
<!-- trait GtkApplicationExt::fn get_property_screensaver_active -->
This property is `true` if GTK+ believes that the screensaver is
currently active. GTK+ only tracks session state (including this)
when `Application::register-session` is set to `true`.

Tracking the screensaver state is supported on Linux.

Feature: `v3_24`

<!-- struct ApplicationInhibitFlags -->
Types of user actions that may be blocked by `GtkApplicationExt::inhibit`.
<!-- struct ApplicationInhibitFlags::const LOGOUT -->
Inhibit ending the user session
 by logging out or by shutting down the computer
<!-- struct ApplicationInhibitFlags::const SWITCH -->
Inhibit user switching
<!-- struct ApplicationInhibitFlags::const SUSPEND -->
Inhibit suspending the
 session or computer
<!-- struct ApplicationInhibitFlags::const IDLE -->
Inhibit the session being
 marked as idle (and possibly locked)
<!-- struct ApplicationWindow -->
`ApplicationWindow` is a `Window` subclass that offers some
extra functionality for better integration with `Application`
features. Notably, it can handle both the application menu as well
as the menubar. See `GtkApplicationExt::set_app_menu` and
`GtkApplicationExt::set_menubar`.

This class implements the `gio::ActionGroup` and `gio::ActionMap` interfaces,
to let you add window-specific actions that will be exported by the
associated `Application`, together with its application-wide
actions. Window-specific actions are prefixed with the “win.”
prefix and application-wide actions are prefixed with the “app.”
prefix. Actions must be addressed with the prefixed name when
referring to them from a `gio::MenuModel`.

Note that widgets that are placed inside a `ApplicationWindow`
can also activate these actions, if they implement the
`Actionable` interface.

As with `Application`, the GDK lock will be acquired when
processing actions arriving from other processes and should therefore
be held when activating actions locally (if GDK threads are enabled).

The settings `Settings:gtk-shell-shows-app-menu` and
`Settings:gtk-shell-shows-menubar` tell GTK+ whether the
desktop environment is showing the application menu and menubar
models outside the application as part of the desktop shell.
For instance, on OS X, both menus will be displayed remotely;
on Windows neither will be. gnome-shell (starting with version 3.4)
will display the application menu, but not the menubar.

If the desktop environment does not display the menubar, then
`ApplicationWindow` will automatically show a `MenuBar` for it.
This behaviour can be overridden with the `ApplicationWindow:show-menubar`
property. If the desktop environment does not display the application
menu, then it will automatically be included in the menubar or in the
windows client-side decorations.

## A `ApplicationWindow` with a menubar


```C
GtkApplication *app = gtk_application_new ("org.gtk.test", 0);

GtkBuilder *builder = gtk_builder_new_from_string (
    "<interface>"
    "  <menu id='menubar'>"
    "    <submenu label='_Edit'>"
    "      <item label='_Copy' action='win.copy'/>"
    "      <item label='_Paste' action='win.paste'/>"
    "    </submenu>"
    "  </menu>"
    "</interface>",
    -1);

GMenuModel *menubar = G_MENU_MODEL (gtk_builder_get_object (builder,
                                                            "menubar"));
gtk_application_set_menubar (GTK_APPLICATION (app), menubar);
g_object_unref (builder);

// ...

GtkWidget *window = gtk_application_window_new (app);
```

## Handling fallback yourself

[A simple example](https://git.gnome.org/browse/gtk+/tree/examples/sunny.c)

The XML format understood by `Builder` for `gio::MenuModel` consists
of a toplevel `<menu>` element, which contains one or more `<item>`
elements. Each `<item>` element contains `<attribute>` and `<link>`
elements with a mandatory name attribute. `<link>` elements have the
same content model as `<menu>`. Instead of `<link name="submenu>` or
`<link name="section">`, you can use `<submenu>` or `<section>`
elements.

Attribute values can be translated using gettext, like other `Builder`
content. `<attribute>` elements can be marked for translation with a
`translatable="yes"` attribute. It is also possible to specify message
context and translator comments, using the context and comments attributes.
To make use of this, the `Builder` must have been given the gettext
domain to use.

The following attributes are used when constructing menu items:
- "label": a user-visible string to display
- "action": the prefixed name of the action to trigger
- "target": the parameter to use when activating the action
- "icon" and "verb-icon": names of icons that may be displayed
- "submenu-action": name of an action that may be used to determine
 if a submenu can be opened
- "hidden-when": a string used to determine when the item will be hidden.
 Possible values include "action-disabled", "action-missing", "macos-menubar".

The following attributes are used when constructing sections:
- "label": a user-visible string to use as section heading
- "display-hint": a string used to determine special formatting for the section.
 Possible values include "horizontal-buttons".
- "text-direction": a string used to determine the `TextDirection` to use
 when "display-hint" is set to "horizontal-buttons". Possible values
 include "rtl", "ltr", and "none".

The following attributes are used when constructing submenus:
- "label": a user-visible string to display
- "icon": icon name to display

# Implements

[`ApplicationWindowExt`](trait.ApplicationWindowExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`gio::ActionGroupExt`](../gio/trait.ActionGroupExt.html), [`gio::ActionMapExt`](../gio/trait.ActionMapExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ApplicationWindowExt -->
Trait containing all `ApplicationWindow` methods.

# Implementors

[`ApplicationWindow`](struct.ApplicationWindow.html)
<!-- impl ApplicationWindow::fn new -->
Creates a new `ApplicationWindow`.
## `application`
a `Application`

# Returns

a newly created `ApplicationWindow`
<!-- trait ApplicationWindowExt::fn get_help_overlay -->
Gets the `ShortcutsWindow` that has been set up with
a prior call to `ApplicationWindowExt::set_help_overlay`.

Feature: `v3_20`


# Returns

the help overlay associated with `self`, or `None`
<!-- trait ApplicationWindowExt::fn get_id -->
Returns the unique ID of the window. If the window has not yet been added to
a `Application`, returns `0`.

# Returns

the unique ID for `self`, or `0` if the window
 has not yet been added to a `Application`
<!-- trait ApplicationWindowExt::fn get_show_menubar -->
Returns whether the window will display a menubar for the app menu
and menubar as needed.

# Returns

`true` if `self` will display a menubar when needed
<!-- trait ApplicationWindowExt::fn set_help_overlay -->
Associates a shortcuts window with the application window, and
sets up an action with the name win.show-help-overlay to present
it.

`self` takes resposibility for destroying `help_overlay`.

Feature: `v3_20`

## `help_overlay`
a `ShortcutsWindow`
<!-- trait ApplicationWindowExt::fn set_show_menubar -->
Sets whether the window will display a menubar for the app menu
and menubar as needed.
## `show_menubar`
whether to show a menubar when needed
<!-- trait ApplicationWindowExt::fn get_property_show_menubar -->
If this property is `true`, the window will display a menubar
that includes the app menu and menubar, unless these are
shown by the desktop shell. See `GtkApplicationExt::set_app_menu`
and `GtkApplicationExt::set_menubar`.

If `false`, the window will not display a menubar, regardless
of whether the desktop shell is showing the menus or not.
<!-- trait ApplicationWindowExt::fn set_property_show_menubar -->
If this property is `true`, the window will display a menubar
that includes the app menu and menubar, unless these are
shown by the desktop shell. See `GtkApplicationExt::set_app_menu`
and `GtkApplicationExt::set_menubar`.

If `false`, the window will not display a menubar, regardless
of whether the desktop shell is showing the menus or not.
<!-- enum ArrowType -->
Used to indicate the direction in which an arrow should point.
<!-- enum ArrowType::variant Up -->
Represents an upward pointing arrow.
<!-- enum ArrowType::variant Down -->
Represents a downward pointing arrow.
<!-- enum ArrowType::variant Left -->
Represents a left pointing arrow.
<!-- enum ArrowType::variant Right -->
Represents a right pointing arrow.
<!-- enum ArrowType::variant None -->
No arrow. Since 2.10.
<!-- struct AspectFrame -->
The `AspectFrame` is useful when you want
pack a widget so that it can resize but always retains
the same aspect ratio. For instance, one might be
drawing a small preview of a larger image. `AspectFrame`
derives from `Frame`, so it can draw a label and
a frame around the child. The frame will be
“shrink-wrapped” to the size of the child.

# CSS nodes

`AspectFrame` uses a CSS node with name frame.

# Implements

[`AspectFrameExt`](trait.AspectFrameExt.html), [`FrameExt`](trait.FrameExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AspectFrameExt -->
Trait containing all `AspectFrame` methods.

# Implementors

[`AspectFrame`](struct.AspectFrame.html)
<!-- impl AspectFrame::fn new -->
Create a new `AspectFrame`.
## `label`
Label text.
## `xalign`
Horizontal alignment of the child within the allocation of
 the `AspectFrame`. This ranges from 0.0 (left aligned)
 to 1.0 (right aligned)
## `yalign`
Vertical alignment of the child within the allocation of
 the `AspectFrame`. This ranges from 0.0 (top aligned)
 to 1.0 (bottom aligned)
## `ratio`
The desired aspect ratio.
## `obey_child`
If `true`, `ratio` is ignored, and the aspect
 ratio is taken from the requistion of the child.

# Returns

the new `AspectFrame`.
<!-- trait AspectFrameExt::fn set -->
Set parameters for an existing `AspectFrame`.
## `xalign`
Horizontal alignment of the child within the allocation of
 the `AspectFrame`. This ranges from 0.0 (left aligned)
 to 1.0 (right aligned)
## `yalign`
Vertical alignment of the child within the allocation of
 the `AspectFrame`. This ranges from 0.0 (top aligned)
 to 1.0 (bottom aligned)
## `ratio`
The desired aspect ratio.
## `obey_child`
If `true`, `ratio` is ignored, and the aspect
 ratio is taken from the requistion of the child.
<!-- struct Assistant -->
A `Assistant` is a widget used to represent a generally complex
operation splitted in several steps, guiding the user through its
pages and controlling the page flow to collect the necessary data.

The design of `Assistant` is that it controls what buttons to show
and to make sensitive, based on what it knows about the page sequence
and the [type][`AssistantPageType`] of each page,
in addition to state information like the page
[completion][gtk-assistant-set-page-complete]
and [committed][gtk-assistant-commit] status.

If you have a case that doesn’t quite fit in ``GtkAssistants`` way of
handling buttons, you can use the `AssistantPageType::Custom` page
type and handle buttons yourself.

# `Assistant` as `Buildable`

The `Assistant` implementation of the `Buildable` interface
exposes the `action_area` as internal children with the name
“action_area”.

To add pages to an assistant in `Builder`, simply add it as a
child to the `Assistant` object, and set its child properties
as necessary.

# CSS nodes

`Assistant` has a single CSS node with the name assistant.

# Implements

[`AssistantExt`](trait.AssistantExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait AssistantExt -->
Trait containing all `Assistant` methods.

# Implementors

[`Assistant`](struct.Assistant.html)
<!-- impl Assistant::fn new -->
Creates a new `Assistant`.

# Returns

a newly created `Assistant`
<!-- trait AssistantExt::fn add_action_widget -->
Adds a widget to the action area of a `Assistant`.
## `child`
a `Widget`
<!-- trait AssistantExt::fn append_page -->
Appends a page to the `self`.
## `page`
a `Widget`

# Returns

the index (starting at 0) of the inserted page
<!-- trait AssistantExt::fn commit -->
Erases the visited page history so the back button is not
shown on the current page, and removes the cancel button
from subsequent pages.

Use this when the information provided up to the current
page is hereafter deemed permanent and cannot be modified
or undone. For example, showing a progress page to track
a long-running, unreversible operation after the user has
clicked apply on a confirmation page.
<!-- trait AssistantExt::fn get_current_page -->
Returns the page number of the current page.

# Returns

The index (starting from 0) of the current
 page in the `self`, or -1 if the `self` has no pages,
 or no current page.
<!-- trait AssistantExt::fn get_n_pages -->
Returns the number of pages in the `self`

# Returns

the number of pages in the `self`
<!-- trait AssistantExt::fn get_nth_page -->
Returns the child widget contained in page number `page_num`.
## `page_num`
the index of a page in the `self`,
 or -1 to get the last page

# Returns

the child widget, or `None`
 if `page_num` is out of bounds
<!-- trait AssistantExt::fn get_page_complete -->
Gets whether `page` is complete.
## `page`
a page of `self`

# Returns

`true` if `page` is complete.
<!-- trait AssistantExt::fn get_page_has_padding -->
Gets whether page has padding.

Feature: `v3_18`

## `page`
a page of `self`

# Returns

`true` if `page` has padding
<!-- trait AssistantExt::fn get_page_title -->
Gets the title for `page`.
## `page`
a page of `self`

# Returns

the title for `page`
<!-- trait AssistantExt::fn get_page_type -->
Gets the page type of `page`.
## `page`
a page of `self`

# Returns

the page type of `page`
<!-- trait AssistantExt::fn insert_page -->
Inserts a page in the `self` at a given position.
## `page`
a `Widget`
## `position`
the index (starting at 0) at which to insert the page,
 or -1 to append the page to the `self`

# Returns

the index (starting from 0) of the inserted page
<!-- trait AssistantExt::fn next_page -->
Navigate to the next page.

It is a programming error to call this function when
there is no next page.

This function is for use when creating pages of the
`AssistantPageType::Custom` type.
<!-- trait AssistantExt::fn prepend_page -->
Prepends a page to the `self`.
## `page`
a `Widget`

# Returns

the index (starting at 0) of the inserted page
<!-- trait AssistantExt::fn previous_page -->
Navigate to the previous visited page.

It is a programming error to call this function when
no previous page is available.

This function is for use when creating pages of the
`AssistantPageType::Custom` type.
<!-- trait AssistantExt::fn remove_action_widget -->
Removes a widget from the action area of a `Assistant`.
## `child`
a `Widget`
<!-- trait AssistantExt::fn remove_page -->
Removes the `page_num`’s page from `self`.
## `page_num`
the index of a page in the `self`,
 or -1 to remove the last page
<!-- trait AssistantExt::fn set_current_page -->
Switches the page to `page_num`.

Note that this will only be necessary in custom buttons,
as the `self` flow can be set with
`AssistantExt::set_forward_page_func`.
## `page_num`
index of the page to switch to, starting from 0.
 If negative, the last page will be used. If greater
 than the number of pages in the `self`, nothing
 will be done.
<!-- trait AssistantExt::fn set_forward_page_func -->
Sets the page forwarding function to be `page_func`.

This function will be used to determine what will be
the next page when the user presses the forward button.
Setting `page_func` to `None` will make the assistant to
use the default forward function, which just goes to the
next visible page.
## `page_func`
the ``GtkAssistantPageFunc``, or `None`
 to use the default one
## `data`
user data for `page_func`
## `destroy`
destroy notifier for `data`
<!-- trait AssistantExt::fn set_page_complete -->
Sets whether `page` contents are complete.

This will make `self` update the buttons state
to be able to continue the task.
## `page`
a page of `self`
## `complete`
the completeness status of the page
<!-- trait AssistantExt::fn set_page_has_padding -->
Sets whether the assistant is adding padding around
the page.

Feature: `v3_18`

## `page`
a page of `self`
## `has_padding`
whether this page has padding
<!-- trait AssistantExt::fn set_page_title -->
Sets a title for `page`.

The title is displayed in the header area of the assistant
when `page` is the current page.
## `page`
a page of `self`
## `title`
the new title for `page`
<!-- trait AssistantExt::fn set_page_type -->
Sets the page type for `page`.

The page type determines the page behavior in the `self`.
## `page`
a page of `self`
## `type_`
the new type for `page`
<!-- trait AssistantExt::fn update_buttons_state -->
Forces `self` to recompute the buttons state.

GTK+ automatically takes care of this in most situations,
e.g. when the user goes to a different page, or when the
visibility or completeness of a page changes.

One situation where it can be necessary to call this
function is when changing a value on the current page
affects the future page flow of the assistant.
<!-- trait AssistantExt::fn connect_apply -->
The ::apply signal is emitted when the apply button is clicked.

The default behavior of the `Assistant` is to switch to the page
after the current page, unless the current page is the last one.

A handler for the ::apply signal should carry out the actions for
which the wizard has collected data. If the action takes a long time
to complete, you might consider putting a page of type
`AssistantPageType::Progress` after the confirmation page and handle
this operation within the `Assistant::prepare` signal of the progress
page.
<!-- trait AssistantExt::fn connect_cancel -->
The ::cancel signal is emitted when then the cancel button is clicked.
<!-- trait AssistantExt::fn connect_close -->
The ::close signal is emitted either when the close button of
a summary page is clicked, or when the apply button in the last
page in the flow (of type `AssistantPageType::Confirm`) is clicked.
<!-- trait AssistantExt::fn connect_prepare -->
The ::prepare signal is emitted when a new page is set as the
assistant's current page, before making the new page visible.

A handler for this signal can do any preparations which are
necessary before showing `page`.
## `page`
the current page
<!-- trait AssistantExt::fn get_property_use_header_bar -->
`true` if the assistant uses a `HeaderBar` for action buttons
instead of the action-area.

For technical reasons, this property is declared as an integer
property, but you should only set it to `true` or `false`.
<!-- trait AssistantExt::fn set_property_use_header_bar -->
`true` if the assistant uses a `HeaderBar` for action buttons
instead of the action-area.

For technical reasons, this property is declared as an integer
property, but you should only set it to `true` or `false`.
<!-- enum AssistantPageType -->
An enum for determining the page role inside the `Assistant`. It's
used to handle buttons sensitivity and visibility.

Note that an assistant needs to end its page flow with a page of type
`AssistantPageType::Confirm`, `AssistantPageType::Summary` or
`AssistantPageType::Progress` to be correct.

The Cancel button will only be shown if the page isn’t “committed”.
See `AssistantExt::commit` for details.
<!-- enum AssistantPageType::variant Content -->
The page has regular contents. Both the
 Back and forward buttons will be shown.
<!-- enum AssistantPageType::variant Intro -->
The page contains an introduction to the
 assistant task. Only the Forward button will be shown if there is a
 next page.
<!-- enum AssistantPageType::variant Confirm -->
The page lets the user confirm or deny the
 changes. The Back and Apply buttons will be shown.
<!-- enum AssistantPageType::variant Summary -->
The page informs the user of the changes
 done. Only the Close button will be shown.
<!-- enum AssistantPageType::variant Progress -->
Used for tasks that take a long time to
 complete, blocks the assistant until the page is marked as complete.
 Only the back button will be shown.
<!-- enum AssistantPageType::variant Custom -->
Used for when other page types are not
 appropriate. No buttons will be shown, and the application must
 add its own buttons through `AssistantExt::add_action_widget`.
<!-- enum BaselinePosition -->
Whenever a container has some form of natural row it may align
children in that row along a common typographical baseline. If
the amount of verical space in the row is taller than the total
requested height of the baseline-aligned children then it can use a
`BaselinePosition` to select where to put the baseline inside the
extra availible space.
<!-- enum BaselinePosition::variant Top -->
Align the baseline at the top
<!-- enum BaselinePosition::variant Center -->
Center the baseline
<!-- enum BaselinePosition::variant Bottom -->
Align the baseline at the bottom
<!-- struct Bin -->
The `Bin` widget is a container with just one child.
It is not very useful itself, but it is useful for deriving subclasses,
since it provides common code needed for handling a single child widget.

Many GTK+ widgets are subclasses of `Bin`, including `Window`,
`Button`, `Frame`, `HandleBox` or `ScrolledWindow`.

# Implements

[`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait BinExt -->
Trait containing all `Bin` methods.

# Implementors

[`ActionBar`](struct.ActionBar.html), [`Bin`](struct.Bin.html), [`Button`](struct.Button.html), [`ComboBox`](struct.ComboBox.html), [`EventBox`](struct.EventBox.html), [`Expander`](struct.Expander.html), [`FlowBoxChild`](struct.FlowBoxChild.html), [`Frame`](struct.Frame.html), [`ListBoxRow`](struct.ListBoxRow.html), [`MenuItem`](struct.MenuItem.html), [`Overlay`](struct.Overlay.html), [`Popover`](struct.Popover.html), [`Revealer`](struct.Revealer.html), [`ScrolledWindow`](struct.ScrolledWindow.html), [`SearchBar`](struct.SearchBar.html), [`StackSidebar`](struct.StackSidebar.html), [`ToolItem`](struct.ToolItem.html), [`Viewport`](struct.Viewport.html), [`Window`](struct.Window.html)
<!-- trait BinExt::fn get_child -->
Gets the child of the `Bin`, or `None` if the bin contains
no child widget. The returned widget does not have a reference
added, so you do not need to unref it.

# Returns

the child of `self`, or `None` if it does
not have a child.
<!-- struct Border -->
A struct that specifies a border around a rectangular area
that can be of different width on each side.
<!-- impl Border::fn new -->
Allocates a new `Border`-struct and initializes its elements to zero.

# Returns

a newly allocated `Border`-struct.
 Free with `Border::free`
<!-- impl Border::fn copy -->
Copies a `Border`-struct.

# Returns

a copy of `self`.
<!-- impl Border::fn free -->
Frees a `Border`-struct.
<!-- enum BorderStyle -->
Describes how the border of a UI element should be rendered.
<!-- enum BorderStyle::variant None -->
No visible border
<!-- enum BorderStyle::variant Solid -->
A single line segment
<!-- enum BorderStyle::variant Inset -->
Looks as if the content is sunken into the canvas
<!-- enum BorderStyle::variant Outset -->
Looks as if the content is coming out of the canvas
<!-- enum BorderStyle::variant Hidden -->
Same as `BorderStyle::None`
<!-- enum BorderStyle::variant Dotted -->
A series of round dots
<!-- enum BorderStyle::variant Dashed -->
A series of square-ended dashes
<!-- enum BorderStyle::variant Double -->
Two parallel lines with some space between them
<!-- enum BorderStyle::variant Groove -->
Looks as if it were carved in the canvas
<!-- enum BorderStyle::variant Ridge -->
Looks as if it were coming out of the canvas
<!-- struct Box -->
The `Box` widget arranges child widgets into a single row or column,
depending upon the value of its `Orientable:orientation` property. Within
the other dimension, all children are allocated the same size. Of course,
the `Widget:halign` and `Widget:valign` properties can be used on
the children to influence their allocation.

`Box` uses a notion of packing. Packing refers
to adding widgets with reference to a particular position in a
`Container`. For a `Box`, there are two reference positions: the
start and the end of the box.
For a vertical `Box`, the start is defined as the top of the box and
the end is defined as the bottom. For a horizontal `Box` the start
is defined as the left side and the end is defined as the right side.

Use repeated calls to `BoxExt::pack_start` to pack widgets into a
`Box` from start to end. Use `BoxExt::pack_end` to add widgets from
end to start. You may intersperse these calls and add widgets from
both ends of the same `Box`.

Because `Box` is a `Container`, you may also use `ContainerExt::add`
to insert widgets into the box, and they will be packed with the default
values for expand and fill child properties. Use `ContainerExt::remove`
to remove widgets from the `Box`.

Use `BoxExt::set_homogeneous` to specify whether or not all children
of the `Box` are forced to get the same amount of space.

Use `BoxExt::set_spacing` to determine how much space will be
minimally placed between all children in the `Box`. Note that
spacing is added between the children, while
padding added by `BoxExt::pack_start` or `BoxExt::pack_end` is added
on either side of the widget it belongs to.

Use `BoxExt::reorder_child` to move a `Box` child to a different
place in the box.

Use `BoxExt::set_child_packing` to reset the expand,
fill and padding child properties.
Use `BoxExt::query_child_packing` to query these fields.

# CSS nodes

`Box` uses a single CSS node with name box.

In horizontal orientation, the nodes of the children are always arranged
from left to right. So :first-child will always select the leftmost child,
regardless of text direction.

# Implements

[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait BoxExt -->
Trait containing all `Box` methods.

# Implementors

[`AppChooserWidget`](struct.AppChooserWidget.html), [`Box`](struct.Box.html), [`ButtonBox`](struct.ButtonBox.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`FileChooserButton`](struct.FileChooserButton.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`InfoBar`](struct.InfoBar.html), [`RecentChooserWidget`](struct.RecentChooserWidget.html), [`ShortcutLabel`](struct.ShortcutLabel.html), [`ShortcutsGroup`](struct.ShortcutsGroup.html), [`ShortcutsSection`](struct.ShortcutsSection.html), [`ShortcutsShortcut`](struct.ShortcutsShortcut.html), [`StackSwitcher`](struct.StackSwitcher.html), [`Statusbar`](struct.Statusbar.html)
<!-- impl Box::fn new -->
Creates a new `Box`.
## `orientation`
the box’s orientation.
## `spacing`
the number of pixels to place by default between children.

# Returns

a new `Box`.
<!-- trait BoxExt::fn get_baseline_position -->
Gets the value set by `BoxExt::set_baseline_position`.

# Returns

the baseline position
<!-- trait BoxExt::fn get_center_widget -->
Retrieves the center widget of the box.

# Returns

the center widget
 or `None` in case no center widget is set.
<!-- trait BoxExt::fn get_homogeneous -->
Returns whether the box is homogeneous (all children are the
same size). See `BoxExt::set_homogeneous`.

# Returns

`true` if the box is homogeneous.
<!-- trait BoxExt::fn get_spacing -->
Gets the value set by `BoxExt::set_spacing`.

# Returns

spacing between children
<!-- trait BoxExt::fn pack_end -->
Adds `child` to `self`, packed with reference to the end of `self`.
The `child` is packed after (away from end of) any other child
packed with reference to the end of `self`.
## `child`
the `Widget` to be added to `self`
## `expand`
`true` if the new child is to be given extra space allocated
 to `self`. The extra space will be divided evenly between all children
 of `self` that use this option
## `fill`
`true` if space given to `child` by the `expand` option is
 actually allocated to `child`, rather than just padding it. This
 parameter has no effect if `expand` is set to `false`. A child is
 always allocated the full height of a horizontal `Box` and the full width
 of a vertical `Box`. This option affects the other dimension
## `padding`
extra space in pixels to put between this child and its
 neighbors, over and above the global amount specified by
 `Box:spacing` property. If `child` is a widget at one of the
 reference ends of `self`, then `padding` pixels are also put between
 `child` and the reference edge of `self`
<!-- trait BoxExt::fn pack_start -->
Adds `child` to `self`, packed with reference to the start of `self`.
The `child` is packed after any other child packed with reference
to the start of `self`.
## `child`
the `Widget` to be added to `self`
## `expand`
`true` if the new child is to be given extra space allocated
 to `self`. The extra space will be divided evenly between all children
 that use this option
## `fill`
`true` if space given to `child` by the `expand` option is
 actually allocated to `child`, rather than just padding it. This
 parameter has no effect if `expand` is set to `false`. A child is
 always allocated the full height of a horizontal `Box` and the full width
 of a vertical `Box`. This option affects the other dimension
## `padding`
extra space in pixels to put between this child and its
 neighbors, over and above the global amount specified by
 `Box:spacing` property. If `child` is a widget at one of the
 reference ends of `self`, then `padding` pixels are also put between
 `child` and the reference edge of `self`
<!-- trait BoxExt::fn query_child_packing -->
Obtains information about how `child` is packed into `self`.
## `child`
the `Widget` of the child to query
## `expand`
pointer to return location for expand child
 property
## `fill`
pointer to return location for fill child
 property
## `padding`
pointer to return location for padding
 child property
## `pack_type`
pointer to return location for pack-type
 child property
<!-- trait BoxExt::fn reorder_child -->
Moves `child` to a new `position` in the list of `self` children.
The list contains widgets packed `PackType::Start`
as well as widgets packed `PackType::End`, in the order that these
widgets were added to `self`.

A widget’s position in the `self` children list determines where
the widget is packed into `self`. A child widget at some position
in the list will be packed just after all other widgets of the
same packing type that appear earlier in the list.
## `child`
the `Widget` to move
## `position`
the new position for `child` in the list of children
 of `self`, starting from 0. If negative, indicates the end of
 the list
<!-- trait BoxExt::fn set_baseline_position -->
Sets the baseline position of a box. This affects
only horizontal boxes with at least one baseline aligned
child. If there is more vertical space available than requested,
and the baseline is not allocated by the parent then
`position` is used to allocate the baseline wrt the
extra space available.
## `position`
a `BaselinePosition`
<!-- trait BoxExt::fn set_center_widget -->
Sets a center widget; that is a child widget that will be
centered with respect to the full width of the box, even
if the children at either side take up different amounts
of space.
## `widget`
the widget to center
<!-- trait BoxExt::fn set_child_packing -->
Sets the way `child` is packed into `self`.
## `child`
the `Widget` of the child to set
## `expand`
the new value of the expand child property
## `fill`
the new value of the fill child property
## `padding`
the new value of the padding child property
## `pack_type`
the new value of the pack-type child property
<!-- trait BoxExt::fn set_homogeneous -->
Sets the `Box:homogeneous` property of `self`, controlling
whether or not all children of `self` are given equal space
in the box.
## `homogeneous`
a boolean value, `true` to create equal allotments,
 `false` for variable allotments
<!-- trait BoxExt::fn set_spacing -->
Sets the `Box:spacing` property of `self`, which is the
number of pixels to place between children of `self`.
## `spacing`
the number of pixels to put between children
<!-- struct Buildable -->
`Buildable` allows objects to extend and customize their deserialization
from [`Builder` UI descriptions][BUILDER-UI].
The interface includes methods for setting names and properties of objects,
parsing custom tags and constructing child objects.

The `Buildable` interface is implemented by all widgets and
many of the non-widget objects that are provided by GTK+. The
main user of this interface is `Builder`. There should be
very little need for applications to call any of these functions directly.

An object only needs to implement this interface if it needs to extend the
`Builder` format or run any extra routines at deserialization time.

# Implements

[`BuildableExt`](trait.BuildableExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait BuildableExt -->
Trait containing all `Buildable` methods.

# Implementors

[`AboutDialog`](struct.AboutDialog.html), [`AccelLabel`](struct.AccelLabel.html), [`ActionBar`](struct.ActionBar.html), [`AppChooserButton`](struct.AppChooserButton.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`AppChooserWidget`](struct.AppChooserWidget.html), [`ApplicationWindow`](struct.ApplicationWindow.html), [`AspectFrame`](struct.AspectFrame.html), [`Assistant`](struct.Assistant.html), [`Bin`](struct.Bin.html), [`Box`](struct.Box.html), [`Buildable`](struct.Buildable.html), [`ButtonBox`](struct.ButtonBox.html), [`Button`](struct.Button.html), [`Calendar`](struct.Calendar.html), [`CellAreaBox`](struct.CellAreaBox.html), [`CellArea`](struct.CellArea.html), [`CellView`](struct.CellView.html), [`CheckButton`](struct.CheckButton.html), [`CheckMenuItem`](struct.CheckMenuItem.html), [`ColorButton`](struct.ColorButton.html), [`ColorChooserDialog`](struct.ColorChooserDialog.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`ComboBoxText`](struct.ComboBoxText.html), [`ComboBox`](struct.ComboBox.html), [`Container`](struct.Container.html), [`Dialog`](struct.Dialog.html), [`DrawingArea`](struct.DrawingArea.html), [`EntryCompletion`](struct.EntryCompletion.html), [`Entry`](struct.Entry.html), [`EventBox`](struct.EventBox.html), [`Expander`](struct.Expander.html), [`FileChooserButton`](struct.FileChooserButton.html), [`FileChooserDialog`](struct.FileChooserDialog.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FileFilter`](struct.FileFilter.html), [`Fixed`](struct.Fixed.html), [`FlowBoxChild`](struct.FlowBoxChild.html), [`FlowBox`](struct.FlowBox.html), [`FontButton`](struct.FontButton.html), [`FontChooserDialog`](struct.FontChooserDialog.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`Frame`](struct.Frame.html), [`GLArea`](struct.GLArea.html), [`Grid`](struct.Grid.html), [`HeaderBar`](struct.HeaderBar.html), [`IconView`](struct.IconView.html), [`Image`](struct.Image.html), [`InfoBar`](struct.InfoBar.html), [`Invisible`](struct.Invisible.html), [`Label`](struct.Label.html), [`Layout`](struct.Layout.html), [`LevelBar`](struct.LevelBar.html), [`LinkButton`](struct.LinkButton.html), [`ListBoxRow`](struct.ListBoxRow.html), [`ListBox`](struct.ListBox.html), [`ListStore`](struct.ListStore.html), [`LockButton`](struct.LockButton.html), [`MenuBar`](struct.MenuBar.html), [`MenuButton`](struct.MenuButton.html), [`MenuItem`](struct.MenuItem.html), [`MenuShell`](struct.MenuShell.html), [`MenuToolButton`](struct.MenuToolButton.html), [`Menu`](struct.Menu.html), [`MessageDialog`](struct.MessageDialog.html), [`Misc`](struct.Misc.html), [`ModelButton`](struct.ModelButton.html), [`Notebook`](struct.Notebook.html), [`OffscreenWindow`](struct.OffscreenWindow.html), [`Overlay`](struct.Overlay.html), [`Paned`](struct.Paned.html), [`PlacesSidebar`](struct.PlacesSidebar.html), [`Plug`](struct.Plug.html), [`PopoverMenu`](struct.PopoverMenu.html), [`Popover`](struct.Popover.html), [`ProgressBar`](struct.ProgressBar.html), [`RadioButton`](struct.RadioButton.html), [`RadioMenuItem`](struct.RadioMenuItem.html), [`RadioToolButton`](struct.RadioToolButton.html), [`Range`](struct.Range.html), [`RecentChooserDialog`](struct.RecentChooserDialog.html), [`RecentChooserMenu`](struct.RecentChooserMenu.html), [`RecentChooserWidget`](struct.RecentChooserWidget.html), [`RecentFilter`](struct.RecentFilter.html), [`Revealer`](struct.Revealer.html), [`ScaleButton`](struct.ScaleButton.html), [`Scale`](struct.Scale.html), [`Scrollbar`](struct.Scrollbar.html), [`ScrolledWindow`](struct.ScrolledWindow.html), [`SearchBar`](struct.SearchBar.html), [`SearchEntry`](struct.SearchEntry.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html), [`SeparatorToolItem`](struct.SeparatorToolItem.html), [`Separator`](struct.Separator.html), [`ShortcutLabel`](struct.ShortcutLabel.html), [`ShortcutsGroup`](struct.ShortcutsGroup.html), [`ShortcutsSection`](struct.ShortcutsSection.html), [`ShortcutsShortcut`](struct.ShortcutsShortcut.html), [`ShortcutsWindow`](struct.ShortcutsWindow.html), [`SizeGroup`](struct.SizeGroup.html), [`Socket`](struct.Socket.html), [`SpinButton`](struct.SpinButton.html), [`Spinner`](struct.Spinner.html), [`StackSidebar`](struct.StackSidebar.html), [`StackSwitcher`](struct.StackSwitcher.html), [`Stack`](struct.Stack.html), [`Statusbar`](struct.Statusbar.html), [`Switch`](struct.Switch.html), [`TextTagTable`](struct.TextTagTable.html), [`TextView`](struct.TextView.html), [`ToggleButton`](struct.ToggleButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html), [`ToolItemGroup`](struct.ToolItemGroup.html), [`ToolItem`](struct.ToolItem.html), [`ToolPalette`](struct.ToolPalette.html), [`Toolbar`](struct.Toolbar.html), [`TreeStore`](struct.TreeStore.html), [`TreeViewColumn`](struct.TreeViewColumn.html), [`TreeView`](struct.TreeView.html), [`Viewport`](struct.Viewport.html), [`VolumeButton`](struct.VolumeButton.html), [`Widget`](struct.Widget.html), [`Window`](struct.Window.html)
<!-- trait BuildableExt::fn add_child -->
Adds a child to `self`. `type_` is an optional string
describing how the child should be added.
## `builder`
a `Builder`
## `child`
child to add
## `type_`
kind of child or `None`
<!-- trait BuildableExt::fn construct_child -->
Constructs a child of `self` with the name `name`.

`Builder` calls this function if a “constructor” has been
specified in the UI definition.
## `builder`
`Builder` used to construct this object
## `name`
name of child to construct

# Returns

the constructed child
<!-- trait BuildableExt::fn custom_finished -->
This is similar to `Buildable::parser_finished` but is
called once for each custom tag handled by the `self`.
## `builder`
a `Builder`
## `child`
child object or `None` for non-child tags
## `tagname`
the name of the tag
## `data`
user data created in custom_tag_start
<!-- trait BuildableExt::fn custom_tag_end -->
This is called at the end of each custom element handled by
the buildable.
## `builder`
`Builder` used to construct this object
## `child`
child object or `None` for non-child tags
## `tagname`
name of tag
## `data`
user data that will be passed in to parser functions
<!-- trait BuildableExt::fn custom_tag_start -->
This is called for each unknown element under `<child>`.
## `builder`
a `Builder` used to construct this object
## `child`
child object or `None` for non-child tags
## `tagname`
name of tag
## `parser`
a `glib::MarkupParser` to fill in
## `data`
return location for user data that will be passed in
 to parser functions

# Returns

`true` if a object has a custom implementation, `false`
 if it doesn't.
<!-- trait BuildableExt::fn get_internal_child -->
Get the internal child called `childname` of the `self` object.
## `builder`
a `Builder`
## `childname`
name of child

# Returns

the internal child of the buildable object
<!-- trait BuildableExtManual::fn get_name -->
Gets the name of the `self` object.

`Builder` sets the name based on the
[`Builder` UI definition][BUILDER-UI]
used to construct the `self`.

# Returns

the name set with `Buildable::set_name`
<!-- trait BuildableExt::fn parser_finished -->
Called when the builder finishes the parsing of a
[`Builder` UI definition][BUILDER-UI].
Note that this will be called once for each time
`Builder::add_from_file` or `BuilderExt::add_from_string`
is called on a builder.
## `builder`
a `Builder`
<!-- trait BuildableExt::fn set_buildable_property -->
Sets the property name `name` to `value` on the `self` object.
## `builder`
a `Builder`
## `name`
name of property
## `value`
value of property
<!-- trait BuildableExtManual::fn set_name -->
Sets the name of the `self` object.
## `name`
name to set
<!-- struct Builder -->
A `Builder` is an auxiliary object that reads textual descriptions
of a user interface and instantiates the described objects. To create
a `Builder` from a user interface description, call
`Builder::new_from_file`, `Builder::new_from_resource` or
`Builder::new_from_string`.

In the (unusual) case that you want to add user interface
descriptions from multiple sources to the same `Builder` you can
call `Builder::new` to get an empty builder and populate it by
(multiple) calls to `Builder::add_from_file`,
`BuilderExt::add_from_resource` or `BuilderExt::add_from_string`.

A `Builder` holds a reference to all objects that it has constructed
and drops these references when it is finalized. This finalization can
cause the destruction of non-widget objects or widgets which are not
contained in a toplevel window. For toplevel windows constructed by a
builder, it is the responsibility of the user to call `Widget::destroy`
to get rid of them and all the widgets they contain.

The functions `Builder::get_object` and `BuilderExt::get_objects`
can be used to access the widgets in the interface by the names assigned
to them inside the UI description. Toplevel windows returned by these
functions will stay around until the user explicitly destroys them
with `Widget::destroy`. Other widgets will either be part of a
larger hierarchy constructed by the builder (in which case you should
not have to worry about their lifecycle), or without a parent, in which
case they have to be added to some container to make use of them.
Non-widget objects need to be reffed with `gobject::ObjectExt::ref` to keep them
beyond the lifespan of the builder.

The function `BuilderExt::connect_signals` and variants thereof can be
used to connect handlers to the named signals in the description.

# `Builder` UI Definitions # {`BUILDER`-UI}

`Builder` parses textual descriptions of user interfaces which are
specified in an XML format which can be roughly described by the
RELAX NG schema below. We refer to these descriptions as “`Builder`
UI definitions” or just “UI definitions” if the context is clear.
Do not confuse `Builder` UI Definitions with
[`UIManager` UI Definitions][XML-UI], which are more limited in scope.
It is common to use `.ui` as the filename extension for files containing
`Builder` UI definitions.

[RELAX NG Compact Syntax](https://git.gnome.org/browse/gtk+/tree/gtk/gtkbuilder.rnc)

The toplevel element is `<interface>`. It optionally takes a “domain”
attribute, which will make the builder look for translated strings
using `dgettext` in the domain specified. This can also be done by
calling `BuilderExt::set_translation_domain` on the builder.
Objects are described by `<object>` elements, which can contain
`<property>` elements to set properties, `<signal>` elements which
connect signals to handlers, and `<child>` elements, which describe
child objects (most often widgets inside a container, but also e.g.
actions in an action group, or columns in a tree model). A `<child>`
element contains an `<object>` element which describes the child object.
The target toolkit version(s) are described by `<requires>` elements,
the “lib” attribute specifies the widget library in question (currently
the only supported value is “gtk+”) and the “version” attribute specifies
the target version in the form “`<major>`.`<minor>`”. The builder will error
out if the version requirements are not met.

Typically, the specific kind of object represented by an `<object>`
element is specified by the “class” attribute. If the type has not
been loaded yet, GTK+ tries to find the `get_type` function from the
class name by applying heuristics. This works in most cases, but if
necessary, it is possible to specify the name of the `get_type` function
explictly with the "type-func" attribute. As a special case, `Builder`
allows to use an object that has been constructed by a `UIManager` in
another part of the UI definition by specifying the id of the `UIManager`
in the “constructor” attribute and the name of the object in the “id”
attribute.

Objects may be given a name with the “id” attribute, which allows the
application to retrieve them from the builder with `Builder::get_object`.
An id is also necessary to use the object as property value in other
parts of the UI definition. GTK+ reserves ids starting and ending
with ___ (3 underscores) for its own purposes.

Setting properties of objects is pretty straightforward with the
`<property>` element: the “name” attribute specifies the name of the
property, and the content of the element specifies the value.
If the “translatable” attribute is set to a true value, GTK+ uses
`gettext` (or `dgettext` if the builder has a translation domain set)
to find a translation for the value. This happens before the value
is parsed, so it can be used for properties of any type, but it is
probably most useful for string properties. It is also possible to
specify a context to disambiguate short strings, and comments which
may help the translators.

`Builder` can parse textual representations for the most common
property types: characters, strings, integers, floating-point numbers,
booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted
as `true`, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted
as `false`), enumerations (can be specified by their name, nick or
integer value), flags (can be specified by their name, nick, integer
value, optionally combined with “|”, e.g. “GTK_VISIBLE|GTK_REALIZED”)
and colors (in a format understood by `gdk::RGBA::parse`).

GVariants can be specified in the format understood by `glib::Variant::parse`,
and pixbufs can be specified as a filename of an image file to load.

Objects can be referred to by their name and by default refer to
objects declared in the local xml fragment and objects exposed via
`BuilderExt::expose_object`. In general, `Builder` allows forward
references to objects — declared in the local xml; an object doesn’t
have to be constructed before it can be referred to. The exception
to this rule is that an object has to be constructed before it can
be used as the value of a construct-only property.

It is also possible to bind a property value to another object's
property value using the attributes
"bind-source" to specify the source object of the binding,
"bind-property" to specify the source property and optionally
"bind-flags" to specify the binding flags.
Internally builder implements this using GBinding objects.
For more information see `gobject::ObjectExt::bind_property`

Signal handlers are set up with the `<signal>` element. The “name”
attribute specifies the name of the signal, and the “handler” attribute
specifies the function to connect to the signal. By default, GTK+ tries
to find the handler using `gmodule::Module::symbol`, but this can be changed by
passing a custom ``GtkBuilderConnectFunc`` to
`Builder::connect_signals_full`. The remaining attributes, “after”,
“swapped” and “object”, have the same meaning as the corresponding
parameters of the `g_signal_connect_object` or
`g_signal_connect_data` functions. A “last_modification_time”
attribute is also allowed, but it does not have a meaning to the
builder.

Sometimes it is necessary to refer to widgets which have implicitly
been constructed by GTK+ as part of a composite widget, to set
properties on them or to add further children (e.g. the `vbox` of
a `Dialog`). This can be achieved by setting the “internal-child”
property of the `<child>` element to a true value. Note that `Builder`
still requires an `<object>` element for the internal child, even if it
has already been constructed.

A number of widgets have different places where a child can be added
(e.g. tabs vs. page content in notebooks). This can be reflected in
a UI definition by specifying the “type” attribute on a `<child>`
The possible values for the “type” attribute are described in the
sections describing the widget-specific portions of UI definitions.

# A `Builder` UI Definition


```text
<interface>
  <object class="GtkDialog" id="dialog1">
    <child internal-child="vbox">
      <object class="GtkBox" id="vbox1">
        <property name="border-width">10</property>
        <child internal-child="action_area">
          <object class="GtkButtonBox" id="hbuttonbox1">
            <property name="border-width">20</property>
            <child>
              <object class="GtkButton" id="ok_button">
                <property name="label">gtk-ok</property>
                <property name="use-stock">TRUE</property>
                <signal name="clicked" handler="ok_button_clicked"/>
              </object>
            </child>
          </object>
        </child>
      </object>
    </child>
  </object>
</interface>
```

Beyond this general structure, several object classes define their
own XML DTD fragments for filling in the ANY placeholders in the DTD
above. Note that a custom element in a `<child>` element gets parsed by
the custom tag handler of the parent object, while a custom element in
an `<object>` element gets parsed by the custom tag handler of the object.

These XML fragments are explained in the documentation of the
respective objects.

Additionally, since 3.10 a special `<template>` tag has been added
to the format allowing one to define a widget class’s components.
See the [`Widget` documentation][composite-templates] for details.

# Implements

[`BuilderExt`](trait.BuilderExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuilderExtManual`](prelude/trait.BuilderExtManual.html)
<!-- trait BuilderExt -->
Trait containing all `Builder` methods.

# Implementors

[`Builder`](struct.Builder.html)
<!-- impl Builder::fn new -->
Creates a new empty builder object.

This function is only useful if you intend to make multiple calls
to `Builder::add_from_file`, `BuilderExt::add_from_resource`
or `BuilderExt::add_from_string` in order to merge multiple UI
descriptions into a single builder.

Most users will probably want to use `Builder::new_from_file`,
`Builder::new_from_resource` or `Builder::new_from_string`.

# Returns

a new (empty) `Builder` object
<!-- impl Builder::fn new_from_file -->
Builds the [`Builder` UI definition][BUILDER-UI]
in the file `filename`.

If there is an error opening the file or parsing the description then
the program will be aborted. You should only ever attempt to parse
user interface descriptions that are shipped as part of your program.
## `filename`
filename of user interface description file

# Returns

a `Builder` containing the described interface
<!-- impl Builder::fn new_from_resource -->
Builds the [`Builder` UI definition][BUILDER-UI]
at `resource_path`.

If there is an error locating the resource or parsing the
description, then the program will be aborted.
## `resource_path`
a `gio::Resource` resource path

# Returns

a `Builder` containing the described interface
<!-- impl Builder::fn new_from_string -->
Builds the user interface described by `string` (in the
[`Builder` UI definition][BUILDER-UI] format).

If `string` is `None`-terminated, then `length` should be -1.
If `length` is not -1, then it is the length of `string`.

If there is an error parsing `string` then the program will be
aborted. You should not attempt to parse user interface description
from untrusted sources.
## `string`
a user interface (XML) description
## `length`
the length of `string`, or -1

# Returns

a `Builder` containing the interface described by `string`
<!-- trait BuilderExt::fn add_callback_symbol -->
Adds the `callback_symbol` to the scope of `self` under the given `callback_name`.

Using this function overrides the behavior of `BuilderExt::connect_signals`
for any callback symbols that are added. Using this method allows for better
encapsulation as it does not require that callback symbols be declared in
the global namespace.
## `callback_name`
The name of the callback, as expected in the XML
## `callback_symbol`
The callback pointer
<!-- trait BuilderExt::fn add_callback_symbols -->
A convenience function to add many callbacks instead of calling
`BuilderExt::add_callback_symbol` for each symbol.
## `first_callback_name`
The name of the callback, as expected in the XML
## `first_callback_symbol`
The callback pointer
<!-- trait BuilderExtManual::fn add_from_file -->
Parses a file containing a [`Builder` UI definition][BUILDER-UI]
and merges it with the current contents of `self`.

Most users will probably want to use `Builder::new_from_file`.

If an error occurs, 0 will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_FILE_ERROR`
domain.

It’s not really reasonable to attempt to handle failures of this
call. You should not use this function with untrusted files (ie:
files that are not part of your application). Broken `Builder`
files can easily crash your program, and it’s possible that memory
was leaked leading up to the reported failure. The only reasonable
thing to do when an error is detected is to call `g_error`.
## `filename`
the name of the file to parse

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExt::fn add_from_resource -->
Parses a resource file containing a [`Builder` UI definition][BUILDER-UI]
and merges it with the current contents of `self`.

Most users will probably want to use `Builder::new_from_resource`.

If an error occurs, 0 will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_RESOURCE_ERROR`
domain.

It’s not really reasonable to attempt to handle failures of this
call. The only reasonable thing to do when an error is detected is
to call `g_error`.
## `resource_path`
the path of the resource file to parse

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExt::fn add_from_string -->
Parses a string containing a [`Builder` UI definition][BUILDER-UI]
and merges it with the current contents of `self`.

Most users will probably want to use `Builder::new_from_string`.

Upon errors 0 will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or
`G_VARIANT_PARSE_ERROR` domain.

It’s not really reasonable to attempt to handle failures of this
call. The only reasonable thing to do when an error is detected is
to call `g_error`.
## `buffer`
the string to parse
## `length`
the length of `buffer` (may be -1 if `buffer` is nul-terminated)

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExtManual::fn add_objects_from_file -->
Parses a file containing a [`Builder` UI definition][BUILDER-UI]
building only the requested objects and merges
them with the current contents of `self`.

Upon errors 0 will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_FILE_ERROR`
domain.

If you are adding an object that depends on an object that is not
its child (for instance a `TreeView` that depends on its
`TreeModel`), you have to explicitly list all of them in `object_ids`.
## `filename`
the name of the file to parse
## `object_ids`
nul-terminated array of objects to build

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExt::fn add_objects_from_resource -->
Parses a resource file containing a [`Builder` UI definition][BUILDER-UI]
building only the requested objects and merges
them with the current contents of `self`.

Upon errors 0 will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_RESOURCE_ERROR`
domain.

If you are adding an object that depends on an object that is not
its child (for instance a `TreeView` that depends on its
`TreeModel`), you have to explicitly list all of them in `object_ids`.
## `resource_path`
the path of the resource file to parse
## `object_ids`
nul-terminated array of objects to build

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExt::fn add_objects_from_string -->
Parses a string containing a [`Builder` UI definition][BUILDER-UI]
building only the requested objects and merges
them with the current contents of `self`.

Upon errors 0 will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR` or `G_MARKUP_ERROR` domain.

If you are adding an object that depends on an object that is not
its child (for instance a `TreeView` that depends on its
`TreeModel`), you have to explicitly list all of them in `object_ids`.
## `buffer`
the string to parse
## `length`
the length of `buffer` (may be -1 if `buffer` is nul-terminated)
## `object_ids`
nul-terminated array of objects to build

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExt::fn connect_signals -->
This method is a simpler variation of `Builder::connect_signals_full`.
It uses symbols explicitly added to `self` with prior calls to
`BuilderExt::add_callback_symbol`. In the case that symbols are not
explicitly added; it uses `gmodule::Module`’s introspective features (by opening the module `None`)
to look at the application’s symbol table. From here it tries to match
the signal handler names given in the interface description with
symbols in the application and connects the signals. Note that this
function can only be called once, subsequent calls will do nothing.

Note that unless `BuilderExt::add_callback_symbol` is called for
all signal callbacks which are referenced by the loaded XML, this
function will require that `gmodule::Module` be supported on the platform.

If you rely on `gmodule::Module` support to lookup callbacks in the symbol table,
the following details should be noted:

When compiling applications for Windows, you must declare signal callbacks
with `G_MODULE_EXPORT`, or they will not be put in the symbol table.
On Linux and Unices, this is not necessary; applications should instead
be compiled with the -Wl,--export-dynamic CFLAGS, and linked against
gmodule-export-2.0.
## `user_data`
user data to pass back with all signals
<!-- trait BuilderExt::fn connect_signals_full -->
This function can be thought of the interpreted language binding
version of `BuilderExt::connect_signals`, except that it does not
require GModule to function correctly.
## `func`
the function used to connect the signals
## `user_data`
arbitrary data that will be passed to the connection function
<!-- trait BuilderExt::fn expose_object -->
Add `object` to the `self` object pool so it can be referenced just like any
other object built by builder.
## `name`
the name of the object exposed to the builder
## `object`
the object to expose
<!-- trait BuilderExt::fn extend_with_template -->
Main private entry point for building composite container
components from template XML.

This is exported purely to let gtk-builder-tool validate
templates, applications have no need to call this function.
## `widget`
the widget that is being extended
## `template_type`
the type that the template is for
## `buffer`
the string to parse
## `length`
the length of `buffer` (may be -1 if `buffer` is nul-terminated)

# Returns

A positive value on success, 0 if an error occurred
<!-- trait BuilderExt::fn get_application -->
Gets the `Application` associated with the builder.

The `Application` is used for creating action proxies as requested
from XML that the builder is loading.

By default, the builder uses the default application: the one from
`gio::Application::get_default`. If you want to use another application
for constructing proxies, use `BuilderExt::set_application`.

# Returns

the application being used by the builder,
 or `None`
<!-- trait BuilderExtManual::fn get_object -->
Gets the object named `name`. Note that this function does not
increment the reference count of the returned object.
## `name`
name of object to get

# Returns

the object named `name` or `None` if
 it could not be found in the object tree.
<!-- trait BuilderExt::fn get_objects -->
Gets all objects that have been constructed by `self`. Note that
this function does not increment the reference counts of the returned
objects.

# Returns

a newly-allocated `glib::SList` containing all the objects
 constructed by the `Builder` instance. It should be freed by
 `glib::SList::free`
<!-- trait BuilderExt::fn get_translation_domain -->
Gets the translation domain of `self`.

# Returns

the translation domain. This string is owned
by the builder object and must not be modified or freed.
<!-- trait BuilderExt::fn get_type_from_name -->
Looks up a type by name, using the virtual function that
`Builder` has for that purpose. This is mainly used when
implementing the `Buildable` interface on a type.
## `type_name`
type name to lookup

# Returns

the `glib::Type` found for `type_name` or `G_TYPE_INVALID`
 if no type was found
<!-- trait BuilderExt::fn lookup_callback_symbol -->
Fetches a symbol previously added to `self`
with `BuilderExt::add_callback_symbols`

This function is intended for possible use in language bindings
or for any case that one might be cusomizing signal connections
using `Builder::connect_signals_full`
## `callback_name`
The name of the callback

# Returns

The callback symbol in `self` for `callback_name`, or `None`
<!-- trait BuilderExt::fn set_application -->
Sets the application associated with `self`.

You only need this function if there is more than one `gio::Application`
in your process. `application` cannot be `None`.
## `application`
a `Application`
<!-- trait BuilderExt::fn set_translation_domain -->
Sets the translation domain of `self`.
See `Builder:translation-domain`.
## `domain`
the translation domain or `None`
<!-- trait BuilderExt::fn value_from_string -->
This function demarshals a value from a string. This function
calls `gobject::Value::init` on the `value` argument, so it need not be
initialised beforehand.

This function can handle char, uchar, boolean, int, uint, long,
ulong, enum, flags, float, double, string, `gdk::Color`, `gdk::RGBA` and
`Adjustment` type values. Support for `Widget` type values is
still to come.

Upon errors `false` will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR` domain.
## `pspec`
the `gobject::ParamSpec` for the property
## `string`
the string representation of the value
## `value`
the `gobject::Value` to store the result in

# Returns

`true` on success
<!-- trait BuilderExt::fn value_from_string_type -->
Like `BuilderExt::value_from_string`, this function demarshals
a value from a string, but takes a `glib::Type` instead of `gobject::ParamSpec`.
This function calls `gobject::Value::init` on the `value` argument, so it
need not be initialised beforehand.

Upon errors `false` will be returned and `error` will be assigned a
`glib::Error` from the `GTK_BUILDER_ERROR` domain.
## `type_`
the `glib::Type` of the value
## `string`
the string representation of the value
## `value`
the `gobject::Value` to store the result in

# Returns

`true` on success
<!-- trait BuilderExt::fn get_property_translation_domain -->
The translation domain used when translating property values that
have been marked as translatable in interface descriptions.
If the translation domain is `None`, `Builder` uses `gettext`,
otherwise `g_dgettext`.
<!-- trait BuilderExt::fn set_property_translation_domain -->
The translation domain used when translating property values that
have been marked as translatable in interface descriptions.
If the translation domain is `None`, `Builder` uses `gettext`,
otherwise `g_dgettext`.
<!-- enum BuilderError -->
Error codes that identify various errors that can occur while using
`Builder`.
<!-- enum BuilderError::variant InvalidTypeFunction -->
A type-func attribute didn’t name
 a function that returns a `glib::Type`.
<!-- enum BuilderError::variant UnhandledTag -->
The input contained a tag that `Builder`
 can’t handle.
<!-- enum BuilderError::variant MissingAttribute -->
An attribute that is required by
 `Builder` was missing.
<!-- enum BuilderError::variant InvalidAttribute -->
`Builder` found an attribute that
 it doesn’t understand.
<!-- enum BuilderError::variant InvalidTag -->
`Builder` found a tag that
 it doesn’t understand.
<!-- enum BuilderError::variant MissingPropertyValue -->
A required property value was
 missing.
<!-- enum BuilderError::variant InvalidValue -->
`Builder` couldn’t parse
 some attribute value.
<!-- enum BuilderError::variant VersionMismatch -->
The input file requires a newer version
 of GTK+.
<!-- enum BuilderError::variant DuplicateId -->
An object id occurred twice.
<!-- enum BuilderError::variant ObjectTypeRefused -->
A specified object type is of the same type or
 derived from the type of the composite class being extended with builder XML.
<!-- enum BuilderError::variant TemplateMismatch -->
The wrong type was specified in a composite class’s template XML
<!-- enum BuilderError::variant InvalidProperty -->
The specified property is unknown for the object class.
<!-- enum BuilderError::variant InvalidSignal -->
The specified signal is unknown for the object class.
<!-- enum BuilderError::variant InvalidId -->
An object id is unknown
<!-- struct Button -->
The `Button` widget is generally used to trigger a callback function that is
called when the button is pressed. The various signals and how to use them
are outlined below.

The `Button` widget can hold any valid child widget. That is, it can hold
almost any other standard `Widget`. The most commonly used child is the
`Label`.

# CSS nodes

`Button` has a single CSS node with name button. The node will get the
style classes .image-button or .text-button, if the content is just an
image or label, respectively. It may also receive the .flat style class.

Other style classes that are commonly used with `Button` include
.suggested-action and .destructive-action. In special cases, buttons
can be made round by adding the .circular style class.

Button-like widgets like `ToggleButton`, `MenuButton`, `VolumeButton`,
`LockButton`, `ColorButton`, `FontButton` or `FileChooserButton` use
style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file
to differentiate themselves from a plain `Button`.

# Implements

[`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ButtonExt -->
Trait containing all `Button` methods.

# Implementors

[`Button`](struct.Button.html), [`ColorButton`](struct.ColorButton.html), [`FontButton`](struct.FontButton.html), [`LinkButton`](struct.LinkButton.html), [`LockButton`](struct.LockButton.html), [`ModelButton`](struct.ModelButton.html), [`ScaleButton`](struct.ScaleButton.html), [`ToggleButton`](struct.ToggleButton.html)
<!-- impl Button::fn new -->
Creates a new `Button` widget. To add a child widget to the button,
use `ContainerExt::add`.

# Returns

The newly created `Button` widget.
<!-- impl Button::fn new_from_icon_name -->
Creates a new button containing an icon from the current icon theme.

If the icon name isn’t known, a “broken image” icon will be
displayed instead. If the current icon theme is changed, the icon
will be updated appropriately.

This function is a convenience wrapper around `Button::new` and
`ButtonExt::set_image`.
## `icon_name`
an icon name or `None`
## `size`
an icon size (`IconSize`)

# Returns

a new `Button` displaying the themed icon
<!-- impl Button::fn new_with_label -->
Creates a `Button` widget with a `Label` child containing the given
text.
## `label`
The text you want the `Label` to hold.

# Returns

The newly created `Button` widget.
<!-- impl Button::fn new_with_mnemonic -->
Creates a new `Button` containing a label.
If characters in `label` are preceded by an underscore, they are underlined.
If you need a literal underscore character in a label, use “__” (two
underscores). The first underlined character represents a keyboard
accelerator called a mnemonic.
Pressing Alt and that key activates the button.
## `label`
The text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `Button`
<!-- trait ButtonExt::fn clicked -->
Emits a `Button::clicked` signal to the given `Button`.
<!-- trait ButtonExt::fn get_always_show_image -->
Returns whether the button will ignore the `Settings:gtk-button-images`
setting and always show the image, if available.

# Returns

`true` if the button will always show the image
<!-- trait ButtonExt::fn get_event_window -->
Returns the button’s event window if it is realized, `None` otherwise.
This function should be rarely needed.

# Returns

`self`’s event window.
<!-- trait ButtonExt::fn get_focus_on_click -->
Returns whether the button grabs focus when it is clicked with the mouse.
See `ButtonExt::set_focus_on_click`.

# Deprecated since 3.20

Use `WidgetExt::get_focus_on_click` instead

# Returns

`true` if the button grabs focus when it is clicked with
 the mouse.
<!-- trait ButtonExt::fn get_image -->
Gets the widget that is currenty set as the image of `self`.
This may have been explicitly set by `ButtonExt::set_image`
or constructed by `Button::new_from_stock`.

# Returns

a `Widget` or `None` in case
 there is no image
<!-- trait ButtonExt::fn get_image_position -->
Gets the position of the image relative to the text
inside the button.

# Returns

the position
<!-- trait ButtonExt::fn get_label -->
Fetches the text from the label of the button, as set by
`ButtonExt::set_label`. If the label text has not
been set the return value will be `None`. This will be the
case if you create an empty button with `Button::new` to
use as a container.

# Returns

The text of the label widget. This string is owned
by the widget and must not be modified or freed.
<!-- trait ButtonExt::fn get_relief -->
Returns the current relief style of the given `Button`.

# Returns

The current `ReliefStyle`
<!-- trait ButtonExt::fn get_use_underline -->
Returns whether an embedded underline in the button label indicates a
mnemonic. See gtk_button_set_use_underline ().

# Returns

`true` if an embedded underline in the button label
 indicates the mnemonic accelerator keys.
<!-- trait ButtonExt::fn set_always_show_image -->
If `true`, the button will ignore the `Settings:gtk-button-images`
setting and always show the image, if available.

Use this property if the button would be useless or hard to use
without the image.
## `always_show`
`true` if the menuitem should always show the image
<!-- trait ButtonExt::fn set_focus_on_click -->
Sets whether the button will 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.

# Deprecated since 3.20

Use `WidgetExt::set_focus_on_click` instead
## `focus_on_click`
whether the button grabs focus when clicked with the mouse
<!-- trait ButtonExt::fn set_image -->
Set the image of `self` to the given widget. The image will be
displayed if the label text is `None` or if
`Button:always-show-image` is `true`. You don’t have to call
`WidgetExt::show` on `image` yourself.
## `image`
a widget to set as the image for the button, or `None` to unset
<!-- trait ButtonExt::fn set_image_position -->
Sets the position of the image relative to the text
inside the button.
## `position`
the position
<!-- trait ButtonExt::fn set_label -->
Sets the text of the label of the button to `str`. This text is
also used to select the stock item if `Button::set_use_stock`
is used.

This will also clear any previously set labels.
## `label`
a string
<!-- trait ButtonExt::fn set_relief -->
Sets the relief style of the edges of the given `Button` widget.
Two styles exist, `ReliefStyle::Normal` and `ReliefStyle::None`.
The default style is, as one can guess, `ReliefStyle::Normal`.
The deprecated value `ReliefStyle::Half` behaves the same as
`ReliefStyle::Normal`.
## `relief`
The `ReliefStyle` as described above
<!-- trait ButtonExt::fn set_use_underline -->
If true, an underline in the text of the button label indicates
the next character should be used for the mnemonic accelerator key.
## `use_underline`
`true` if underlines in the text indicate mnemonics
<!-- trait ButtonExt::fn connect_activate -->
The ::activate signal on `Button` is an action signal and
emitting it causes the button to animate press then release.
Applications should never connect to this signal, but use the
`Button::clicked` signal.
<!-- trait ButtonExt::fn connect_clicked -->
Emitted when the button has been activated (pressed and released).
<!-- trait ButtonExt::fn get_property_always_show_image -->
If `true`, the button will ignore the `Settings:gtk-button-images`
setting and always show the image, if available.

Use this property if the button would be useless or hard to use
without the image.
<!-- trait ButtonExt::fn set_property_always_show_image -->
If `true`, the button will ignore the `Settings:gtk-button-images`
setting and always show the image, if available.

Use this property if the button would be useless or hard to use
without the image.
<!-- trait ButtonExt::fn get_property_image -->
The child widget to appear next to the button text.
<!-- trait ButtonExt::fn set_property_image -->
The child widget to appear next to the button text.
<!-- trait ButtonExt::fn get_property_image_position -->
The position of the image relative to the text inside the button.
<!-- trait ButtonExt::fn set_property_image_position -->
The position of the image relative to the text inside the button.
<!-- struct ButtonBox -->


# Implements

[`ButtonBoxExt`](trait.ButtonBoxExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ButtonBoxExt -->
Trait containing all `ButtonBox` methods.

# Implementors

[`ButtonBox`](struct.ButtonBox.html)
<!-- impl ButtonBox::fn new -->
Creates a new `ButtonBox`.
## `orientation`
the box's orientation.

# Returns

a new `ButtonBox`.
<!-- trait ButtonBoxExt::fn get_child_non_homogeneous -->
Returns whether the child is exempted from homogenous
sizing.
## `child`
a child of `self`

# Returns

`true` if the child is not subject to homogenous sizing
<!-- trait ButtonBoxExt::fn get_child_secondary -->
Returns whether `child` should appear in a secondary group of children.
## `child`
a child of `self`

# Returns

whether `child` should appear in a secondary group of children.
<!-- trait ButtonBoxExt::fn get_layout -->
Retrieves the method being used to arrange the buttons in a button box.

# Returns

the method used to lay out buttons in `self`.
<!-- trait ButtonBoxExt::fn set_child_non_homogeneous -->
Sets whether the child is exempted from homogeous sizing.
## `child`
a child of `self`
## `non_homogeneous`
the new value
<!-- trait ButtonBoxExt::fn set_child_secondary -->
Sets whether `child` should appear in a secondary group of children.
A typical use of a secondary child is the help button in a dialog.

This group appears after the other children if the style
is `ButtonBoxStyle::Start`, `ButtonBoxStyle::Spread` or
`ButtonBoxStyle::Edge`, and before the other children if the style
is `ButtonBoxStyle::End`. For horizontal button boxes, the definition
of before/after depends on direction of the widget (see
`WidgetExt::set_direction`). If the style is `ButtonBoxStyle::Start`
or `ButtonBoxStyle::End`, then the secondary children are aligned at
the other end of the button box from the main children. For the
other styles, they appear immediately next to the main children.
## `child`
a child of `self`
## `is_secondary`
if `true`, the `child` appears in a secondary group of the
 button box.
<!-- trait ButtonBoxExt::fn set_layout -->
Changes the way buttons are arranged in their container.
## `layout_style`
the new layout style
<!-- enum ButtonBoxStyle -->
Used to dictate the style that a `ButtonBox` uses to layout the buttons it
contains.
<!-- enum ButtonBoxStyle::variant Spread -->
Buttons are evenly spread across the box.
<!-- enum ButtonBoxStyle::variant Edge -->
Buttons are placed at the edges of the box.
<!-- enum ButtonBoxStyle::variant Start -->
Buttons are grouped towards the start of the box,
 (on the left for a HBox, or the top for a VBox).
<!-- enum ButtonBoxStyle::variant End -->
Buttons are grouped towards the end of the box,
 (on the right for a HBox, or the bottom for a VBox).
<!-- enum ButtonBoxStyle::variant Center -->
Buttons are centered in the box. Since 2.12.
<!-- enum ButtonBoxStyle::variant Expand -->
Buttons expand to fill the box. This entails giving
 buttons a "linked" appearance, making button sizes homogeneous, and
 setting spacing to 0 (same as calling `BoxExt::set_homogeneous` and
 `BoxExt::set_spacing` manually). Since 3.12.
<!-- enum ButtonRole -->
The role specifies the desired appearance of a `ModelButton`.
<!-- enum ButtonRole::variant Normal -->
A plain button
<!-- enum ButtonRole::variant Check -->
A check button
<!-- enum ButtonRole::variant Radio -->
A radio button

Feature: `v3_16`

<!-- enum ButtonsType -->
Prebuilt sets of buttons for the dialog. If
none of these choices are appropriate, simply use `ButtonsType::None`
then call `DialogExt::add_buttons`.

> Please note that `ButtonsType::Ok`, `ButtonsType::YesNo`
> and `ButtonsType::OkCancel` are discouraged by the
> [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/).
<!-- enum ButtonsType::variant None -->
no buttons at all
<!-- enum ButtonsType::variant Ok -->
an OK button
<!-- enum ButtonsType::variant Close -->
a Close button
<!-- enum ButtonsType::variant Cancel -->
a Cancel button
<!-- enum ButtonsType::variant YesNo -->
Yes and No buttons
<!-- enum ButtonsType::variant OkCancel -->
OK and Cancel buttons
<!-- struct Calendar -->
`Calendar` is a widget that displays a Gregorian calendar, one month
at a time. It can be created with `Calendar::new`.

The month and year currently displayed can be altered with
`CalendarExt::select_month`. The exact day can be selected from the
displayed month using `CalendarExt::select_day`.

To place a visual marker on a particular day, use `CalendarExt::mark_day`
and to remove the marker, `CalendarExt::unmark_day`. Alternative, all
marks can be cleared with `CalendarExt::clear_marks`.

The way in which the calendar itself is displayed can be altered using
`CalendarExt::set_display_options`.

The selected date can be retrieved from a `Calendar` using
`CalendarExt::get_date`.

Users should be aware that, although the Gregorian calendar is the
legal calendar in most countries, it was adopted progressively
between 1582 and 1929. Display before these dates is likely to be
historically incorrect.

# Implements

[`CalendarExt`](trait.CalendarExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait CalendarExt -->
Trait containing all `Calendar` methods.

# Implementors

[`Calendar`](struct.Calendar.html)
<!-- impl Calendar::fn new -->
Creates a new calendar, with the current date being selected.

# Returns

a newly `Calendar` widget
<!-- trait CalendarExt::fn clear_marks -->
Remove all visual markers.
<!-- trait CalendarExt::fn get_date -->
Obtains the selected date from a `Calendar`.
## `year`
location to store the year as a decimal
 number (e.g. 2011), or `None`
## `month`
location to store the month number
 (between 0 and 11), or `None`
## `day`
location to store the day number (between
 1 and 31), or `None`
<!-- trait CalendarExt::fn get_day_is_marked -->
Returns if the `day` of the `self` is already marked.
## `day`
the day number between 1 and 31.

# Returns

whether the day is marked.
<!-- trait CalendarExt::fn get_detail_height_rows -->
Queries the height of detail cells, in rows.
See `Calendar:detail-width-chars`.

# Returns

The height of detail cells, in rows.
<!-- trait CalendarExt::fn get_detail_width_chars -->
Queries the width of detail cells, in characters.
See `Calendar:detail-width-chars`.

# Returns

The width of detail cells, in characters.
<!-- trait CalendarExt::fn get_display_options -->
Returns the current display options of `self`.

# Returns

the display options.
<!-- trait CalendarExt::fn mark_day -->
Places a visual marker on a particular day.
## `day`
the day number to mark between 1 and 31.
<!-- trait CalendarExt::fn select_day -->
Selects a day from the current month.
## `day`
the day number between 1 and 31, or 0 to unselect
 the currently selected day.
<!-- trait CalendarExt::fn select_month -->
Shifts the calendar to a different month.
## `month`
a month number between 0 and 11.
## `year`
the year the month is in.
<!-- trait CalendarExt::fn set_detail_func -->
Installs a function which provides Pango markup with detail information
for each day. Examples for such details are holidays or appointments. That
information is shown below each day when `Calendar:show-details` is set.
A tooltip containing with full detail information is provided, if the entire
text should not fit into the details area, or if `Calendar:show-details`
is not set.

The size of the details area can be restricted by setting the
`Calendar:detail-width-chars` and `Calendar:detail-height-rows`
properties.
## `func`
a function providing details for each day.
## `data`
data to pass to `func` invokations.
## `destroy`
a function for releasing `data`.
<!-- trait CalendarExt::fn set_detail_height_rows -->
Updates the height of detail cells.
See `Calendar:detail-height-rows`.
## `rows`
detail height in rows.
<!-- trait CalendarExt::fn set_detail_width_chars -->
Updates the width of detail cells.
See `Calendar:detail-width-chars`.
## `chars`
detail width in characters.
<!-- trait CalendarExt::fn set_display_options -->
Sets display options (whether to display the heading and the month
headings).
## `flags`
the display options to set
<!-- trait CalendarExt::fn unmark_day -->
Removes the visual marker from a particular day.
## `day`
the day number to unmark between 1 and 31.
<!-- trait CalendarExt::fn connect_day_selected -->
Emitted when the user selects a day.
<!-- trait CalendarExt::fn connect_day_selected_double_click -->
Emitted when the user double-clicks a day.
<!-- trait CalendarExt::fn connect_month_changed -->
Emitted when the user clicks a button to change the selected month on a
calendar.
<!-- trait CalendarExt::fn connect_next_month -->
Emitted when the user switched to the next month.
<!-- trait CalendarExt::fn connect_next_year -->
Emitted when user switched to the next year.
<!-- trait CalendarExt::fn connect_prev_month -->
Emitted when the user switched to the previous month.
<!-- trait CalendarExt::fn connect_prev_year -->
Emitted when user switched to the previous year.
<!-- trait CalendarExt::fn get_property_day -->
The selected day (as a number between 1 and 31, or 0
to unselect the currently selected day).
This property gets initially set to the current day.
<!-- trait CalendarExt::fn set_property_day -->
The selected day (as a number between 1 and 31, or 0
to unselect the currently selected day).
This property gets initially set to the current day.
<!-- trait CalendarExt::fn get_property_detail_height_rows -->
Height of a detail cell, in rows.
A value of 0 allows any width. See `CalendarExt::set_detail_func`.
<!-- trait CalendarExt::fn set_property_detail_height_rows -->
Height of a detail cell, in rows.
A value of 0 allows any width. See `CalendarExt::set_detail_func`.
<!-- trait CalendarExt::fn get_property_detail_width_chars -->
Width of a detail cell, in characters.
A value of 0 allows any width. See `CalendarExt::set_detail_func`.
<!-- trait CalendarExt::fn set_property_detail_width_chars -->
Width of a detail cell, in characters.
A value of 0 allows any width. See `CalendarExt::set_detail_func`.
<!-- trait CalendarExt::fn get_property_month -->
The selected month (as a number between 0 and 11).
This property gets initially set to the current month.
<!-- trait CalendarExt::fn set_property_month -->
The selected month (as a number between 0 and 11).
This property gets initially set to the current month.
<!-- trait CalendarExt::fn get_property_no_month_change -->
Determines whether the selected month can be changed.
<!-- trait CalendarExt::fn set_property_no_month_change -->
Determines whether the selected month can be changed.
<!-- trait CalendarExt::fn get_property_show_day_names -->
Determines whether day names are displayed.
<!-- trait CalendarExt::fn set_property_show_day_names -->
Determines whether day names are displayed.
<!-- trait CalendarExt::fn get_property_show_details -->
Determines whether details are shown directly in the widget, or if they are
available only as tooltip. When this property is set days with details are
marked.
<!-- trait CalendarExt::fn set_property_show_details -->
Determines whether details are shown directly in the widget, or if they are
available only as tooltip. When this property is set days with details are
marked.
<!-- trait CalendarExt::fn get_property_show_heading -->
Determines whether a heading is displayed.
<!-- trait CalendarExt::fn set_property_show_heading -->
Determines whether a heading is displayed.
<!-- trait CalendarExt::fn get_property_show_week_numbers -->
Determines whether week numbers are displayed.
<!-- trait CalendarExt::fn set_property_show_week_numbers -->
Determines whether week numbers are displayed.
<!-- trait CalendarExt::fn get_property_year -->
The selected year.
This property gets initially set to the current year.
<!-- trait CalendarExt::fn set_property_year -->
The selected year.
This property gets initially set to the current year.
<!-- struct CalendarDisplayOptions -->
These options can be used to influence the display and behaviour of a `Calendar`.
<!-- struct CalendarDisplayOptions::const SHOW_HEADING -->
Specifies that the month and year should be displayed.
<!-- struct CalendarDisplayOptions::const SHOW_DAY_NAMES -->
Specifies that three letter day descriptions should be present.
<!-- struct CalendarDisplayOptions::const NO_MONTH_CHANGE -->
Prevents the user from switching months with the calendar.
<!-- struct CalendarDisplayOptions::const SHOW_WEEK_NUMBERS -->
Displays each week numbers of the current year, down the
left side of the calendar.
<!-- struct CalendarDisplayOptions::const SHOW_DETAILS -->
Just show an indicator, not the full details
text when details are provided. See `CalendarExt::set_detail_func`.
<!-- struct CellArea -->
The `CellArea` is an abstract class for `CellLayout` widgets
(also referred to as "layouting widgets") to interface with an
arbitrary number of ``GtkCellRenderers`` and interact with the user
for a given `TreeModel` row.

The cell area handles events, focus navigation, drawing and
size requests and allocations for a given row of data.

Usually users dont have to interact with the `CellArea` directly
unless they are implementing a cell-layouting widget themselves.

# Requesting area sizes

As outlined in
[`Widget`’s geometry management section][geometry-management],
GTK+ uses a height-for-width
geometry management system to compute the sizes of widgets and user
interfaces. `CellArea` uses the same semantics to calculate the
size of an area for an arbitrary number of `TreeModel` rows.

When requesting the size of a cell area one needs to calculate
the size for a handful of rows, and this will be done differently by
different layouting widgets. For instance a `TreeViewColumn`
always lines up the areas from top to bottom while a `IconView`
on the other hand might enforce that all areas received the same
width and wrap the areas around, requesting height for more cell
areas when allocated less width.

It’s also important for areas to maintain some cell
alignments with areas rendered for adjacent rows (cells can
appear “columnized” inside an area even when the size of
cells are different in each row). For this reason the `CellArea`
uses a `CellAreaContext` object to store the alignments
and sizes along the way (as well as the overall largest minimum
and natural size for all the rows which have been calculated
with the said context).

The `CellAreaContext` is an opaque object specific to the
`CellArea` which created it (see `CellAreaExt::create_context`).
The owning cell-layouting widget can create as many contexts as
it wishes to calculate sizes of rows which should receive the
same size in at least one orientation (horizontally or vertically),
However, it’s important that the same `CellAreaContext` which
was used to request the sizes for a given `TreeModel` row be
used when rendering or processing events for that row.

In order to request the width of all the rows at the root level
of a `TreeModel` one would do the following:


```C
GtkTreeIter iter;
gint        minimum_width;
gint        natural_width;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL);

    valid = gtk_tree_model_iter_next (model, &iter);
  }
gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);
```

Note that in this example it’s not important to observe the
returned minimum and natural width of the area for each row
unless the cell-layouting object is actually interested in the
widths of individual rows. The overall width is however stored
in the accompanying `CellAreaContext` object and can be consulted
at any time.

This can be useful since `CellLayout` widgets usually have to
support requesting and rendering rows in treemodels with an
exceedingly large amount of rows. The `CellLayout` widget in
that case would calculate the required width of the rows in an
idle or timeout source (see `g_timeout_add`) and when the widget
is requested its actual width in `WidgetClass.get_preferred_width`()
it can simply consult the width accumulated so far in the
`CellAreaContext` object.

A simple example where rows are rendered from top to bottom and
take up the full width of the layouting widget would look like:


```C
static void
foo_get_preferred_width (GtkWidget       *widget,
                         gint            *minimum_size,
                         gint            *natural_size)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;

  foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo);

  gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size);
}
```

In the above example the Foo widget has to make sure that some
row sizes have been calculated (the amount of rows that Foo judged
was appropriate to request space for in a single timeout iteration)
before simply returning the amount of space required by the area via
the `CellAreaContext`.

Requesting the height for width (or width for height) of an area is
a similar task except in this case the `CellAreaContext` does not
store the data (actually, it does not know how much space the layouting
widget plans to allocate it for every row. It’s up to the layouting
widget to render each row of data with the appropriate height and
width which was requested by the `CellArea`).

In order to request the height for width of all the rows at the
root level of a `TreeModel` one would do the following:


```C
GtkTreeIter iter;
gint        minimum_height;
gint        natural_height;
gint        full_minimum_height = 0;
gint        full_natural_height = 0;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    gtk_cell_area_get_preferred_height_for_width (area, context, widget,
                                                  width, &minimum_height, &natural_height);

    if (width_is_for_allocation)
       cache_row_height (&iter, minimum_height, natural_height);

    full_minimum_height += minimum_height;
    full_natural_height += natural_height;

    valid = gtk_tree_model_iter_next (model, &iter);
  }
```

Note that in the above example we would need to cache the heights
returned for each row so that we would know what sizes to render the
areas for each row. However we would only want to really cache the
heights if the request is intended for the layouting widgets real
allocation.

In some cases the layouting widget is requested the height for an
arbitrary for_width, this is a special case for layouting widgets
who need to request size for tens of thousands of rows. For this
case it’s only important that the layouting widget calculate
one reasonably sized chunk of rows and return that height
synchronously. The reasoning here is that any layouting widget is
at least capable of synchronously calculating enough height to fill
the screen height (or scrolled window height) in response to a single
call to `WidgetClass.get_preferred_height_for_width`(). Returning
a perfect height for width that is larger than the screen area is
inconsequential since after the layouting receives an allocation
from a scrolled window it simply continues to drive the scrollbar
values while more and more height is required for the row heights
that are calculated in the background.

# Rendering Areas

Once area sizes have been aquired at least for the rows in the
visible area of the layouting widget they can be rendered at
`WidgetClass.draw`() time.

A crude example of how to render all the rows at the root level
runs as follows:


```C
GtkAllocation allocation;
GdkRectangle  cell_area = { 0, };
GtkTreeIter   iter;
gint          minimum_width;
gint          natural_width;

gtk_widget_get_allocation (widget, &allocation);
cell_area.width = allocation.width;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    cell_area.height = get_cached_height_for_row (&iter);

    gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    gtk_cell_area_render (area, context, widget, cr,
                          &cell_area, &cell_area, state_flags, FALSE);

    cell_area.y += cell_area.height;

    valid = gtk_tree_model_iter_next (model, &iter);
  }
```

Note that the cached height in this example really depends on how
the layouting widget works. The layouting widget might decide to
give every row its minimum or natural height or, if the model content
is expected to fit inside the layouting widget without scrolling, it
would make sense to calculate the allocation for each row at
`Widget::size-allocate` time using `gtk_distribute_natural_allocation`.

# Handling Events and Driving Keyboard Focus

Passing events to the area is as simple as handling events on any
normal widget and then passing them to the `CellAreaExt::event`
API as they come in. Usually `CellArea` is only interested in
button events, however some customized derived areas can be implemented
who are interested in handling other events. Handling an event can
trigger the `CellArea::focus-changed` signal to fire; as well as
`CellArea::add-editable` in the case that an editable cell was
clicked and needs to start editing. You can call
`CellAreaExt::stop_editing` at any time to cancel any cell editing
that is currently in progress.

The `CellArea` drives keyboard focus from cell to cell in a way
similar to `Widget`. For layouting widgets that support giving
focus to cells it’s important to remember to pass `CellRendererState::Focused`
to the area functions for the row that has focus and to tell the
area to paint the focus at render time.

Layouting widgets that accept focus on cells should implement the
`WidgetClass.focus`() virtual method. The layouting widget is always
responsible for knowing where `TreeModel` rows are rendered inside
the widget, so at `WidgetClass.focus`() time the layouting widget
should use the `CellArea` methods to navigate focus inside the area
and then observe the `DirectionType` to pass the focus to adjacent
rows and areas.

A basic example of how the `WidgetClass.focus`() virtual method
should be implemented:


```C
static gboolean
foo_focus (GtkWidget       *widget,
           GtkDirectionType direction)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;
  gint        focus_row;
  gboolean    have_focus = FALSE;

  focus_row = priv->focus_row;

  if (!gtk_widget_has_focus (widget))
    gtk_widget_grab_focus (widget);

  valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row);
  while (valid)
    {
      gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE);

      if (gtk_cell_area_focus (priv->area, direction))
        {
           priv->focus_row = focus_row;
           have_focus = TRUE;
           break;
        }
      else
        {
          if (direction == GTK_DIR_RIGHT ||
              direction == GTK_DIR_LEFT)
            break;
          else if (direction == GTK_DIR_UP ||
                   direction == GTK_DIR_TAB_BACKWARD)
           {
              if (focus_row == 0)
                break;
              else
               {
                  focus_row--;
                  valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row);
               }
            }
          else
            {
              if (focus_row == last_row)
                break;
              else
                {
                  focus_row++;
                  valid = gtk_tree_model_iter_next (priv->model, &iter);
                }
            }
        }
    }
    return have_focus;
}
```

Note that the layouting widget is responsible for matching the
`DirectionType` values to the way it lays out its cells.

# Cell Properties

The `CellArea` introduces cell properties for ``GtkCellRenderers``
in very much the same way that `Container` introduces
[child properties][child-properties]
for ``GtkWidgets``. This provides some general interfaces for defining
the relationship cell areas have with their cells. For instance in a
`CellAreaBox` a cell might “expand” and receive extra space when
the area is allocated more than its full natural request, or a cell
might be configured to “align” with adjacent rows which were requested
and rendered with the same `CellAreaContext`.

Use `CellAreaClass::install_cell_property` to install cell
properties for a cell area class and `CellAreaClass::find_cell_property`
or `CellAreaClass::list_cell_properties` to get information about
existing cell properties.

To set the value of a cell property, use `CellAreaExt::cell_set_property`,
`CellAreaExt::cell_set` or `CellAreaExt::cell_set_valist`. To obtain
the value of a cell property, use `CellAreaExt::cell_get_property`,
`CellAreaExt::cell_get` or `CellAreaExt::cell_get_valist`.

# Implements

[`CellAreaExt`](trait.CellAreaExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait CellAreaExt -->
Trait containing all `CellArea` methods.

# Implementors

[`CellAreaBox`](struct.CellAreaBox.html), [`CellArea`](struct.CellArea.html)
<!-- trait CellAreaExt::fn activate -->
Activates `self`, usually by activating the currently focused
cell, however some subclasses which embed widgets in the area
can also activate a widget if it currently has the focus.
## `context`
the `CellAreaContext` in context with the current row data
## `widget`
the `Widget` that `self` is rendering on
## `cell_area`
the size and location of `self` relative to `widget`’s allocation
## `flags`
the `CellRendererState` flags for `self` for this row of data.
## `edit_only`
if `true` then only cell renderers that are `CellRendererMode::Editable`
 will be activated.

# Returns

Whether `self` was successfully activated.
<!-- trait CellAreaExt::fn activate_cell -->
This is used by `CellArea` subclasses when handling events
to activate cells, the base `CellArea` class activates cells
for keyboard events for free in its own `CellArea`->`activate`
implementation.
## `widget`
the `Widget` that `self` is rendering onto
## `renderer`
the `CellRenderer` in `self` to activate
## `event`
the ``GdkEvent`` for which cell activation should occur
## `cell_area`
the `gdk::Rectangle` in `widget` relative coordinates
 of `renderer` for the current row.
## `flags`
the `CellRendererState` for `renderer`

# Returns

whether cell activation was successful
<!-- trait CellAreaExt::fn add -->
Adds `renderer` to `self` with the default child cell properties.
## `renderer`
the `CellRenderer` to add to `self`
<!-- trait CellAreaExt::fn add_focus_sibling -->
Adds `sibling` to `renderer`’s focusable area, focus will be drawn
around `renderer` and all of its siblings if `renderer` can
focus for a given row.

Events handled by focus siblings can also activate the given
focusable `renderer`.
## `renderer`
the `CellRenderer` expected to have focus
## `sibling`
the `CellRenderer` to add to `renderer`’s focus area
<!-- trait CellAreaExt::fn add_with_properties -->
Adds `renderer` to `self`, setting cell properties at the same time.
See `CellAreaExt::add` and `CellAreaExt::cell_set` for more details.
## `renderer`
a `CellRenderer` to be placed inside `self`
## `first_prop_name`
the name of the first cell property to set
<!-- trait CellAreaExt::fn apply_attributes -->
Applies any connected attributes to the renderers in
`self` by pulling the values from `tree_model`.
## `tree_model`
the `TreeModel` to pull values from
## `iter`
the `TreeIter` in `tree_model` to apply values for
## `is_expander`
whether `iter` has children
## `is_expanded`
whether `iter` is expanded in the view and
 children are visible
<!-- trait CellAreaExt::fn attribute_connect -->
Connects an `attribute` to apply values from `column` for the
`TreeModel` in use.
## `renderer`
the `CellRenderer` to connect an attribute for
## `attribute`
the attribute name
## `column`
the `TreeModel` column to fetch attribute values from
<!-- trait CellAreaExt::fn attribute_disconnect -->
Disconnects `attribute` for the `renderer` in `self` so that
attribute will no longer be updated with values from the
model.
## `renderer`
the `CellRenderer` to disconnect an attribute for
## `attribute`
the attribute name
<!-- trait CellAreaExt::fn attribute_get_column -->
Returns the model column that an attribute has been mapped to,
or -1 if the attribute is not mapped.
## `renderer`
a `CellRenderer`
## `attribute`
an attribute on the renderer

# Returns

the model column, or -1
<!-- trait CellAreaExt::fn cell_get -->
Gets the values of one or more cell properties for `renderer` in `self`.
## `renderer`
a `CellRenderer` which is inside `self`
## `first_prop_name`
the name of the first cell property to get
<!-- trait CellAreaExt::fn cell_get_property -->
Gets the value of a cell property for `renderer` in `self`.
## `renderer`
a `CellRenderer` inside `self`
## `property_name`
the name of the property to get
## `value`
a location to return the value
<!-- trait CellAreaExt::fn cell_get_valist -->
Gets the values of one or more cell properties for `renderer` in `self`.
## `renderer`
a `CellRenderer` inside `self`
## `first_property_name`
the name of the first property to get
## `var_args`
return location for the first property, followed
 optionally by more name/return location pairs, followed by `None`
<!-- trait CellAreaExt::fn cell_set -->
Sets one or more cell properties for `cell` in `self`.
## `renderer`
a `CellRenderer` which is a cell inside `self`
## `first_prop_name`
the name of the first cell property to set
<!-- trait CellAreaExt::fn cell_set_property -->
Sets a cell property for `renderer` in `self`.
## `renderer`
a `CellRenderer` inside `self`
## `property_name`
the name of the cell property to set
## `value`
the value to set the cell property to
<!-- trait CellAreaExt::fn cell_set_valist -->
Sets one or more cell properties for `renderer` in `self`.
## `renderer`
a `CellRenderer` which inside `self`
## `first_property_name`
the name of the first cell property to set
## `var_args`
a `None`-terminated list of property names and values, starting
 with `first_prop_name`
<!-- trait CellAreaExt::fn copy_context -->
This is sometimes needed for cases where rows need to share
alignments in one orientation but may be separately grouped
in the opposing orientation.

For instance, `IconView` creates all icons (rows) to have
the same width and the cells theirin to have the same
horizontal alignments. However each row of icons may have
a separate collective height. `IconView` uses this to
request the heights of each row based on a context which
was already used to request all the row widths that are
to be displayed.
## `context`
the `CellAreaContext` to copy

# Returns

a newly created `CellAreaContext` copy of `context`.
<!-- trait CellAreaExt::fn create_context -->
Creates a `CellAreaContext` to be used with `self` for
all purposes. `CellAreaContext` stores geometry information
for rows for which it was operated on, it is important to use
the same context for the same row of data at all times (i.e.
one should render and handle events with the same `CellAreaContext`
which was used to request the size of those rows of data).

# Returns

a newly created `CellAreaContext` which can be used with `self`.
<!-- trait CellAreaExt::fn event -->
Delegates event handling to a `CellArea`.
## `context`
the `CellAreaContext` for this row of data.
## `widget`
the `Widget` that `self` is rendering to
## `event`
the ``GdkEvent`` to handle
## `cell_area`
the `widget` relative coordinates for `self`
## `flags`
the `CellRendererState` for `self` in this row.

# Returns

`true` if the event was handled by `self`.
<!-- trait CellAreaExt::fn focus -->
This should be called by the `self`’s owning layout widget
when focus is to be passed to `self`, or moved within `self`
for a given `direction` and row data.

Implementing `CellArea` classes should implement this
method to receive and navigate focus in its own way particular
to how it lays out cells.
## `direction`
the `DirectionType`

# Returns

`true` if focus remains inside `self` as a result of this call.
<!-- trait CellAreaExt::fn foreach -->
Calls `callback` for every `CellRenderer` in `self`.
## `callback`
the ``GtkCellCallback`` to call
## `callback_data`
user provided data pointer
<!-- trait CellAreaExt::fn foreach_alloc -->
Calls `callback` for every `CellRenderer` in `self` with the
allocated rectangle inside `cell_area`.
## `context`
the `CellAreaContext` for this row of data.
## `widget`
the `Widget` that `self` is rendering to
## `cell_area`
the `widget` relative coordinates and size for `self`
## `background_area`
the `widget` relative coordinates of the background area
## `callback`
the ``GtkCellAllocCallback`` to call
## `callback_data`
user provided data pointer
<!-- trait CellAreaExt::fn get_cell_allocation -->
Derives the allocation of `renderer` inside `self` if `self`
were to be renderered in `cell_area`.
## `context`
the `CellAreaContext` used to hold sizes for `self`.
## `widget`
the `Widget` that `self` is rendering on
## `renderer`
the `CellRenderer` to get the allocation for
## `cell_area`
the whole allocated area for `self` in `widget`
 for this row
## `allocation`
where to store the allocation for `renderer`
<!-- trait CellAreaExt::fn get_cell_at_position -->
Gets the `CellRenderer` at `x` and `y` coordinates inside `self` and optionally
returns the full cell allocation for it inside `cell_area`.
## `context`
the `CellAreaContext` used to hold sizes for `self`.
## `widget`
the `Widget` that `self` is rendering on
## `cell_area`
the whole allocated area for `self` in `widget`
 for this row
## `x`
the x position
## `y`
the y position
## `alloc_area`
where to store the inner allocated area of the
 returned cell renderer, or `None`.

# Returns

the `CellRenderer` at `x` and `y`.
<!-- trait CellAreaExt::fn get_current_path_string -->
Gets the current `TreePath` string for the currently
applied `TreeIter`, this is implicitly updated when
`CellAreaExt::apply_attributes` is called and can be
used to interact with renderers from `CellArea`
subclasses.

# Returns

The current `TreePath` string for the current
attributes applied to `self`. This string belongs to the area and
should not be freed.
<!-- trait CellAreaExt::fn get_edit_widget -->
Gets the `CellEditable` widget currently used
to edit the currently edited cell.

# Returns

The currently active `CellEditable` widget
<!-- trait CellAreaExt::fn get_edited_cell -->
Gets the `CellRenderer` in `self` that is currently
being edited.

# Returns

The currently edited `CellRenderer`
<!-- trait CellAreaExt::fn get_focus_cell -->
Retrieves the currently focused cell for `self`

# Returns

the currently focused cell in `self`.
<!-- trait CellAreaExt::fn get_focus_from_sibling -->
Gets the `CellRenderer` which is expected to be focusable
for which `renderer` is, or may be a sibling.

This is handy for `CellArea` subclasses when handling events,
after determining the renderer at the event location it can
then chose to activate the focus cell for which the event
cell may have been a sibling.
## `renderer`
the `CellRenderer`

# Returns

the `CellRenderer` for which `renderer`
 is a sibling, or `None`.
<!-- trait CellAreaExt::fn get_focus_siblings -->
Gets the focus sibling cell renderers for `renderer`.
## `renderer`
the `CellRenderer` expected to have focus

# Returns

A `glib::List` of ``GtkCellRenderers``.
 The returned list is internal and should not be freed.
<!-- trait CellAreaExt::fn get_preferred_height -->
Retrieves a cell area’s initial minimum and natural height.

`self` will store some geometrical information in `context` along the way;
when requesting sizes over an arbitrary number of rows, it’s not important
to check the `minimum_height` and `natural_height` of this call but rather to
consult `CellAreaContextExt::get_preferred_height` after a series of
requests.
## `context`
the `CellAreaContext` to perform this request with
## `widget`
the `Widget` where `self` will be rendering
## `minimum_height`
location to store the minimum height, or `None`
## `natural_height`
location to store the natural height, or `None`
<!-- trait CellAreaExt::fn get_preferred_height_for_width -->
Retrieves a cell area’s minimum and natural height if it would be given
the specified `width`.

`self` stores some geometrical information in `context` along the way
while calling `CellAreaExt::get_preferred_width`. It’s important to
perform a series of `CellAreaExt::get_preferred_width` requests with
`context` first and then call `CellAreaExt::get_preferred_height_for_width`
on each cell area individually to get the height for width of each
fully requested row.

If at some point, the width of a single row changes, it should be
requested with `CellAreaExt::get_preferred_width` again and then
the full width of the requested rows checked again with
`CellAreaContextExt::get_preferred_width`.
## `context`
the `CellAreaContext` which has already been requested for widths.
## `widget`
the `Widget` where `self` will be rendering
## `width`
the width for which to check the height of this area
## `minimum_height`
location to store the minimum height, or `None`
## `natural_height`
location to store the natural height, or `None`
<!-- trait CellAreaExt::fn get_preferred_width -->
Retrieves a cell area’s initial minimum and natural width.

`self` will store some geometrical information in `context` along the way;
when requesting sizes over an arbitrary number of rows, it’s not important
to check the `minimum_width` and `natural_width` of this call but rather to
consult `CellAreaContextExt::get_preferred_width` after a series of
requests.
## `context`
the `CellAreaContext` to perform this request with
## `widget`
the `Widget` where `self` will be rendering
## `minimum_width`
location to store the minimum width, or `None`
## `natural_width`
location to store the natural width, or `None`
<!-- trait CellAreaExt::fn get_preferred_width_for_height -->
Retrieves a cell area’s minimum and natural width if it would be given
the specified `height`.

`self` stores some geometrical information in `context` along the way
while calling `CellAreaExt::get_preferred_height`. It’s important to
perform a series of `CellAreaExt::get_preferred_height` requests with
`context` first and then call `CellAreaExt::get_preferred_width_for_height`
on each cell area individually to get the height for width of each
fully requested row.

If at some point, the height of a single row changes, it should be
requested with `CellAreaExt::get_preferred_height` again and then
the full height of the requested rows checked again with
`CellAreaContextExt::get_preferred_height`.
## `context`
the `CellAreaContext` which has already been requested for widths.
## `widget`
the `Widget` where `self` will be rendering
## `height`
the height for which to check the width of this area
## `minimum_width`
location to store the minimum width, or `None`
## `natural_width`
location to store the natural width, or `None`
<!-- trait CellAreaExt::fn get_request_mode -->
Gets whether the area prefers a height-for-width layout
or a width-for-height layout.

# Returns

The `SizeRequestMode` preferred by `self`.
<!-- trait CellAreaExt::fn has_renderer -->
Checks if `self` contains `renderer`.
## `renderer`
the `CellRenderer` to check

# Returns

`true` if `renderer` is in the `self`.
<!-- trait CellAreaExt::fn inner_cell_area -->
This is a convenience function for `CellArea` implementations
to get the inner area where a given `CellRenderer` will be
rendered. It removes any padding previously added by `CellAreaExt::request_renderer`.
## `widget`
the `Widget` that `self` is rendering onto
## `cell_area`
the `widget` relative coordinates where one of `self`’s cells
 is to be placed
## `inner_area`
the return location for the inner cell area
<!-- trait CellAreaExt::fn is_activatable -->
Returns whether the area can do anything when activated,
after applying new attributes to `self`.

# Returns

whether `self` can do anything when activated.
<!-- trait CellAreaExt::fn is_focus_sibling -->
Returns whether `sibling` is one of `renderer`’s focus siblings
(see `CellAreaExt::add_focus_sibling`).
## `renderer`
the `CellRenderer` expected to have focus
## `sibling`
the `CellRenderer` to check against `renderer`’s sibling list

# Returns

`true` if `sibling` is a focus sibling of `renderer`
<!-- trait CellAreaExt::fn remove -->
Removes `renderer` from `self`.
## `renderer`
the `CellRenderer` to remove from `self`
<!-- trait CellAreaExt::fn remove_focus_sibling -->
Removes `sibling` from `renderer`’s focus sibling list
(see `CellAreaExt::add_focus_sibling`).
## `renderer`
the `CellRenderer` expected to have focus
## `sibling`
the `CellRenderer` to remove from `renderer`’s focus area
<!-- trait CellAreaExt::fn render -->
Renders `self`’s cells according to `self`’s layout onto `widget` at
the given coordinates.
## `context`
the `CellAreaContext` for this row of data.
## `widget`
the `Widget` that `self` is rendering to
## `cr`
the `cairo::Context` to render with
## `background_area`
the `widget` relative coordinates for `self`’s background
## `cell_area`
the `widget` relative coordinates for `self`
## `flags`
the `CellRendererState` for `self` in this row.
## `paint_focus`
whether `self` should paint focus on focused cells for focused rows or not.
<!-- trait CellAreaExt::fn request_renderer -->
This is a convenience function for `CellArea` implementations
to request size for cell renderers. It’s important to use this
function to request size and then use `CellAreaExt::inner_cell_area`
at render and event time since this function will add padding
around the cell for focus painting.
## `renderer`
the `CellRenderer` to request size for
## `orientation`
the `Orientation` in which to request size
## `widget`
the `Widget` that `self` is rendering onto
## `for_size`
the allocation contextual size to request for, or -1 if
the base request for the orientation is to be returned.
## `minimum_size`
location to store the minimum size, or `None`
## `natural_size`
location to store the natural size, or `None`
<!-- trait CellAreaExt::fn set_focus_cell -->
Explicitly sets the currently focused cell to `renderer`.

This is generally called by implementations of
`CellAreaClass.focus`() or `CellAreaClass.event`(),
however it can also be used to implement functions such
as `TreeViewExt::set_cursor_on_cell`.
## `renderer`
the `CellRenderer` to give focus to
<!-- trait CellAreaExt::fn stop_editing -->
Explicitly stops the editing of the currently edited cell.

If `canceled` is `true`, the currently edited cell renderer
will emit the ::editing-canceled signal, otherwise the
the ::editing-done signal will be emitted on the current
edit widget.

See `CellAreaExt::get_edited_cell` and `CellAreaExt::get_edit_widget`.
## `canceled`
whether editing was canceled.
<!-- trait CellAreaExt::fn connect_add_editable -->
Indicates that editing has started on `renderer` and that `editable`
should be added to the owning cell-layouting widget at `cell_area`.
## `renderer`
the `CellRenderer` that started the edited
## `editable`
the `CellEditable` widget to add
## `cell_area`
the `Widget` relative `gdk::Rectangle` coordinates
 where `editable` should be added
## `path`
the `TreePath` string this edit was initiated for
<!-- trait CellAreaExt::fn connect_apply_attributes -->
This signal is emitted whenever applying attributes to `area` from `model`
## `model`
the `TreeModel` to apply the attributes from
## `iter`
the `TreeIter` indicating which row to apply the attributes of
## `is_expander`
whether the view shows children for this row
## `is_expanded`
whether the view is currently showing the children of this row
<!-- trait CellAreaExt::fn connect_focus_changed -->
Indicates that focus changed on this `area`. This signal
is emitted either as a result of focus handling or event
handling.

It's possible that the signal is emitted even if the
currently focused renderer did not change, this is
because focus may change to the same renderer in the
same cell area for a different row of data.
## `renderer`
the `CellRenderer` that has focus
## `path`
the current `TreePath` string set for `area`
<!-- trait CellAreaExt::fn connect_remove_editable -->
Indicates that editing finished on `renderer` and that `editable`
should be removed from the owning cell-layouting widget.
## `renderer`
the `CellRenderer` that finished editeding
## `editable`
the `CellEditable` widget to remove
<!-- trait CellAreaExt::fn get_property_edit_widget -->
The widget currently editing the edited cell

This property is read-only and only changes as
a result of a call `CellAreaExt::activate_cell`.
<!-- trait CellAreaExt::fn get_property_edited_cell -->
The cell in the area that is currently edited

This property is read-only and only changes as
a result of a call `CellAreaExt::activate_cell`.
<!-- trait CellAreaExt::fn get_property_focus_cell -->
The cell in the area that currently has focus
<!-- trait CellAreaExt::fn set_property_focus_cell -->
The cell in the area that currently has focus
<!-- struct CellAreaBox -->
The `CellAreaBox` renders cell renderers into a row or a column
depending on its `Orientation`.

`CellAreaBox` uses a notion of packing. Packing
refers to adding cell renderers with reference to a particular position
in a `CellAreaBox`. There are two reference positions: the
start and the end of the box.
When the `CellAreaBox` is oriented in the `Orientation::Vertical`
orientation, the start is defined as the top of the box and the end is
defined as the bottom. In the `Orientation::Horizontal` orientation
start is defined as the left side and the end is defined as the right
side.

Alignments of ``GtkCellRenderers`` rendered in adjacent rows can be
configured by configuring the `CellAreaBox` align child cell property
with `CellAreaExt::cell_set_property` or by specifying the "align"
argument to `CellAreaBoxExt::pack_start` and `CellAreaBoxExt::pack_end`.

# Implements

[`CellAreaBoxExt`](trait.CellAreaBoxExt.html), [`CellAreaExt`](trait.CellAreaExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`OrientableExt`](trait.OrientableExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait CellAreaBoxExt -->
Trait containing all `CellAreaBox` methods.

# Implementors

[`CellAreaBox`](struct.CellAreaBox.html)
<!-- impl CellAreaBox::fn new -->
Creates a new `CellAreaBox`.

# Returns

a newly created `CellAreaBox`
<!-- trait CellAreaBoxExt::fn get_spacing -->
Gets the spacing added between cell renderers.

# Returns

the space added between cell renderers in `self`.
<!-- trait CellAreaBoxExt::fn pack_end -->
Adds `renderer` to `self`, packed with reference to the end of `self`.

The `renderer` is packed after (away from end of) any other
`CellRenderer` packed with reference to the end of `self`.
## `renderer`
the `CellRenderer` to add
## `expand`
whether `renderer` should receive extra space when the area receives
more than its natural size
## `align`
whether `renderer` should be aligned in adjacent rows
## `fixed`
whether `renderer` should have the same size in all rows
<!-- trait CellAreaBoxExt::fn pack_start -->
Adds `renderer` to `self`, packed with reference to the start of `self`.

The `renderer` is packed after any other `CellRenderer` packed
with reference to the start of `self`.
## `renderer`
the `CellRenderer` to add
## `expand`
whether `renderer` should receive extra space when the area receives
more than its natural size
## `align`
whether `renderer` should be aligned in adjacent rows
## `fixed`
whether `renderer` should have the same size in all rows
<!-- trait CellAreaBoxExt::fn set_spacing -->
Sets the spacing to add between cell renderers in `self`.
## `spacing`
the space to add between ``GtkCellRenderers``
<!-- trait CellAreaBoxExt::fn get_property_spacing -->
The amount of space to reserve between cells.
<!-- trait CellAreaBoxExt::fn set_property_spacing -->
The amount of space to reserve between cells.
<!-- struct CellAreaContext -->
The `CellAreaContext` object is created by a given `CellArea`
implementation via its `CellAreaClass.create_context`() virtual
method and is used to store cell sizes and alignments for a series of
`TreeModel` rows that are requested and rendered in the same context.

`CellLayout` widgets can create any number of contexts in which to
request and render groups of data rows. However, it’s important that the
same context which was used to request sizes for a given `TreeModel`
row also be used for the same row when calling other `CellArea` APIs
such as `CellAreaExt::render` and `CellAreaExt::event`.

# Implements

[`CellAreaContextExt`](trait.CellAreaContextExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellAreaContextExt -->
Trait containing all `CellAreaContext` methods.

# Implementors

[`CellAreaContext`](struct.CellAreaContext.html)
<!-- trait CellAreaContextExt::fn allocate -->
Allocates a width and/or a height for all rows which are to be
rendered with `self`.

Usually allocation is performed only horizontally or sometimes
vertically since a group of rows are usually rendered side by
side vertically or horizontally and share either the same width
or the same height. Sometimes they are allocated in both horizontal
and vertical orientations producing a homogeneous effect of the
rows. This is generally the case for `TreeView` when
`TreeView:fixed-height-mode` is enabled.

Since 3.0
## `width`
the allocated width for all `TreeModel` rows rendered
 with `self`, or -1.
## `height`
the allocated height for all `TreeModel` rows rendered
 with `self`, or -1.
<!-- trait CellAreaContextExt::fn get_allocation -->
Fetches the current allocation size for `self`.

If the context was not allocated in width or height, or if the
context was recently reset with `CellAreaContextExt::reset`,
the returned value will be -1.
## `width`
location to store the allocated width, or `None`
## `height`
location to store the allocated height, or `None`
<!-- trait CellAreaContextExt::fn get_area -->
Fetches the `CellArea` this `self` was created by.

This is generally unneeded by layouting widgets; however,
it is important for the context implementation itself to
fetch information about the area it is being used for.

For instance at `CellAreaContextClass.allocate`() time
it’s important to know details about any cell spacing
that the `CellArea` is configured with in order to
compute a proper allocation.

# Returns

the `CellArea` this context was created by.
<!-- trait CellAreaContextExt::fn get_preferred_height -->
Gets the accumulative preferred height for all rows which have been
requested with this context.

After `CellAreaContextExt::reset` is called and/or before ever
requesting the size of a `CellArea`, the returned values are 0.
## `minimum_height`
location to store the minimum height,
 or `None`
## `natural_height`
location to store the natural height,
 or `None`
<!-- trait CellAreaContextExt::fn get_preferred_height_for_width -->
Gets the accumulative preferred height for `width` for all rows
which have been requested for the same said `width` with this context.

After `CellAreaContextExt::reset` is called and/or before ever
requesting the size of a `CellArea`, the returned values are -1.
## `width`
a proposed width for allocation
## `minimum_height`
location to store the minimum height,
 or `None`
## `natural_height`
location to store the natural height,
 or `None`
<!-- trait CellAreaContextExt::fn get_preferred_width -->
Gets the accumulative preferred width for all rows which have been
requested with this context.

After `CellAreaContextExt::reset` is called and/or before ever
requesting the size of a `CellArea`, the returned values are 0.
## `minimum_width`
location to store the minimum width,
 or `None`
## `natural_width`
location to store the natural width,
 or `None`
<!-- trait CellAreaContextExt::fn get_preferred_width_for_height -->
Gets the accumulative preferred width for `height` for all rows which
have been requested for the same said `height` with this context.

After `CellAreaContextExt::reset` is called and/or before ever
requesting the size of a `CellArea`, the returned values are -1.
## `height`
a proposed height for allocation
## `minimum_width`
location to store the minimum width,
 or `None`
## `natural_width`
location to store the natural width,
 or `None`
<!-- trait CellAreaContextExt::fn push_preferred_height -->
Causes the minimum and/or natural height to grow if the new
proposed sizes exceed the current minimum and natural height.

This is used by `CellAreaContext` implementations during
the request process over a series of `TreeModel` rows to
progressively push the requested height over a series of
`CellAreaExt::get_preferred_height` requests.
## `minimum_height`
the proposed new minimum height for `self`
## `natural_height`
the proposed new natural height for `self`
<!-- trait CellAreaContextExt::fn push_preferred_width -->
Causes the minimum and/or natural width to grow if the new
proposed sizes exceed the current minimum and natural width.

This is used by `CellAreaContext` implementations during
the request process over a series of `TreeModel` rows to
progressively push the requested width over a series of
`CellAreaExt::get_preferred_width` requests.
## `minimum_width`
the proposed new minimum width for `self`
## `natural_width`
the proposed new natural width for `self`
<!-- trait CellAreaContextExt::fn reset -->
Resets any previously cached request and allocation
data.

When underlying `TreeModel` data changes its
important to reset the context if the content
size is allowed to shrink. If the content size
is only allowed to grow (this is usually an option
for views rendering large data stores as a measure
of optimization), then only the row that changed
or was inserted needs to be (re)requested with
`CellAreaExt::get_preferred_width`.

When the new overall size of the context requires
that the allocated size changes (or whenever this
allocation changes at all), the variable row
sizes need to be re-requested for every row.

For instance, if the rows are displayed all with
the same width from top to bottom then a change
in the allocated width necessitates a recalculation
of all the displayed row heights using
`CellAreaExt::get_preferred_height_for_width`.

Since 3.0
<!-- trait CellAreaContextExt::fn get_property_area -->
The `CellArea` this context was created by
<!-- trait CellAreaContextExt::fn set_property_area -->
The `CellArea` this context was created by
<!-- trait CellAreaContextExt::fn get_property_minimum_height -->
The minimum height for the `CellArea` in this context
for all `TreeModel` rows that this context was requested
for using `CellAreaExt::get_preferred_height`.
<!-- trait CellAreaContextExt::fn get_property_minimum_width -->
The minimum width for the `CellArea` in this context
for all `TreeModel` rows that this context was requested
for using `CellAreaExt::get_preferred_width`.
<!-- trait CellAreaContextExt::fn get_property_natural_height -->
The natural height for the `CellArea` in this context
for all `TreeModel` rows that this context was requested
for using `CellAreaExt::get_preferred_height`.
<!-- trait CellAreaContextExt::fn get_property_natural_width -->
The natural width for the `CellArea` in this context
for all `TreeModel` rows that this context was requested
for using `CellAreaExt::get_preferred_width`.
<!-- struct CellEditable -->
The `CellEditable` interface must be implemented for widgets to be usable
to edit the contents of a `TreeView` cell. It provides a way to specify how
temporary widgets should be configured for editing, get the new value, etc.

# Implements

[`CellEditableExt`](trait.CellEditableExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait CellEditableExt -->
Trait containing all `CellEditable` methods.

# Implementors

[`AppChooserButton`](struct.AppChooserButton.html), [`CellEditable`](struct.CellEditable.html), [`ComboBoxText`](struct.ComboBoxText.html), [`ComboBox`](struct.ComboBox.html), [`Entry`](struct.Entry.html), [`SearchEntry`](struct.SearchEntry.html), [`SpinButton`](struct.SpinButton.html)
<!-- trait CellEditableExt::fn editing_done -->
Emits the `CellEditable::editing-done` signal.
<!-- trait CellEditableExt::fn remove_widget -->
Emits the `CellEditable::remove-widget` signal.
<!-- trait CellEditableExt::fn start_editing -->
Begins editing on a `self`.

The `CellRenderer` for the cell creates and returns a `CellEditable` from
`CellRendererExt::start_editing`, configured for the `CellRenderer` type.

`CellEditable::start_editing` can then set up `self` suitably for
editing a cell, e.g. making the Esc key emit `CellEditable::editing-done`.

Note that the `self` is created on-demand for the current edit; its
lifetime is temporary and does not persist across other edits and/or cells.
## `event`
The ``GdkEvent`` that began the editing process, or
 `None` if editing was initiated programmatically
<!-- trait CellEditableExt::fn connect_editing_done -->
This signal is a sign for the cell renderer to update its
value from the `cell_editable`.

Implementations of `CellEditable` are responsible for
emitting this signal when they are done editing, e.g.
`Entry` emits this signal when the user presses Enter. Typical things to
do in a handler for ::editing-done are to capture the edited value,
disconnect the `cell_editable` from signals on the `CellRenderer`, etc.

`CellEditable::editing_done` is a convenience method
for emitting `CellEditable::editing-done`.
<!-- trait CellEditableExt::fn connect_remove_widget -->
This signal is meant to indicate that the cell is finished
editing, and the `cell_editable` widget is being removed and may
subsequently be destroyed.

Implementations of `CellEditable` are responsible for
emitting this signal when they are done editing. It must
be emitted after the `CellEditable::editing-done` signal,
to give the cell renderer a chance to update the cell's value
before the widget is removed.

`CellEditable::remove_widget` is a convenience method
for emitting `CellEditable::remove-widget`.
<!-- trait CellEditableExt::fn get_property_editing_canceled -->
Indicates whether editing on the cell has been canceled.
<!-- trait CellEditableExt::fn set_property_editing_canceled -->
Indicates whether editing on the cell has been canceled.
<!-- struct CellLayout -->
`CellLayout` is an interface to be implemented by all objects which
want to provide a `TreeViewColumn` like API for packing cells,
setting attributes and data funcs.

One of the notable features provided by implementations of
`CellLayout` are attributes. Attributes let you set the properties
in flexible ways. They can just be set to constant values like regular
properties. But they can also be mapped to a column of the underlying
tree model with `CellLayout::set_attributes`, which means that the value
of the attribute can change from cell to cell as they are rendered by
the cell renderer. Finally, it is possible to specify a function with
`CellLayout::set_cell_data_func` that is called to determine the
value of the attribute for each cell that is rendered.

# `GtkCellLayouts` as `Buildable`

Implementations of `CellLayout` which also implement the `Buildable`
interface (`CellView`, `IconView`, `ComboBox`,
`EntryCompletion`, `TreeViewColumn`) accept `CellRenderer` objects
as `<child>` elements in UI definitions. They support a custom `<attributes>`
element for their children, which can contain multiple `<attribute>`
elements. Each `<attribute>` element has a name attribute which specifies
a property of the cell renderer; the content of the element is the
attribute value.

This is an example of a UI definition fragment specifying attributes:

```C
combo = g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL);
```

to use a custom cell area with a combo box. But construct properties
are only initialized after instance `init`
functions have run, which means that using functions which rely on
the existence of the cell area in your subclass’ `init` function will
cause the default cell area to be instantiated. In this case, a provided
construct property value will be ignored (with a warning, to alert
you to the problem).


```C
static void
my_combo_box_init (MyComboBox *b)
{
  GtkCellRenderer *cell;

  cell = gtk_cell_renderer_pixbuf_new ();
  // The following call causes the default cell area for combo boxes,
  // a GtkCellAreaBox, to be instantiated
  gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE);
  ...
}

GtkWidget *
my_combo_box_new (GtkCellArea *area)
{
  // This call is going to cause a warning about area being ignored
  return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL);
}
```

If supporting alternative cell areas with your derived widget is
not important, then this does not have to concern you. If you want
to support alternative cell areas, you can do so by moving the
problematic calls out of `init` and into a `constructor`
for your class.

# Implements

[`CellLayoutExt`](trait.CellLayoutExt.html)
<!-- trait CellLayoutExt -->
Trait containing all `CellLayout` methods.

# Implementors

[`AppChooserButton`](struct.AppChooserButton.html), [`CellAreaBox`](struct.CellAreaBox.html), [`CellArea`](struct.CellArea.html), [`CellLayout`](struct.CellLayout.html), [`CellView`](struct.CellView.html), [`ComboBoxText`](struct.ComboBoxText.html), [`ComboBox`](struct.ComboBox.html), [`EntryCompletion`](struct.EntryCompletion.html), [`IconView`](struct.IconView.html), [`TreeViewColumn`](struct.TreeViewColumn.html)
<!-- trait CellLayoutExt::fn add_attribute -->
Adds an attribute mapping to the list in `self`.

The `column` is the column of the model to get a value from, and the
`attribute` is the parameter on `cell` to be set from the value. So for
example if column 2 of the model contains strings, you could have the
“text” attribute of a `CellRendererText` get its values from column 2.
## `cell`
a `CellRenderer`
## `attribute`
an attribute on the renderer
## `column`
the column position on the model to get the attribute from
<!-- trait CellLayoutExt::fn clear -->
Unsets all the mappings on all renderers on `self` and
removes all renderers from `self`.
<!-- trait CellLayoutExt::fn clear_attributes -->
Clears all existing attributes previously set with
`CellLayout::set_attributes`.
## `cell`
a `CellRenderer` to clear the attribute mapping on
<!-- trait CellLayoutExt::fn get_area -->
Returns the underlying `CellArea` which might be `self`
if called on a `CellArea` or might be `None` if no `CellArea`
is used by `self`.

# Returns

the cell area used by `self`,
or `None` in case no cell area is used.
<!-- trait CellLayoutExt::fn get_cells -->
Returns the cell renderers which have been added to `self`.

# Returns


 a list of cell renderers. The list, but not the renderers has
 been newly allocated and should be freed with `glib::List::free`
 when no longer needed.
<!-- trait CellLayoutExt::fn pack_end -->
Adds the `cell` to the end of `self`. If `expand` is `false`, then the
`cell` is allocated no more space than it needs. Any unused space is
divided evenly between cells for which `expand` is `true`.

Note that reusing the same cell renderer is not supported.
## `cell`
a `CellRenderer`
## `expand`
`true` if `cell` is to be given extra space allocated to `self`
<!-- trait CellLayoutExt::fn pack_start -->
Packs the `cell` into the beginning of `self`. If `expand` is `false`,
then the `cell` is allocated no more space than it needs. Any unused space
is divided evenly between cells for which `expand` is `true`.

Note that reusing the same cell renderer is not supported.
## `cell`
a `CellRenderer`
## `expand`
`true` if `cell` is to be given extra space allocated to `self`
<!-- trait CellLayoutExt::fn reorder -->
Re-inserts `cell` at `position`.

Note that `cell` has already to be packed into `self`
for this to function properly.
## `cell`
a `CellRenderer` to reorder
## `position`
new position to insert `cell` at
<!-- trait CellLayoutExt::fn set_attributes -->
Sets the attributes in list as the attributes of `self`.

The attributes should be in attribute/column order, as in
`CellLayout::add_attribute`. All existing attributes are
removed, and replaced with the new attributes.
## `cell`
a `CellRenderer`
<!-- trait CellLayoutExt::fn set_cell_data_func -->
Sets the ``GtkCellLayoutDataFunc`` to use for `self`.

This function is used instead of the standard attributes mapping
for setting the column value, and should set the value of `self`’s
cell renderer(s) as appropriate.

`func` may be `None` to remove a previously set function.
## `cell`
a `CellRenderer`
## `func`
the ``GtkCellLayoutDataFunc`` to use, or `None`
## `func_data`
user data for `func`
## `destroy`
destroy notify for `func_data`
<!-- struct CellRenderer -->
The `CellRenderer` is a base class of a set of objects used for
rendering a cell to a `cairo::Context`. These objects are used primarily by
the `TreeView` widget, though they aren’t tied to them in any
specific way. It is worth noting that `CellRenderer` is not a
`Widget` and cannot be treated as such.

The primary use of a `CellRenderer` is for drawing a certain graphical
elements on a `cairo::Context`. Typically, one cell renderer is used to
draw many cells on the screen. To this extent, it isn’t expected that a
CellRenderer keep any permanent state around. Instead, any state is set
just prior to use using `GObjects` property system. Then, the
cell is measured using `CellRenderer::get_size`. Finally, the cell
is rendered in the correct location using `CellRendererExt::render`.

There are a number of rules that must be followed when writing a new
`CellRenderer`. First and foremost, it’s important that a certain set
of properties will always yield a cell renderer of the same size,
barring a `Style` change. The `CellRenderer` also has a number of
generic properties that are expected to be honored by all children.

Beyond merely rendering a cell, cell renderers can optionally
provide active user interface elements. A cell renderer can be
“activatable” like `CellRendererToggle`,
which toggles when it gets activated by a mouse click, or it can be
“editable” like `CellRendererText`, which
allows the user to edit the text using a widget implementing the
`CellEditable` interface, e.g. `Entry`.
To make a cell renderer activatable or editable, you have to
implement the `CellRendererClass.activate` or
`CellRendererClass.start_editing` virtual functions, respectively.

Many properties of `CellRenderer` and its subclasses have a
corresponding “set” property, e.g. “cell-background-set” corresponds
to “cell-background”. These “set” properties reflect whether a property
has been set or not. You should not set them independently.

# Implements

[`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererExt -->
Trait containing all `CellRenderer` methods.

# Implementors

[`CellRendererPixbuf`](struct.CellRendererPixbuf.html), [`CellRendererProgress`](struct.CellRendererProgress.html), [`CellRendererSpinner`](struct.CellRendererSpinner.html), [`CellRendererText`](struct.CellRendererText.html), [`CellRendererToggle`](struct.CellRendererToggle.html), [`CellRenderer`](struct.CellRenderer.html)
<!-- trait CellRendererExt::fn activate -->
Passes an activate event to the cell renderer for possible processing.
Some cell renderers may use events; for example, `CellRendererToggle`
toggles when it gets a mouse click.
## `event`
a ``GdkEvent``
## `widget`
widget that received the event
## `path`
widget-dependent string representation of the event location;
 e.g. for `TreeView`, a string representation of `TreePath`
## `background_area`
background area as passed to `CellRendererExt::render`
## `cell_area`
cell area as passed to `CellRendererExt::render`
## `flags`
render flags

# Returns

`true` if the event was consumed/handled
<!-- trait CellRendererExt::fn get_aligned_area -->
Gets the aligned area used by `self` inside `cell_area`. Used for finding
the appropriate edit and focus rectangle.
## `widget`
the `Widget` this cell will be rendering to
## `flags`
render flags
## `cell_area`
cell area which would be passed to `CellRendererExt::render`
## `aligned_area`
the return location for the space inside `cell_area`
 that would acually be used to render.
<!-- trait CellRendererExt::fn get_alignment -->
Fills in `xalign` and `yalign` with the appropriate values of `self`.
## `xalign`
location to fill in with the x alignment of the cell, or `None`
## `yalign`
location to fill in with the y alignment of the cell, or `None`
<!-- trait CellRendererExt::fn get_fixed_size -->
Fills in `width` and `height` with the appropriate size of `self`.
## `width`
location to fill in with the fixed width of the cell, or `None`
## `height`
location to fill in with the fixed height of the cell, or `None`
<!-- trait CellRendererExt::fn get_padding -->
Fills in `xpad` and `ypad` with the appropriate values of `self`.
## `xpad`
location to fill in with the x padding of the cell, or `None`
## `ypad`
location to fill in with the y padding of the cell, or `None`
<!-- trait CellRendererExt::fn get_preferred_height -->
Retreives a renderer’s natural size when rendered to `widget`.
## `widget`
the `Widget` this cell will be rendering to
## `minimum_size`
location to store the minimum size, or `None`
## `natural_size`
location to store the natural size, or `None`
<!-- trait CellRendererExt::fn get_preferred_height_for_width -->
Retreives a cell renderers’s minimum and natural height if it were rendered to
`widget` with the specified `width`.
## `widget`
the `Widget` this cell will be rendering to
## `width`
the size which is available for allocation
## `minimum_height`
location for storing the minimum size, or `None`
## `natural_height`
location for storing the preferred size, or `None`
<!-- trait CellRendererExt::fn get_preferred_size -->
Retrieves the minimum and natural size of a cell taking
into account the widget’s preference for height-for-width management.
## `widget`
the `Widget` this cell will be rendering to
## `minimum_size`
location for storing the minimum size, or `None`
## `natural_size`
location for storing the natural size, or `None`
<!-- trait CellRendererExt::fn get_preferred_width -->
Retreives a renderer’s natural size when rendered to `widget`.
## `widget`
the `Widget` this cell will be rendering to
## `minimum_size`
location to store the minimum size, or `None`
## `natural_size`
location to store the natural size, or `None`
<!-- trait CellRendererExt::fn get_preferred_width_for_height -->
Retreives a cell renderers’s minimum and natural width if it were rendered to
`widget` with the specified `height`.
## `widget`
the `Widget` this cell will be rendering to
## `height`
the size which is available for allocation
## `minimum_width`
location for storing the minimum size, or `None`
## `natural_width`
location for storing the preferred size, or `None`
<!-- trait CellRendererExt::fn get_request_mode -->
Gets whether the cell renderer prefers a height-for-width layout
or a width-for-height layout.

# Returns

The `SizeRequestMode` preferred by this renderer.
<!-- trait CellRendererExt::fn get_sensitive -->
Returns the cell renderer’s sensitivity.

# Returns

`true` if the cell renderer is sensitive
<!-- trait CellRendererExt::fn get_state -->
Translates the cell renderer state to `StateFlags`,
based on the cell renderer and widget sensitivity, and
the given `CellRendererState`.
## `widget`
a `Widget`, or `None`
## `cell_state`
cell renderer state

# Returns

the widget state flags applying to `self`
<!-- trait CellRendererExt::fn get_visible -->
Returns the cell renderer’s visibility.

# Returns

`true` if the cell renderer is visible
<!-- trait CellRendererExt::fn is_activatable -->
Checks whether the cell renderer can do something when activated.

# Returns

`true` if the cell renderer can do anything when activated
<!-- trait CellRendererExt::fn render -->
Invokes the virtual render function of the `CellRenderer`. The three
passed-in rectangles are areas in `cr`. Most renderers will draw within
`cell_area`; the xalign, yalign, xpad, and ypad fields of the `CellRenderer`
should be honored with respect to `cell_area`. `background_area` includes the
blank space around the cell, and also the area containing the tree expander;
so the `background_area` rectangles for all cells tile to cover the entire
`window`.
## `cr`
a cairo context to draw to
## `widget`
the widget owning `window`
## `background_area`
entire cell area (including tree expanders and maybe
 padding on the sides)
## `cell_area`
area normally rendered by a cell renderer
## `flags`
flags that affect rendering
<!-- trait CellRendererExt::fn set_alignment -->
Sets the renderer’s alignment within its available space.
## `xalign`
the x alignment of the cell renderer
## `yalign`
the y alignment of the cell renderer
<!-- trait CellRendererExt::fn set_fixed_size -->
Sets the renderer size to be explicit, independent of the properties set.
## `width`
the width of the cell renderer, or -1
## `height`
the height of the cell renderer, or -1
<!-- trait CellRendererExt::fn set_padding -->
Sets the renderer’s padding.
## `xpad`
the x padding of the cell renderer
## `ypad`
the y padding of the cell renderer
<!-- trait CellRendererExt::fn set_sensitive -->
Sets the cell renderer’s sensitivity.
## `sensitive`
the sensitivity of the cell
<!-- trait CellRendererExt::fn set_visible -->
Sets the cell renderer’s visibility.
## `visible`
the visibility of the cell
<!-- trait CellRendererExt::fn start_editing -->
Starts editing the contents of this `self`, through a new `CellEditable`
widget created by the `CellRendererClass.start_editing` virtual function.
## `event`
a ``GdkEvent``
## `widget`
widget that received the event
## `path`
widget-dependent string representation of the event location;
 e.g. for `TreeView`, a string representation of `TreePath`
## `background_area`
background area as passed to `CellRendererExt::render`
## `cell_area`
cell area as passed to `CellRendererExt::render`
## `flags`
render flags

# Returns

A new `CellEditable` for editing this
 `self`, or `None` if editing is not possible
<!-- trait CellRendererExt::fn stop_editing -->
Informs the cell renderer that the editing is stopped.
If `canceled` is `true`, the cell renderer will emit the
`CellRenderer::editing-canceled` signal.

This function should be called by cell renderer implementations
in response to the `CellEditable::editing-done` signal of
`CellEditable`.
## `canceled`
`true` if the editing has been canceled
<!-- trait CellRendererExt::fn connect_editing_canceled -->
This signal gets emitted when the user cancels the process of editing a
cell. For example, an editable cell renderer could be written to cancel
editing when the user presses Escape.

See also: `CellRendererExt::stop_editing`.
<!-- trait CellRendererExt::fn connect_editing_started -->
This signal gets emitted when a cell starts to be edited.
The intended use of this signal is to do special setup
on `editable`, e.g. adding a `EntryCompletion` or setting
up additional columns in a `ComboBox`.

See `CellEditable::start_editing` for information on the lifecycle of
the `editable` and a way to do setup that doesn’t depend on the `renderer`.

Note that GTK+ doesn't guarantee that cell renderers will
continue to use the same kind of widget for editing in future
releases, therefore you should check the type of `editable`
before doing any specific setup, as in the following example:

```C
static void
text_editing_started (GtkCellRenderer *cell,
                      GtkCellEditable *editable,
                      const gchar     *path,
                      gpointer         data)
{
  if (GTK_IS_ENTRY (editable))
    {
      GtkEntry *entry = GTK_ENTRY (editable);
      
      // ... create a GtkEntryCompletion
      
      gtk_entry_set_completion (entry, completion);
    }
}
```
## `editable`
the `CellEditable`
## `path`
the path identifying the edited cell
<!-- trait CellRendererExt::fn get_property_cell_background_rgba -->
Cell background as a `gdk::RGBA`
<!-- trait CellRendererExt::fn set_property_cell_background_rgba -->
Cell background as a `gdk::RGBA`
<!-- struct CellRendererAccel -->
`CellRendererAccel` displays a keyboard accelerator (i.e. a key
combination like `Control + a`). If the cell renderer is editable,
the accelerator can be changed by simply typing the new combination.

The `CellRendererAccel` cell renderer was added in GTK+ 2.10.

# Implements

[`CellRendererAccelExt`](trait.CellRendererAccelExt.html), [`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererAccelExt -->
Trait containing all `CellRendererAccel` methods.

# Implementors

[`CellRendererAccel`](struct.CellRendererAccel.html)
<!-- impl CellRendererAccel::fn new -->
Creates a new `CellRendererAccel`.

# Returns

the new cell renderer
<!-- trait CellRendererAccelExt::fn connect_accel_cleared -->
Gets emitted when the user has removed the accelerator.
## `path_string`
the path identifying the row of the edited cell
<!-- trait CellRendererAccelExt::fn connect_accel_edited -->
Gets emitted when the user has selected a new accelerator.
## `path_string`
the path identifying the row of the edited cell
## `accel_key`
the new accelerator keyval
## `accel_mods`
the new acclerator modifier mask
## `hardware_keycode`
the keycode of the new accelerator
<!-- trait CellRendererAccelExt::fn get_property_accel_key -->
The keyval of the accelerator.
<!-- trait CellRendererAccelExt::fn set_property_accel_key -->
The keyval of the accelerator.
<!-- trait CellRendererAccelExt::fn get_property_accel_mode -->
Determines if the edited accelerators are GTK+ accelerators. If
they are, consumed modifiers are suppressed, only accelerators
accepted by GTK+ are allowed, and the accelerators are rendered
in the same way as they are in menus.

If the mode is set to `CellRendererAccelMode::ModifierTap`
then bare modifiers can be set as accelerators by tapping (ie:
pressing and immediately releasing) them.
<!-- trait CellRendererAccelExt::fn set_property_accel_mode -->
Determines if the edited accelerators are GTK+ accelerators. If
they are, consumed modifiers are suppressed, only accelerators
accepted by GTK+ are allowed, and the accelerators are rendered
in the same way as they are in menus.

If the mode is set to `CellRendererAccelMode::ModifierTap`
then bare modifiers can be set as accelerators by tapping (ie:
pressing and immediately releasing) them.
<!-- trait CellRendererAccelExt::fn get_property_accel_mods -->
The modifier mask of the accelerator.
<!-- trait CellRendererAccelExt::fn set_property_accel_mods -->
The modifier mask of the accelerator.
<!-- trait CellRendererAccelExt::fn get_property_keycode -->
The hardware keycode of the accelerator. Note that the hardware keycode is
only relevant if the key does not have a keyval. Normally, the keyboard
configuration should assign keyvals to all keys.
<!-- trait CellRendererAccelExt::fn set_property_keycode -->
The hardware keycode of the accelerator. Note that the hardware keycode is
only relevant if the key does not have a keyval. Normally, the keyboard
configuration should assign keyvals to all keys.
<!-- enum CellRendererAccelMode -->
Determines if the edited accelerators are GTK+ accelerators. If
they are, consumed modifiers are suppressed, only accelerators
accepted by GTK+ are allowed, and the accelerators are rendered
in the same way as they are in menus.
<!-- enum CellRendererAccelMode::variant Gtk -->
GTK+ accelerators mode
<!-- enum CellRendererAccelMode::variant Other -->
Other accelerator mode
GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP: Bare modifiers mode
<!-- struct CellRendererCombo -->
`CellRendererCombo` renders text in a cell like `CellRendererText` from
which it is derived. But while `CellRendererText` offers a simple entry to
edit the text, `CellRendererCombo` offers a `ComboBox`
widget to edit the text. The values to display in the combo box are taken from
the tree model specified in the `CellRendererCombo:model` property.

The combo cell renderer takes care of adding a text cell renderer to the combo
box and sets it to display the column specified by its
`CellRendererCombo:text-column` property. Further properties of the combo box
can be set in a handler for the `CellRenderer::editing-started` signal.

The `CellRendererCombo` cell renderer was added in GTK+ 2.6.

# Implements

[`CellRendererComboExt`](trait.CellRendererComboExt.html), [`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererComboExt -->
Trait containing all `CellRendererCombo` methods.

# Implementors

[`CellRendererCombo`](struct.CellRendererCombo.html)
<!-- impl CellRendererCombo::fn new -->
Creates a new `CellRendererCombo`.
Adjust how text is drawn using object properties.
Object properties can be set globally (with `gobject::ObjectExt::set`).
Also, with `TreeViewColumn`, you can bind a property to a value
in a `TreeModel`. For example, you can bind the “text” property
on the cell renderer to a string value in the model, thus rendering
a different string in each row of the `TreeView`.

# Returns

the new cell renderer
<!-- trait CellRendererComboExt::fn connect_changed -->
This signal is emitted each time after the user selected an item in
the combo box, either by using the mouse or the arrow keys. Contrary
to `ComboBox`, `CellRendererCombo`::changed is not emitted for
changes made to a selected item in the entry. The argument `new_iter`
corresponds to the newly selected item in the combo box and it is relative
to the `TreeModel` set via the model property on `CellRendererCombo`.

Note that as soon as you change the model displayed in the tree view,
the tree view will immediately cease the editing operating. This
means that you most probably want to refrain from changing the model
until the combo cell renderer emits the edited or editing_canceled signal.
## `path_string`
a string of the path identifying the edited cell
 (relative to the tree view model)
## `new_iter`
the new iter selected in the combo box
 (relative to the combo box model)
<!-- trait CellRendererComboExt::fn get_property_has_entry -->
If `true`, the cell renderer will include an entry and allow to enter
values other than the ones in the popup list.
<!-- trait CellRendererComboExt::fn set_property_has_entry -->
If `true`, the cell renderer will include an entry and allow to enter
values other than the ones in the popup list.
<!-- trait CellRendererComboExt::fn get_property_model -->
Holds a tree model containing the possible values for the combo box.
Use the text_column property to specify the column holding the values.
<!-- trait CellRendererComboExt::fn set_property_model -->
Holds a tree model containing the possible values for the combo box.
Use the text_column property to specify the column holding the values.
<!-- trait CellRendererComboExt::fn get_property_text_column -->
Specifies the model column which holds the possible values for the
combo box.

Note that this refers to the model specified in the model property,
not the model backing the tree view to which
this cell renderer is attached.

`CellRendererCombo` automatically adds a text cell renderer for
this column to its combo box.
<!-- trait CellRendererComboExt::fn set_property_text_column -->
Specifies the model column which holds the possible values for the
combo box.

Note that this refers to the model specified in the model property,
not the model backing the tree view to which
this cell renderer is attached.

`CellRendererCombo` automatically adds a text cell renderer for
this column to its combo box.
<!-- enum CellRendererMode -->
Identifies how the user can interact with a particular cell.
<!-- enum CellRendererMode::variant Inert -->
The cell is just for display
 and cannot be interacted with. Note that this doesn’t mean that eg. the
 row being drawn can’t be selected -- just that a particular element of
 it cannot be individually modified.
<!-- enum CellRendererMode::variant Activatable -->
The cell can be clicked.
<!-- enum CellRendererMode::variant Editable -->
The cell can be edited or otherwise modified.
<!-- struct CellRendererPixbuf -->
A `CellRendererPixbuf` can be used to render an image in a cell. It allows
to render either a given `gdk_pixbuf::Pixbuf` (set via the
`CellRendererPixbuf:pixbuf` property) or a named icon (set via the
`CellRendererPixbuf:icon-name` property).

To support the tree view, `CellRendererPixbuf` also supports rendering two
alternative pixbufs, when the `CellRenderer:is-expander` property is `true`.
If the `CellRenderer:is-expanded` property is `true` and the
`CellRendererPixbuf:pixbuf-expander-open` property is set to a pixbuf, it
renders that pixbuf, if the `CellRenderer:is-expanded` property is `false`
and the `CellRendererPixbuf:pixbuf-expander-closed` property is set to a
pixbuf, it renders that one.

# Implements

[`CellRendererPixbufExt`](trait.CellRendererPixbufExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`CellRendererPixbufExtManual`](prelude/trait.CellRendererPixbufExtManual.html)
<!-- trait CellRendererPixbufExt -->
Trait containing all `CellRendererPixbuf` methods.

# Implementors

[`CellRendererPixbuf`](struct.CellRendererPixbuf.html)
<!-- impl CellRendererPixbuf::fn new -->
Creates a new `CellRendererPixbuf`. Adjust rendering
parameters using object properties. Object properties can be set
globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`, you
can bind a property to a value in a `TreeModel`. For example, you
can bind the “pixbuf” property on the cell renderer to a pixbuf value
in the model, thus rendering a different image in each row of the
`TreeView`.

# Returns

the new cell renderer
<!-- trait CellRendererPixbufExt::fn get_property_follow_state -->
Specifies whether the rendered pixbuf should be colorized
according to the `CellRendererState`.

# Deprecated since 3.16

Cell renderers always follow state.
<!-- trait CellRendererPixbufExt::fn set_property_follow_state -->
Specifies whether the rendered pixbuf should be colorized
according to the `CellRendererState`.

# Deprecated since 3.16

Cell renderers always follow state.
<!-- trait CellRendererPixbufExt::fn get_property_gicon -->
The GIcon representing the icon to display.
If the icon theme is changed, the image will be updated
automatically.
<!-- trait CellRendererPixbufExt::fn set_property_gicon -->
The GIcon representing the icon to display.
If the icon theme is changed, the image will be updated
automatically.
<!-- trait CellRendererPixbufExt::fn get_property_icon_name -->
The name of the themed icon to display.
This property only has an effect if not overridden by "stock_id"
or "pixbuf" properties.
<!-- trait CellRendererPixbufExt::fn set_property_icon_name -->
The name of the themed icon to display.
This property only has an effect if not overridden by "stock_id"
or "pixbuf" properties.
<!-- trait CellRendererPixbufExtManual::fn get_property_stock_size -->
The `IconSize` value that specifies the size of the rendered icon.
<!-- trait CellRendererPixbufExtManual::fn set_property_stock_size -->
The `IconSize` value that specifies the size of the rendered icon.
<!-- struct CellRendererProgress -->
`CellRendererProgress` renders a numeric value as a progress par in a cell.
Additionally, it can display a text on top of the progress bar.

The `CellRendererProgress` cell renderer was added in GTK+ 2.6.

# Implements

[`CellRendererProgressExt`](trait.CellRendererProgressExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html)
<!-- trait CellRendererProgressExt -->
Trait containing all `CellRendererProgress` methods.

# Implementors

[`CellRendererProgress`](struct.CellRendererProgress.html)
<!-- impl CellRendererProgress::fn new -->
Creates a new `CellRendererProgress`.

# Returns

the new cell renderer
<!-- trait CellRendererProgressExt::fn get_property_pulse -->
Setting this to a non-negative value causes the cell renderer to
enter "activity mode", where a block bounces back and forth to
indicate that some progress is made, without specifying exactly how
much.

Each increment of the property causes the block to move by a little
bit.

To indicate that the activity has not started yet, set the property
to zero. To indicate completion, set the property to `G_MAXINT`.
<!-- trait CellRendererProgressExt::fn set_property_pulse -->
Setting this to a non-negative value causes the cell renderer to
enter "activity mode", where a block bounces back and forth to
indicate that some progress is made, without specifying exactly how
much.

Each increment of the property causes the block to move by a little
bit.

To indicate that the activity has not started yet, set the property
to zero. To indicate completion, set the property to `G_MAXINT`.
<!-- trait CellRendererProgressExt::fn get_property_text -->
The "text" property determines the label which will be drawn
over the progress bar. Setting this property to `None` causes the default
label to be displayed. Setting this property to an empty string causes
no label to be displayed.
<!-- trait CellRendererProgressExt::fn set_property_text -->
The "text" property determines the label which will be drawn
over the progress bar. Setting this property to `None` causes the default
label to be displayed. Setting this property to an empty string causes
no label to be displayed.
<!-- trait CellRendererProgressExt::fn get_property_text_xalign -->
The "text-xalign" property controls the horizontal alignment of the
text in the progress bar. Valid values range from 0 (left) to 1
(right). Reserved for RTL layouts.
<!-- trait CellRendererProgressExt::fn set_property_text_xalign -->
The "text-xalign" property controls the horizontal alignment of the
text in the progress bar. Valid values range from 0 (left) to 1
(right). Reserved for RTL layouts.
<!-- trait CellRendererProgressExt::fn get_property_text_yalign -->
The "text-yalign" property controls the vertical alignment of the
text in the progress bar. Valid values range from 0 (top) to 1
(bottom).
<!-- trait CellRendererProgressExt::fn set_property_text_yalign -->
The "text-yalign" property controls the vertical alignment of the
text in the progress bar. Valid values range from 0 (top) to 1
(bottom).
<!-- trait CellRendererProgressExt::fn get_property_value -->
The "value" property determines the percentage to which the
progress bar will be "filled in".
<!-- trait CellRendererProgressExt::fn set_property_value -->
The "value" property determines the percentage to which the
progress bar will be "filled in".
<!-- struct CellRendererSpin -->
`CellRendererSpin` renders text in a cell like `CellRendererText` from
which it is derived. But while `CellRendererText` offers a simple entry to
edit the text, `CellRendererSpin` offers a `SpinButton` widget. Of course,
that means that the text has to be parseable as a floating point number.

The range of the spinbutton is taken from the adjustment property of the
cell renderer, which can be set explicitly or mapped to a column in the
tree model, like all properties of cell renders. `CellRendererSpin`
also has properties for the `CellRendererSpin:climb-rate` and the number
of `CellRendererSpin:digits` to display. Other `SpinButton` properties
can be set in a handler for the `CellRenderer::editing-started` signal.

The `CellRendererSpin` cell renderer was added in GTK+ 2.10.

# Implements

[`CellRendererSpinExt`](trait.CellRendererSpinExt.html), [`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererSpinExt -->
Trait containing all `CellRendererSpin` methods.

# Implementors

[`CellRendererSpin`](struct.CellRendererSpin.html)
<!-- impl CellRendererSpin::fn new -->
Creates a new `CellRendererSpin`.

# Returns

a new `CellRendererSpin`
<!-- trait CellRendererSpinExt::fn get_property_adjustment -->
The adjustment that holds the value of the spinbutton.
This must be non-`None` for the cell renderer to be editable.
<!-- trait CellRendererSpinExt::fn set_property_adjustment -->
The adjustment that holds the value of the spinbutton.
This must be non-`None` for the cell renderer to be editable.
<!-- trait CellRendererSpinExt::fn get_property_climb_rate -->
The acceleration rate when you hold down a button.
<!-- trait CellRendererSpinExt::fn set_property_climb_rate -->
The acceleration rate when you hold down a button.
<!-- trait CellRendererSpinExt::fn get_property_digits -->
The number of decimal places to display.
<!-- trait CellRendererSpinExt::fn set_property_digits -->
The number of decimal places to display.
<!-- struct CellRendererSpinner -->
`CellRendererSpinner` renders a spinning animation in a cell, very
similar to `Spinner`. It can often be used as an alternative
to a `CellRendererProgress` for displaying indefinite activity,
instead of actual progress.

To start the animation in a cell, set the `CellRendererSpinner:active`
property to `true` and increment the `CellRendererSpinner:pulse` property
at regular intervals. The usual way to set the cell renderer properties
for each cell is to bind them to columns in your tree model using e.g.
`TreeViewColumn::add_attribute`.

# Implements

[`CellRendererSpinnerExt`](trait.CellRendererSpinnerExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererSpinnerExt -->
Trait containing all `CellRendererSpinner` methods.

# Implementors

[`CellRendererSpinner`](struct.CellRendererSpinner.html)
<!-- impl CellRendererSpinner::fn new -->
Returns a new cell renderer which will show a spinner to indicate
activity.

# Returns

a new `CellRenderer`
<!-- trait CellRendererSpinnerExt::fn get_property_pulse -->
Pulse of the spinner. Increment this value to draw the next frame of the
spinner animation. Usually, you would update this value in a timeout.

By default, the `Spinner` widget draws one full cycle of the animation,
consisting of 12 frames, in 750 milliseconds.
<!-- trait CellRendererSpinnerExt::fn set_property_pulse -->
Pulse of the spinner. Increment this value to draw the next frame of the
spinner animation. Usually, you would update this value in a timeout.

By default, the `Spinner` widget draws one full cycle of the animation,
consisting of 12 frames, in 750 milliseconds.
<!-- trait CellRendererSpinnerExt::fn get_property_size -->
The `IconSize` value that specifies the size of the rendered spinner.
<!-- trait CellRendererSpinnerExt::fn set_property_size -->
The `IconSize` value that specifies the size of the rendered spinner.
<!-- struct CellRendererState -->
Tells how a cell is to be rendered.
<!-- struct CellRendererState::const SELECTED -->
The cell is currently selected, and
 probably has a selection colored background to render to.
<!-- struct CellRendererState::const PRELIT -->
The mouse is hovering over the cell.
<!-- struct CellRendererState::const INSENSITIVE -->
The cell is drawn in an insensitive manner
<!-- struct CellRendererState::const SORTED -->
The cell is in a sorted row
<!-- struct CellRendererState::const FOCUSED -->
The cell is in the focus row.
<!-- struct CellRendererState::const EXPANDABLE -->
The cell is in a row that can be expanded. Since 3.4
<!-- struct CellRendererState::const EXPANDED -->
The cell is in a row that is expanded. Since 3.4
<!-- struct CellRendererText -->
A `CellRendererText` renders a given text in its cell, using the font, color and
style information provided by its properties. The text will be ellipsized if it is
too long and the `CellRendererText:ellipsize` property allows it.

If the `CellRenderer:mode` is `CellRendererMode::Editable`,
the `CellRendererText` allows to edit its text using an entry.

# Implements

[`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererTextExt -->
Trait containing all `CellRendererText` methods.

# Implementors

[`CellRendererAccel`](struct.CellRendererAccel.html), [`CellRendererCombo`](struct.CellRendererCombo.html), [`CellRendererSpin`](struct.CellRendererSpin.html), [`CellRendererText`](struct.CellRendererText.html)
<!-- impl CellRendererText::fn new -->
Creates a new `CellRendererText`. Adjust how text is drawn using
object properties. Object properties can be
set globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`,
you can bind a property to a value in a `TreeModel`. For example,
you can bind the “text” property on the cell renderer to a string
value in the model, thus rendering a different string in each row
of the `TreeView`

# Returns

the new cell renderer
<!-- trait CellRendererTextExt::fn set_fixed_height_from_font -->
Sets the height of a renderer to explicitly be determined by the “font” and
“y_pad” property set on it. Further changes in these properties do not
affect the height, so they must be accompanied by a subsequent call to this
function. Using this function is unflexible, and should really only be used
if calculating the size of a cell is too slow (ie, a massive number of cells
displayed). If `number_of_rows` is -1, then the fixed height is unset, and
the height is determined by the properties again.
## `number_of_rows`
Number of rows of text each cell renderer is allocated, or -1
<!-- trait CellRendererTextExt::fn connect_edited -->
This signal is emitted after `renderer` has been edited.

It is the responsibility of the application to update the model
and store `new_text` at the position indicated by `path`.
## `path`
the path identifying the edited cell
## `new_text`
the new text
<!-- trait CellRendererTextExt::fn get_property_alignment -->
Specifies how to align the lines of text with respect to each other.

Note that this property describes how to align the lines of text in
case there are several of them. The "xalign" property of `CellRenderer`,
on the other hand, sets the horizontal alignment of the whole text.
<!-- trait CellRendererTextExt::fn set_property_alignment -->
Specifies how to align the lines of text with respect to each other.

Note that this property describes how to align the lines of text in
case there are several of them. The "xalign" property of `CellRenderer`,
on the other hand, sets the horizontal alignment of the whole text.
<!-- trait CellRendererTextExt::fn get_property_background_rgba -->
Background color as a `gdk::RGBA`
<!-- trait CellRendererTextExt::fn set_property_background_rgba -->
Background color as a `gdk::RGBA`
<!-- trait CellRendererTextExt::fn get_property_ellipsize -->
Specifies the preferred place to ellipsize the string, if the cell renderer
does not have enough room to display the entire string. Setting it to
`pango::EllipsizeMode::None` turns off ellipsizing. See the wrap-width property
for another way of making the text fit into a given width.
<!-- trait CellRendererTextExt::fn set_property_ellipsize -->
Specifies the preferred place to ellipsize the string, if the cell renderer
does not have enough room to display the entire string. Setting it to
`pango::EllipsizeMode::None` turns off ellipsizing. See the wrap-width property
for another way of making the text fit into a given width.
<!-- trait CellRendererTextExt::fn get_property_foreground_rgba -->
Foreground color as a `gdk::RGBA`
<!-- trait CellRendererTextExt::fn set_property_foreground_rgba -->
Foreground color as a `gdk::RGBA`
<!-- trait CellRendererTextExt::fn get_property_max_width_chars -->
The desired maximum width of the cell, in characters. If this property
is set to -1, the width will be calculated automatically.

For cell renderers that ellipsize or wrap text; this property
controls the maximum reported width of the cell. The
cell should not receive any greater allocation unless it is
set to expand in its `CellLayout` and all of the cell's siblings
have received their natural width.
<!-- trait CellRendererTextExt::fn set_property_max_width_chars -->
The desired maximum width of the cell, in characters. If this property
is set to -1, the width will be calculated automatically.

For cell renderers that ellipsize or wrap text; this property
controls the maximum reported width of the cell. The
cell should not receive any greater allocation unless it is
set to expand in its `CellLayout` and all of the cell's siblings
have received their natural width.
<!-- trait CellRendererTextExt::fn get_property_placeholder_text -->
The text that will be displayed in the `CellRenderer` if
`CellRendererText:editable` is `true` and the cell is empty.

Since 3.6
<!-- trait CellRendererTextExt::fn set_property_placeholder_text -->
The text that will be displayed in the `CellRenderer` if
`CellRendererText:editable` is `true` and the cell is empty.

Since 3.6
<!-- trait CellRendererTextExt::fn get_property_width_chars -->
The desired width of the cell, in characters. If this property is set to
-1, the width will be calculated automatically, otherwise the cell will
request either 3 characters or the property value, whichever is greater.
<!-- trait CellRendererTextExt::fn set_property_width_chars -->
The desired width of the cell, in characters. If this property is set to
-1, the width will be calculated automatically, otherwise the cell will
request either 3 characters or the property value, whichever is greater.
<!-- trait CellRendererTextExt::fn get_property_wrap_mode -->
Specifies how to break the string into multiple lines, if the cell
renderer does not have enough room to display the entire string.
This property has no effect unless the wrap-width property is set.
<!-- trait CellRendererTextExt::fn set_property_wrap_mode -->
Specifies how to break the string into multiple lines, if the cell
renderer does not have enough room to display the entire string.
This property has no effect unless the wrap-width property is set.
<!-- trait CellRendererTextExt::fn get_property_wrap_width -->
Specifies the minimum width at which the text is wrapped. The wrap-mode property can
be used to influence at what character positions the line breaks can be placed.
Setting wrap-width to -1 turns wrapping off.
<!-- trait CellRendererTextExt::fn set_property_wrap_width -->
Specifies the minimum width at which the text is wrapped. The wrap-mode property can
be used to influence at what character positions the line breaks can be placed.
Setting wrap-width to -1 turns wrapping off.
<!-- struct CellRendererToggle -->
`CellRendererToggle` renders a toggle button in a cell. The
button is drawn as a radio or a checkbutton, depending on the
`CellRendererToggle:radio` property.
When activated, it emits the `CellRendererToggle::toggled` signal.

# Implements

[`CellRendererToggleExt`](trait.CellRendererToggleExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait CellRendererToggleExt -->
Trait containing all `CellRendererToggle` methods.

# Implementors

[`CellRendererToggle`](struct.CellRendererToggle.html)
<!-- impl CellRendererToggle::fn new -->
Creates a new `CellRendererToggle`. Adjust rendering
parameters using object properties. Object properties can be set
globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`, you
can bind a property to a value in a `TreeModel`. For example, you
can bind the “active” property on the cell renderer to a boolean value
in the model, thus causing the check button to reflect the state of
the model.

# Returns

the new cell renderer
<!-- trait CellRendererToggleExt::fn get_activatable -->
Returns whether the cell renderer is activatable. See
`CellRendererToggleExt::set_activatable`.

# Returns

`true` if the cell renderer is activatable.
<!-- trait CellRendererToggleExt::fn get_active -->
Returns whether the cell renderer is active. See
`CellRendererToggleExt::set_active`.

# Returns

`true` if the cell renderer is active.
<!-- trait CellRendererToggleExt::fn get_radio -->
Returns whether we’re rendering radio toggles rather than checkboxes.

# Returns

`true` if we’re rendering radio toggles rather than checkboxes
<!-- trait CellRendererToggleExt::fn set_activatable -->
Makes the cell renderer activatable.
## `setting`
the value to set.
<!-- trait CellRendererToggleExt::fn set_active -->
Activates or deactivates a cell renderer.
## `setting`
the value to set.
<!-- trait CellRendererToggleExt::fn set_radio -->
If `radio` is `true`, the cell renderer renders a radio toggle
(i.e. a toggle in a group of mutually-exclusive toggles).
If `false`, it renders a check toggle (a standalone boolean option).
This can be set globally for the cell renderer, or changed just
before rendering each cell in the model (for `TreeView`, you set
up a per-row setting using `TreeViewColumn` to associate model
columns with cell renderer properties).
## `radio`
`true` to make the toggle look like a radio button
<!-- trait CellRendererToggleExt::fn connect_toggled -->
The ::toggled signal is emitted when the cell is toggled.

It is the responsibility of the application to update the model
with the correct value to store at `path`. Often this is simply the
opposite of the value currently stored at `path`.
## `path`
string representation of `TreePath` describing the
 event location
<!-- struct CellView -->
A `CellView` displays a single row of a `TreeModel` using a `CellArea`
and `CellAreaContext`. A `CellAreaContext` can be provided to the
`CellView` at construction time in order to keep the cellview in context
of a group of cell views, this ensures that the renderers displayed will
be properly aligned with eachother (like the aligned cells in the menus
of `ComboBox`).

`CellView` is `Orientable` in order to decide in which orientation
the underlying `CellAreaContext` should be allocated. Taking the `ComboBox`
menu as an example, cellviews should be oriented horizontally if the menus are
listed top-to-bottom and thus all share the same width but may have separate
individual heights (left-to-right menus should be allocated vertically since
they all share the same height but may have variable widths).

# CSS nodes

`CellView` has a single CSS node with name cellview.

# Implements

[`CellViewExt`](trait.CellViewExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait CellViewExt -->
Trait containing all `CellView` methods.

# Implementors

[`CellView`](struct.CellView.html)
<!-- impl CellView::fn new -->
Creates a new `CellView` widget.

# Returns

A newly created `CellView` widget.
<!-- impl CellView::fn new_with_context -->
Creates a new `CellView` widget with a specific `CellArea`
to layout cells and a specific `CellAreaContext`.

Specifying the same context for a handfull of cells lets
the underlying area synchronize the geometry for those cells,
in this way alignments with cellviews for other rows are
possible.
## `area`
the `CellArea` to layout cells
## `context`
the `CellAreaContext` in which to calculate cell geometry

# Returns

A newly created `CellView` widget.
<!-- impl CellView::fn new_with_markup -->
Creates a new `CellView` widget, adds a `CellRendererText`
to it, and makes it show `markup`. The text can be
marked up with the [Pango text markup language][PangoMarkupFormat].
## `markup`
the text to display in the cell view

# Returns

A newly created `CellView` widget.
<!-- impl CellView::fn new_with_pixbuf -->
Creates a new `CellView` widget, adds a `CellRendererPixbuf`
to it, and makes it show `pixbuf`.
## `pixbuf`
the image to display in the cell view

# Returns

A newly created `CellView` widget.
<!-- impl CellView::fn new_with_text -->
Creates a new `CellView` widget, adds a `CellRendererText`
to it, and makes it show `text`.
## `text`
the text to display in the cell view

# Returns

A newly created `CellView` widget.
<!-- trait CellViewExt::fn get_displayed_row -->
Returns a `TreePath` referring to the currently
displayed row. If no row is currently displayed,
`None` is returned.

# Returns

the currently displayed row or `None`
<!-- trait CellViewExt::fn get_draw_sensitive -->
Gets whether `self` is configured to draw all of its
cells in a sensitive state.

# Returns

whether `self` draws all of its
cells in a sensitive state
<!-- trait CellViewExt::fn get_fit_model -->
Gets whether `self` is configured to request space
to fit the entire `TreeModel`.

# Returns

whether `self` requests space to fit
the entire `TreeModel`.
<!-- trait CellViewExt::fn get_model -->
Returns the model for `self`. If no model is used `None` is
returned.

# Returns

a `TreeModel` used or `None`
<!-- trait CellViewExt::fn set_background_rgba -->
Sets the background color of `self`.
## `rgba`
the new background color
<!-- trait CellViewExt::fn set_displayed_row -->
Sets the row of the model that is currently displayed
by the `CellView`. If the path is unset, then the
contents of the cellview “stick” at their last value;
this is not normally a desired result, but may be
a needed intermediate state if say, the model for
the `CellView` becomes temporarily empty.
## `path`
a `TreePath` or `None` to unset.
<!-- trait CellViewExt::fn set_draw_sensitive -->
Sets whether `self` should draw all of its
cells in a sensitive state, this is used by `ComboBox` menus
to ensure that rows with insensitive cells that contain
children appear sensitive in the parent menu item.
## `draw_sensitive`
whether to draw all cells in a sensitive state.
<!-- trait CellViewExt::fn set_fit_model -->
Sets whether `self` should request space to fit the entire `TreeModel`.

This is used by `ComboBox` to ensure that the cell view displayed on
the combo box’s button always gets enough space and does not resize
when selection changes.
## `fit_model`
whether `self` should request space for the whole model.
<!-- trait CellViewExt::fn set_model -->
Sets the model for `self`. If `self` already has a model
set, it will remove it before setting the new model. If `model` is
`None`, then it will unset the old model.
## `model`
a `TreeModel`
<!-- trait CellViewExt::fn get_property_background_rgba -->
The background color as a `gdk::RGBA`
<!-- trait CellViewExt::fn set_property_background_rgba -->
The background color as a `gdk::RGBA`
<!-- trait CellViewExt::fn get_property_cell_area -->
The `CellArea` rendering cells

If no area is specified when creating the cell view with `CellView::new_with_context`
a horizontally oriented `CellAreaBox` will be used.

since 3.0
<!-- trait CellViewExt::fn set_property_cell_area -->
The `CellArea` rendering cells

If no area is specified when creating the cell view with `CellView::new_with_context`
a horizontally oriented `CellAreaBox` will be used.

since 3.0
<!-- trait CellViewExt::fn get_property_cell_area_context -->
The `CellAreaContext` used to compute the geometry of the cell view.

A group of cell views can be assigned the same context in order to
ensure the sizes and cell alignments match across all the views with
the same context.

`ComboBox` menus uses this to assign the same context to all cell views
in the menu items for a single menu (each submenu creates its own
context since the size of each submenu does not depend on parent
or sibling menus).

since 3.0
<!-- trait CellViewExt::fn set_property_cell_area_context -->
The `CellAreaContext` used to compute the geometry of the cell view.

A group of cell views can be assigned the same context in order to
ensure the sizes and cell alignments match across all the views with
the same context.

`ComboBox` menus uses this to assign the same context to all cell views
in the menu items for a single menu (each submenu creates its own
context since the size of each submenu does not depend on parent
or sibling menus).

since 3.0
<!-- trait CellViewExt::fn get_property_draw_sensitive -->
Whether all cells should be draw as sensitive for this view regardless
of the actual cell properties (used to make menus with submenus appear
sensitive when the items in submenus might be insensitive).

since 3.0
<!-- trait CellViewExt::fn set_property_draw_sensitive -->
Whether all cells should be draw as sensitive for this view regardless
of the actual cell properties (used to make menus with submenus appear
sensitive when the items in submenus might be insensitive).

since 3.0
<!-- trait CellViewExt::fn get_property_fit_model -->
Whether the view should request enough space to always fit
the size of every row in the model (used by the combo box to
ensure the combo box size doesnt change when different items
are selected).

since 3.0
<!-- trait CellViewExt::fn set_property_fit_model -->
Whether the view should request enough space to always fit
the size of every row in the model (used by the combo box to
ensure the combo box size doesnt change when different items
are selected).

since 3.0
<!-- trait CellViewExt::fn get_property_model -->
The model for cell view

since 2.10
<!-- trait CellViewExt::fn set_property_model -->
The model for cell view

since 2.10
<!-- struct CheckButton -->
A `CheckButton` places a discrete `ToggleButton` next to a widget,
(usually a `Label`). See the section on `ToggleButton` widgets for
more information about toggle/check buttons.

The important signal ( `ToggleButton::toggled` ) is also inherited from
`ToggleButton`.

# CSS nodes


```plain
checkbutton
├── check
╰── <child>
```

A `CheckButton` with indicator (see `ToggleButtonExt::set_mode`) has a
main CSS node with name checkbutton and a subnode with name check.


```plain
button.check
├── check
╰── <child>
```

A `CheckButton` without indicator changes the name of its main node
to button and adds a .check style class to it. The subnode is invisible
in this case.

# Implements

[`ToggleButtonExt`](trait.ToggleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl CheckButton::fn new -->
Creates a new `CheckButton`.

# Returns

a `Widget`.
<!-- impl CheckButton::fn new_with_label -->
Creates a new `CheckButton` with a `Label` to the right of it.
## `label`
the text for the check button.

# Returns

a `Widget`.
<!-- impl CheckButton::fn new_with_mnemonic -->
Creates a new `CheckButton` containing a label. The label
will be created using `Label::new_with_mnemonic`, so underscores
in `label` indicate the mnemonic for the check button.
## `label`
The text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `CheckButton`
<!-- struct CheckMenuItem -->
A `CheckMenuItem` is a menu item that maintains the state of a boolean
value in addition to a `MenuItem` usual role in activating application
code.

A check box indicating the state of the boolean value is displayed
at the left side of the `MenuItem`. Activating the `MenuItem`
toggles the value.

# CSS nodes


```plain
menuitem
├── check.left
╰── <child>
```

`CheckMenuItem` has a main CSS node with name menuitem, and a subnode
with name check, which gets the .left or .right style class.

# Implements

[`CheckMenuItemExt`](trait.CheckMenuItemExt.html), [`GtkMenuItemExt`](trait.GtkMenuItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait CheckMenuItemExt -->
Trait containing all `CheckMenuItem` methods.

# Implementors

[`CheckMenuItem`](struct.CheckMenuItem.html), [`RadioMenuItem`](struct.RadioMenuItem.html)
<!-- impl CheckMenuItem::fn new -->
Creates a new `CheckMenuItem`.

# Returns

a new `CheckMenuItem`.
<!-- impl CheckMenuItem::fn new_with_label -->
Creates a new `CheckMenuItem` with a label.
## `label`
the string to use for the label.

# Returns

a new `CheckMenuItem`.
<!-- impl CheckMenuItem::fn new_with_mnemonic -->
Creates a new `CheckMenuItem` containing a label. The label
will be created using `Label::new_with_mnemonic`, so underscores
in `label` indicate the mnemonic for the menu item.
## `label`
The text of the button, with an underscore in front of the
 character

# Returns

a new `CheckMenuItem`
<!-- trait CheckMenuItemExt::fn get_active -->
Returns whether the check menu item is active. See
gtk_check_menu_item_set_active ().

# Returns

`true` if the menu item is checked.
<!-- trait CheckMenuItemExt::fn get_draw_as_radio -->
Returns whether `self` looks like a `RadioMenuItem`

# Returns

Whether `self` looks like a `RadioMenuItem`
<!-- trait CheckMenuItemExt::fn get_inconsistent -->
Retrieves the value set by `CheckMenuItemExt::set_inconsistent`.

# Returns

`true` if inconsistent
<!-- trait CheckMenuItemExt::fn set_active -->
Sets the active state of the menu item’s check box.
## `is_active`
boolean value indicating whether the check box is active.
<!-- trait CheckMenuItemExt::fn set_draw_as_radio -->
Sets whether `self` is drawn like a `RadioMenuItem`
## `draw_as_radio`
whether `self` is drawn like a `RadioMenuItem`
<!-- trait CheckMenuItemExt::fn set_inconsistent -->
If the user has selected a range of elements (such as some text or
spreadsheet cells) that are affected by a boolean setting, and the
current values in that range are inconsistent, you may want to
display the check in an “in between” state. This function turns on
“in between” display. Normally you would turn off the inconsistent
state again if the user explicitly selects a setting. This has to be
done manually, `CheckMenuItemExt::set_inconsistent` only affects
visual appearance, it doesn’t affect the semantics of the widget.
## `setting`
`true` to display an “inconsistent” third state check
<!-- trait CheckMenuItemExt::fn toggled -->
Emits the `CheckMenuItem::toggled` signal.
<!-- trait CheckMenuItemExt::fn connect_toggled -->
This signal is emitted when the state of the check box is changed.

A signal handler can use `CheckMenuItemExt::get_active`
to discover the new state.
<!-- struct Clipboard -->
The `Clipboard` object represents a clipboard of data shared
between different processes or between different widgets in
the same process. Each clipboard is identified by a name encoded as a
`gdk::Atom`. (Conversion to and from strings can be done with
`gdk::Atom::intern` and `gdk::Atom::name`.) The default clipboard
corresponds to the “CLIPBOARD” atom; another commonly used clipboard
is the “PRIMARY” clipboard, which, in X, traditionally contains
the currently selected text.

To support having a number of different formats on the clipboard
at the same time, the clipboard mechanism allows providing
callbacks instead of the actual data. When you set the contents
of the clipboard, you can either supply the data directly (via
functions like `Clipboard::set_text`), or you can supply a
callback to be called at a later time when the data is needed (via
`Clipboard::set_with_data` or `Clipboard::set_with_owner`.)
Providing a callback also avoids having to make copies of the data
when it is not needed.

`Clipboard::set_with_data` and `Clipboard::set_with_owner`
are quite similar; the choice between the two depends mostly on
which is more convenient in a particular situation.
The former is most useful when you want to have a blob of data
with callbacks to convert it into the various data types that you
advertise. When the `clear_func` you provided is called, you
simply free the data blob. The latter is more useful when the
contents of clipboard reflect the internal state of a `gobject::Object`
(As an example, for the PRIMARY clipboard, when an entry widget
provides the clipboard’s contents the contents are simply the
text within the selected region.) If the contents change, the
entry widget can call `Clipboard::set_with_owner` to update
the timestamp for clipboard ownership, without having to worry
about `clear_func` being called.

Requesting the data from the clipboard is essentially
asynchronous. If the contents of the clipboard are provided within
the same process, then a direct function call will be made to
retrieve the data, but if they are provided by another process,
then the data needs to be retrieved from the other process, which
may take some time. To avoid blocking the user interface, the call
to request the selection, `Clipboard::request_contents` takes a
callback that will be called when the contents are received (or
when the request fails.) If you don’t want to deal with providing
a separate callback, you can also use `Clipboard::wait_for_contents`.
What this does is run the GLib main loop recursively waiting for
the contents. This can simplify the code flow, but you still have
to be aware that other callbacks in your program can be called
while this recursive mainloop is running.

Along with the functions to get the clipboard contents as an
arbitrary data chunk, there are also functions to retrieve
it as text, `Clipboard::request_text` and
`Clipboard::wait_for_text`. These functions take care of
determining which formats are advertised by the clipboard
provider, asking for the clipboard in the best available format
and converting the results into the UTF-8 encoding. (The standard
form for representing strings in GTK+.)

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl Clipboard::fn get -->
Returns the clipboard object for the given selection.
See `Clipboard::get_for_display` for complete details.
## `selection`
a `gdk::Atom` which identifies the clipboard to use

# Returns

the appropriate clipboard object. If no clipboard
 already exists, a new one will be created. Once a clipboard
 object has been created, it is persistent and, since it is
 owned by GTK+, must not be freed or unreffed.
<!-- impl Clipboard::fn get_default -->
Returns the default clipboard object for use with cut/copy/paste menu items
and keyboard shortcuts.

Feature: `v3_16`

## `display`
the `gdk::Display` for which the clipboard is to be retrieved.

# Returns

the default clipboard object.
<!-- impl Clipboard::fn get_for_display -->
Returns the clipboard object for the given selection.
Cut/copy/paste menu items and keyboard shortcuts should use
the default clipboard, returned by passing `GDK_SELECTION_CLIPBOARD` for `selection`.
(`GDK_NONE` is supported as a synonym for GDK_SELECTION_CLIPBOARD
for backwards compatibility reasons.)
The currently-selected object or text should be provided on the clipboard
identified by `GDK_SELECTION_PRIMARY`. Cut/copy/paste menu items
conceptually copy the contents of the `GDK_SELECTION_PRIMARY` clipboard
to the default clipboard, i.e. they copy the selection to what the
user sees as the clipboard.

(Passing `GDK_NONE` is the same as using `gdk_atom_intern
("CLIPBOARD", FALSE)`.

See the
[FreeDesktop Clipboard Specification](http://www.freedesktop.org/Standards/clipboards-spec)
for a detailed discussion of the “CLIPBOARD” vs. “PRIMARY”
selections under the X window system. On Win32 the
`GDK_SELECTION_PRIMARY` clipboard is essentially ignored.)

It’s possible to have arbitrary named clipboards; if you do invent
new clipboards, you should prefix the selection name with an
underscore (because the ICCCM requires that nonstandard atoms are
underscore-prefixed), and namespace it as well. For example,
if your application called “Foo” has a special-purpose
clipboard, you might call it “_FOO_SPECIAL_CLIPBOARD”.
## `display`
the `gdk::Display` for which the clipboard is to be retrieved or created.
## `selection`
a `gdk::Atom` which identifies the clipboard to use.

# Returns

the appropriate clipboard object. If no
 clipboard already exists, a new one will be created. Once a clipboard
 object has been created, it is persistent and, since it is owned by
 GTK+, must not be freed or unrefd.
<!-- impl Clipboard::fn clear -->
Clears the contents of the clipboard. Generally this should only
be called between the time you call `Clipboard::set_with_owner`
or `Clipboard::set_with_data`,
and when the `clear_func` you supplied is called. Otherwise, the
clipboard may be owned by someone else.
<!-- impl Clipboard::fn get_display -->
Gets the `gdk::Display` associated with `self`

# Returns

the `gdk::Display` associated with `self`
<!-- impl Clipboard::fn get_owner -->
If the clipboard contents callbacks were set with
`Clipboard::set_with_owner`, and the `Clipboard::set_with_data` or
`Clipboard::clear` has not subsequently called, returns the owner set
by `Clipboard::set_with_owner`.

# Returns

the owner of the clipboard, if any;
 otherwise `None`.
<!-- impl Clipboard::fn get_selection -->
Gets the selection that this clipboard is for.

Feature: `v3_22`


# Returns

the selection
<!-- impl Clipboard::fn request_contents -->
Requests the contents of clipboard as the given target.
When the results of the result are later received the supplied callback
will be called.
## `target`
an atom representing the form into which the clipboard
 owner should convert the selection.
## `callback`
A function to call when the results are received
 (or the retrieval fails). If the retrieval fails the length field of
 `selection_data` will be negative.
## `user_data`
user data to pass to `callback`
<!-- impl Clipboard::fn request_image -->
Requests the contents of the clipboard as image. When the image is
later received, it will be converted to a `gdk_pixbuf::Pixbuf`, and
`callback` will be called.

The `pixbuf` parameter to `callback` will contain the resulting
`gdk_pixbuf::Pixbuf` if the request succeeded, or `None` if it failed. This
could happen for various reasons, in particular if the clipboard
was empty or if the contents of the clipboard could not be
converted into an image.
## `callback`
a function to call when the image is received,
 or the retrieval fails. (It will always be called one way or the other.)
## `user_data`
user data to pass to `callback`.
<!-- impl Clipboard::fn request_rich_text -->
Requests the contents of the clipboard as rich text. When the rich
text is later received, `callback` will be called.

The `text` parameter to `callback` will contain the resulting rich
text if the request succeeded, or `None` if it failed. The `length`
parameter will contain `text`’s length. This function can fail for
various reasons, in particular if the clipboard was empty or if the
contents of the clipboard could not be converted into rich text form.
## `buffer`
a `TextBuffer`
## `callback`
a function to call when the text is received,
 or the retrieval fails. (It will always be called one way or the other.)
## `user_data`
user data to pass to `callback`.
<!-- impl Clipboard::fn request_targets -->
Requests the contents of the clipboard as list of supported targets.
When the list is later received, `callback` will be called.

The `targets` parameter to `callback` will contain the resulting targets if
the request succeeded, or `None` if it failed.
## `callback`
a function to call when the targets are
 received, or the retrieval fails. (It will always be called
 one way or the other.)
## `user_data`
user data to pass to `callback`.
<!-- impl Clipboard::fn request_text -->
Requests the contents of the clipboard as text. When the text is
later received, it will be converted to UTF-8 if necessary, and
`callback` will be called.

The `text` parameter to `callback` will contain the resulting text if
the request succeeded, or `None` if it failed. This could happen for
various reasons, in particular if the clipboard was empty or if the
contents of the clipboard could not be converted into text form.
## `callback`
a function to call when the text is received,
 or the retrieval fails. (It will always be called one way or the other.)
## `user_data`
user data to pass to `callback`.
<!-- impl Clipboard::fn request_uris -->
Requests the contents of the clipboard as URIs. When the URIs are
later received `callback` will be called.

The `uris` parameter to `callback` will contain the resulting array of
URIs if the request succeeded, or `None` if it failed. This could happen
for various reasons, in particular if the clipboard was empty or if the
contents of the clipboard could not be converted into URI form.
## `callback`
a function to call when the URIs are received,
 or the retrieval fails. (It will always be called one way or the other.)
## `user_data`
user data to pass to `callback`.
<!-- impl Clipboard::fn set_can_store -->
Hints that the clipboard data should be stored somewhere when the
application exits or when gtk_clipboard_store () is called.

This value is reset when the clipboard owner changes.
Where the clipboard data is stored is platform dependent,
see gdk_display_store_clipboard () for more information.
## `targets`
array containing
 information about which forms should be stored or `None`
 to indicate that all forms should be stored.
## `n_targets`
number of elements in `targets`
<!-- impl Clipboard::fn set_image -->
Sets the contents of the clipboard to the given `gdk_pixbuf::Pixbuf`.
GTK+ will take responsibility for responding for requests
for the image, and for converting the image into the
requested format.
## `pixbuf`
a `gdk_pixbuf::Pixbuf`
<!-- impl Clipboard::fn set_text -->
Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
make a copy of the text and take responsibility for responding
for requests for the text, and for converting the text into
the requested format.
## `text`
a UTF-8 string.
## `len`
length of `text`, in bytes, or -1, in which case
 the length will be determined with `strlen`.
<!-- impl Clipboard::fn set_with_data -->
Virtually sets the contents of the specified clipboard by providing
a list of supported formats for the clipboard data and a function
to call to get the actual data when it is requested.
## `targets`
array containing information
 about the available forms for the clipboard data
## `n_targets`
number of elements in `targets`
## `get_func`
function to call to get the actual clipboard data
## `clear_func`
when the clipboard contents are set again,
 this function will be called, and `get_func` will not be subsequently
 called.
## `user_data`
user data to pass to `get_func` and `clear_func`.

# Returns

`true` if setting the clipboard data succeeded.
 If setting the clipboard data failed the provided callback
 functions will be ignored.
<!-- impl Clipboard::fn set_with_owner -->
Virtually sets the contents of the specified clipboard by providing
a list of supported formats for the clipboard data and a function
to call to get the actual data when it is requested.

The difference between this function and `Clipboard::set_with_data`
is that instead of an generic `user_data` pointer, a `gobject::Object` is passed
in.
## `targets`
array containing information
 about the available forms for the clipboard data
## `n_targets`
number of elements in `targets`
## `get_func`
function to call to get the actual clipboard data
## `clear_func`
when the clipboard contents are set again,
 this function will be called, and `get_func` will not be subsequently
 called
## `owner`
an object that “owns” the data. This object will be passed
 to the callbacks when called

# Returns

`true` if setting the clipboard data succeeded.
 If setting the clipboard data failed the provided callback
 functions will be ignored.
<!-- impl Clipboard::fn store -->
Stores the current clipboard data somewhere so that it will stay
around after the application has quit.
<!-- impl Clipboard::fn wait_for_contents -->
Requests the contents of the clipboard using the given target.
This function waits for the data to be received using the main
loop, so events, timeouts, etc, may be dispatched during the wait.
## `target`
an atom representing the form into which the clipboard
 owner should convert the selection.

# Returns

a newly-allocated `SelectionData` object or `None`
 if retrieving the given target failed. If non-`None`,
 this value must be freed with `SelectionData::free`
 when you are finished with it.
<!-- impl Clipboard::fn wait_for_image -->
Requests the contents of the clipboard as image and converts
the result to a `gdk_pixbuf::Pixbuf`. This function waits for
the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

# Returns

a newly-allocated `gdk_pixbuf::Pixbuf`
 object which must be disposed with `gobject::ObjectExt::unref`, or
 `None` if retrieving the selection data failed. (This could
 happen for various reasons, in particular if the clipboard
 was empty or if the contents of the clipboard could not be
 converted into an image.)
<!-- impl Clipboard::fn wait_for_rich_text -->
Requests the contents of the clipboard as rich text. This function
waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.
## `buffer`
a `TextBuffer`
## `format`
return location for the format of the returned data
## `length`
return location for the length of the returned data

# Returns

a
 newly-allocated binary block of data which must be
 freed with `g_free`, or `None` if retrieving the
 selection data failed. (This could happen for various
 reasons, in particular if the clipboard was empty or
 if the contents of the clipboard could not be
 converted into text form.)
<!-- impl Clipboard::fn wait_for_targets -->
Returns a list of targets that are present on the clipboard, or `None`
if there aren’t any targets available. The returned list must be
freed with `g_free`.
This function waits for the data to be received using the main
loop, so events, timeouts, etc, may be dispatched during the wait.
## `targets`
location
 to store an array of targets. The result stored here must
 be freed with `g_free`.
## `n_targets`
location to store number of items in `targets`.

# Returns

`true` if any targets are present on the clipboard,
 otherwise `false`.
<!-- impl Clipboard::fn wait_for_text -->
Requests the contents of the clipboard as text and converts
the result to UTF-8 if necessary. This function waits for
the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

# Returns

a newly-allocated UTF-8 string which must
 be freed with `g_free`, or `None` if retrieving
 the selection data failed. (This could happen
 for various reasons, in particular if the
 clipboard was empty or if the contents of the
 clipboard could not be converted into text form.)
<!-- impl Clipboard::fn wait_for_uris -->
Requests the contents of the clipboard as URIs. This function waits
for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

# Returns


 a newly-allocated `None`-terminated array of strings which must
 be freed with `g_strfreev`, or `None` if retrieving the
 selection data failed. (This could happen for various reasons,
 in particular if the clipboard was empty or if the contents of
 the clipboard could not be converted into URI form.)
<!-- impl Clipboard::fn wait_is_image_available -->
Test to see if there is an image available to be pasted
This is done by requesting the TARGETS atom and checking
if it contains any of the supported image targets. This function
waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

This function is a little faster than calling
`Clipboard::wait_for_image` since it doesn’t need to retrieve
the actual image data.

# Returns

`true` is there is an image available, `false` otherwise.
<!-- impl Clipboard::fn wait_is_rich_text_available -->
Test to see if there is rich text available to be pasted
This is done by requesting the TARGETS atom and checking
if it contains any of the supported rich text targets. This function
waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

This function is a little faster than calling
`Clipboard::wait_for_rich_text` since it doesn’t need to retrieve
the actual text.
## `buffer`
a `TextBuffer`

# Returns

`true` is there is rich text available, `false` otherwise.
<!-- impl Clipboard::fn wait_is_target_available -->
Checks if a clipboard supports pasting data of a given type. This
function can be used to determine if a “Paste” menu item should be
insensitive or not.

If you want to see if there’s text available on the clipboard, use
gtk_clipboard_wait_is_text_available () instead.
## `target`
A `gdk::Atom` indicating which target to look for.

# Returns

`true` if the target is available, `false` otherwise.
<!-- impl Clipboard::fn wait_is_text_available -->
Test to see if there is text available to be pasted
This is done by requesting the TARGETS atom and checking
if it contains any of the supported text targets. This function
waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

This function is a little faster than calling
`Clipboard::wait_for_text` since it doesn’t need to retrieve
the actual text.

# Returns

`true` is there is text available, `false` otherwise.
<!-- impl Clipboard::fn wait_is_uris_available -->
Test to see if there is a list of URIs available to be pasted
This is done by requesting the TARGETS atom and checking
if it contains the URI targets. This function
waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.

This function is a little faster than calling
`Clipboard::wait_for_uris` since it doesn’t need to retrieve
the actual URI data.

# Returns

`true` is there is an URI list available, `false` otherwise.
<!-- impl Clipboard::fn connect_owner_change -->
The ::owner-change signal is emitted when GTK+ receives an
event that indicates that the ownership of the selection
associated with `clipboard` has changed.
## `event`
the `gdk::EventOwnerChange` event
<!-- struct ColorButton -->
The `ColorButton` is a button which displays the currently selected
color and allows to open a color selection dialog to change the color.
It is suitable widget for selecting a color in a preference dialog.

# CSS nodes

`ColorButton` has a single CSS node with name button. To differentiate
it from a plain `Button`, it gets the .color style class.

# Implements

[`ColorButtonExt`](trait.ColorButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html), [`ColorButtonExtManual`](prelude/trait.ColorButtonExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`ColorChooserExtManual`](prelude/trait.ColorChooserExtManual.html)
<!-- trait ColorButtonExt -->
Trait containing all `ColorButton` methods.

# Implementors

[`ColorButton`](struct.ColorButton.html)
<!-- impl ColorButton::fn new -->
Creates a new color button.

This returns a widget in the form of a small button containing
a swatch representing the current selected color. When the button
is clicked, a color-selection dialog will open, allowing the user
to select a color. The swatch will be updated to reflect the new
color when the user finishes.

# Returns

a new color button
<!-- impl ColorButton::fn new_with_rgba -->
Creates a new color button.
## `rgba`
A `gdk::RGBA` to set the current color with

# Returns

a new color button
<!-- trait ColorButtonExt::fn get_title -->
Gets the title of the color selection dialog.

# Returns

An internal string, do not free the return value
<!-- trait ColorButtonExtManual::fn set_color -->
Sets the current color to be `color`.

# Deprecated

Use `ColorChooser::set_rgba` instead.
## `color`
A `gdk::Color` to set the current color with
<!-- trait ColorButtonExt::fn set_title -->
Sets the title for the color selection dialog.
## `title`
String containing new window title
<!-- trait ColorButtonExt::fn connect_color_set -->
The ::color-set signal is emitted when the user selects a color.
When handling this signal, use `ColorButton::get_rgba` to
find out which color was just selected.

Note that this signal is only emitted when the user
changes the color. If you need to react to programmatic color changes
as well, use the notify::color signal.
<!-- trait ColorButtonExt::fn get_property_alpha -->
The selected opacity value (0 fully transparent, 65535 fully opaque).
<!-- trait ColorButtonExt::fn set_property_alpha -->
The selected opacity value (0 fully transparent, 65535 fully opaque).
<!-- trait ColorButtonExt::fn get_property_rgba -->
The RGBA color.
<!-- trait ColorButtonExt::fn set_property_rgba -->
The RGBA color.
<!-- trait ColorButtonExt::fn get_property_show_editor -->
Set this property to `true` to skip the palette
in the dialog and go directly to the color editor.

This property should be used in cases where the palette
in the editor would be redundant, such as when the color
button is already part of a palette.

Feature: `v3_20`

<!-- trait ColorButtonExt::fn set_property_show_editor -->
Set this property to `true` to skip the palette
in the dialog and go directly to the color editor.

This property should be used in cases where the palette
in the editor would be redundant, such as when the color
button is already part of a palette.

Feature: `v3_20`

<!-- trait ColorButtonExt::fn get_property_title -->
The title of the color selection dialog
<!-- trait ColorButtonExt::fn set_property_title -->
The title of the color selection dialog
<!-- trait ColorButtonExt::fn get_property_use_alpha -->
If this property is set to `true`, the color swatch on the button is
rendered against a checkerboard background to show its opacity and
the opacity slider is displayed in the color selection dialog.
<!-- trait ColorButtonExt::fn set_property_use_alpha -->
If this property is set to `true`, the color swatch on the button is
rendered against a checkerboard background to show its opacity and
the opacity slider is displayed in the color selection dialog.
<!-- struct ColorChooser -->
`ColorChooser` is an interface that is implemented by widgets
for choosing colors. Depending on the situation, colors may be
allowed to have alpha (translucency).

In GTK+, the main widgets that implement this interface are
`ColorChooserWidget`, `ColorChooserDialog` and `ColorButton`.

# Implements

[`ColorChooserExt`](trait.ColorChooserExt.html), [`ColorChooserExtManual`](prelude/trait.ColorChooserExtManual.html)
<!-- trait ColorChooserExt -->
Trait containing all `ColorChooser` methods.

# Implementors

[`ColorButton`](struct.ColorButton.html), [`ColorChooserDialog`](struct.ColorChooserDialog.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`ColorChooser`](struct.ColorChooser.html)
<!-- trait ColorChooserExtManual::fn add_palette -->
Adds a palette to the color chooser. If `orientation` is horizontal,
the colors are grouped in rows, with `colors_per_line` colors
in each row. If `horizontal` is `false`, the colors are grouped
in columns instead.

The default color palette of `ColorChooserWidget` has
27 colors, organized in columns of 3 colors. The default gray
palette has 9 grays in a single row.

The layout of the color chooser widget works best when the
palettes have 9-10 columns.

Calling this function for the first time has the
side effect of removing the default color and gray palettes
from the color chooser.

If `colors` is `None`, removes all previously added palettes.
## `orientation`
`Orientation::Horizontal` if the palette should
 be displayed in rows, `Orientation::Vertical` for columns
## `colors_per_line`
the number of colors to show in each row/column
## `n_colors`
the total number of elements in `colors`
## `colors`
the colors of the palette, or `None`
<!-- trait ColorChooserExt::fn get_rgba -->
Gets the currently-selected color.
## `color`
a `gdk::RGBA` to fill in with the current color
<!-- trait ColorChooserExt::fn get_use_alpha -->
Returns whether the color chooser shows the alpha channel.

# Returns

`true` if the color chooser uses the alpha channel,
 `false` if not
<!-- trait ColorChooserExt::fn set_rgba -->
Sets the color.
## `color`
the new color
<!-- trait ColorChooserExt::fn set_use_alpha -->
Sets whether or not the color chooser should use the alpha channel.
## `use_alpha`
`true` if color chooser should use alpha channel, `false` if not
<!-- trait ColorChooserExt::fn connect_color_activated -->
Emitted when a color is activated from the color chooser.
This usually happens when the user clicks a color swatch,
or a color is selected and the user presses one of the keys
Space, Shift+Space, Return or Enter.
## `color`
the color
<!-- trait ColorChooserExt::fn get_property_rgba -->
The ::rgba property contains the currently selected color,
as a `gdk::RGBA` struct. The property can be set to change
the current selection programmatically.
<!-- trait ColorChooserExt::fn set_property_rgba -->
The ::rgba property contains the currently selected color,
as a `gdk::RGBA` struct. The property can be set to change
the current selection programmatically.
<!-- trait ColorChooserExt::fn get_property_use_alpha -->
When ::use-alpha is `true`, colors may have alpha (translucency)
information. When it is `false`, the `gdk::RGBA` struct obtained
via the `ColorChooser:rgba` property will be forced to have
alpha == 1.

Implementations are expected to show alpha by rendering the color
over a non-uniform background (like a checkerboard pattern).
<!-- trait ColorChooserExt::fn set_property_use_alpha -->
When ::use-alpha is `true`, colors may have alpha (translucency)
information. When it is `false`, the `gdk::RGBA` struct obtained
via the `ColorChooser:rgba` property will be forced to have
alpha == 1.

Implementations are expected to show alpha by rendering the color
over a non-uniform background (like a checkerboard pattern).
<!-- struct ColorChooserDialog -->
The `ColorChooserDialog` widget is a dialog for choosing
a color. It implements the `ColorChooser` interface.

# Implements

[`ColorChooserDialogExt`](trait.ColorChooserDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`ColorChooserExtManual`](prelude/trait.ColorChooserExtManual.html)
<!-- trait ColorChooserDialogExt -->
Trait containing all `ColorChooserDialog` methods.

# Implementors

[`ColorChooserDialog`](struct.ColorChooserDialog.html)
<!-- impl ColorChooserDialog::fn new -->
Creates a new `ColorChooserDialog`.
## `title`
Title of the dialog, or `None`
## `parent`
Transient parent of the dialog, or `None`

# Returns

a new `ColorChooserDialog`
<!-- struct ColorChooserWidget -->
The `ColorChooserWidget` widget lets the user select a
color. By default, the chooser presents a predefined palette
of colors, plus a small number of settable custom colors.
It is also possible to select a different color with the
single-color editor. To enter the single-color editing mode,
use the context menu of any color of the palette, or use the
'+' button to add a new custom color.

The chooser automatically remembers the last selection, as well
as custom colors.

To change the initially selected color, use `ColorChooser::set_rgba`.
To get the selected color use `ColorChooser::get_rgba`.

The `ColorChooserWidget` is used in the `ColorChooserDialog`
to provide a dialog for selecting colors.

# CSS names

`ColorChooserWidget` has a single CSS node with name colorchooser.

# Implements

[`ColorChooserWidgetExt`](trait.ColorChooserWidgetExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`ColorChooserExtManual`](prelude/trait.ColorChooserExtManual.html)
<!-- trait ColorChooserWidgetExt -->
Trait containing all `ColorChooserWidget` methods.

# Implementors

[`ColorChooserWidget`](struct.ColorChooserWidget.html)
<!-- impl ColorChooserWidget::fn new -->
Creates a new `ColorChooserWidget`.

# Returns

a new `ColorChooserWidget`
<!-- trait ColorChooserWidgetExt::fn get_property_show_editor -->
The ::show-editor property is `true` when the color chooser
is showing the single-color editor. It can be set to switch
the color chooser into single-color editing mode.
<!-- trait ColorChooserWidgetExt::fn set_property_show_editor -->
The ::show-editor property is `true` when the color chooser
is showing the single-color editor. It can be set to switch
the color chooser into single-color editing mode.
<!-- struct ComboBox -->
A `ComboBox` is a widget that allows the user to choose from a list of
valid choices. The `ComboBox` displays the selected choice. When
activated, the `ComboBox` displays a popup which allows the user to
make a new choice. The style in which the selected value is displayed,
and the style of the popup is determined by the current theme. It may
be similar to a Windows-style combo box.

The `ComboBox` uses the model-view pattern; the list of valid choices
is specified in the form of a tree model, and the display of the choices
can be adapted to the data in the model by using cell renderers, as you
would in a tree view. This is possible since `ComboBox` implements the
`CellLayout` interface. The tree model holding the valid choices is
not restricted to a flat list, it can be a real tree, and the popup will
reflect the tree structure.

To allow the user to enter values not in the model, the “has-entry”
property allows the `ComboBox` to contain a `Entry`. This entry
can be accessed by calling `BinExt::get_child` on the combo box.

For a simple list of textual choices, the model-view API of `ComboBox`
can be a bit overwhelming. In this case, `ComboBoxText` offers a
simple alternative. Both `ComboBox` and `ComboBoxText` can contain
an entry.

# CSS nodes


```plain
combobox
├── box.linked
│   ╰── button.combo
│       ╰── box
│           ├── cellview
│           ╰── arrow
╰── window.popup
```

A normal combobox contains a box with the .linked class, a button
with the .combo class and inside those buttons, there are a cellview and
an arrow.


```plain
combobox
├── box.linked
│   ├── entry.combo
│   ╰── button.combo
│       ╰── box
│           ╰── arrow
╰── window.popup
```

A `ComboBox` with an entry has a single CSS node with name combobox. It
contains a box with the .linked class. That box contains an entry and a
button, both with the .combo class added.
The button also contains another node with name arrow.

# Implements

[`ComboBoxExt`](trait.ComboBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`ComboBoxExtManual`](prelude/trait.ComboBoxExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ComboBoxExt -->
Trait containing all `ComboBox` methods.

# Implementors

[`AppChooserButton`](struct.AppChooserButton.html), [`ComboBoxText`](struct.ComboBoxText.html), [`ComboBox`](struct.ComboBox.html)
<!-- impl ComboBox::fn new -->
Creates a new empty `ComboBox`.

# Returns

A new `ComboBox`.
<!-- impl ComboBox::fn new_with_area -->
Creates a new empty `ComboBox` using `area` to layout cells.
## `area`
the `CellArea` to use to layout cell renderers

# Returns

A new `ComboBox`.
<!-- impl ComboBox::fn new_with_area_and_entry -->
Creates a new empty `ComboBox` with an entry.

The new combo box will use `area` to layout cells.
## `area`
the `CellArea` to use to layout cell renderers

# Returns

A new `ComboBox`.
<!-- impl ComboBox::fn new_with_entry -->
Creates a new empty `ComboBox` with an entry.

# Returns

A new `ComboBox`.
<!-- impl ComboBox::fn new_with_model -->
Creates a new `ComboBox` with the model initialized to `model`.
## `model`
A `TreeModel`.

# Returns

A new `ComboBox`.
<!-- impl ComboBox::fn new_with_model_and_entry -->
Creates a new empty `ComboBox` with an entry
and with the model initialized to `model`.
## `model`
A `TreeModel`

# Returns

A new `ComboBox`
<!-- trait ComboBoxExtManual::fn get_active -->
Returns the index of the currently active item, or -1 if there’s no
active item. If the model is a non-flat treemodel, and the active item
is not an immediate child of the root of the tree, this function returns
`gtk_tree_path_get_indices (path)[0]`, where
`path` is the `TreePath` of the active item.

# Returns

An integer which is the index of the currently active item,
 or -1 if there’s no active item.
<!-- trait ComboBoxExt::fn get_active_id -->
Returns the ID of the active row of `self`. This value is taken
from the active row and the column specified by the `ComboBox:id-column`
property of `self` (see `ComboBoxExt::set_id_column`).

The returned value is an interned string which means that you can
compare the pointer by value to other interned strings and that you
must not free it.

If the `ComboBox:id-column` property of `self` is not set, or if
no row is active, or if the active row has a `None` ID value, then `None`
is returned.

# Returns

the ID of the active row, or `None`
<!-- trait ComboBoxExt::fn get_active_iter -->
Sets `iter` to point to the currently active item, if any item is active.
Otherwise, `iter` is left unchanged.
## `iter`
A `TreeIter`

# Returns

`true` if `iter` was set, `false` otherwise
<!-- trait ComboBoxExt::fn get_button_sensitivity -->
Returns whether the combo box sets the dropdown button
sensitive or not when there are no items in the model.

# Returns

`SensitivityType::On` if the dropdown button
 is sensitive when the model is empty, `SensitivityType::Off`
 if the button is always insensitive or
 `SensitivityType::Auto` if it is only sensitive as long as
 the model has one item to be selected.
<!-- trait ComboBoxExt::fn get_column_span_column -->
Returns the column with column span information for `self`.

# Returns

the column span column.
<!-- trait ComboBoxExt::fn get_entry_text_column -->
Returns the column which `self` is using to get the strings
from to display in the internal entry.

# Returns

A column in the data source model of `self`.
<!-- trait ComboBoxExt::fn get_focus_on_click -->
Returns whether the combo box grabs focus when it is clicked
with the mouse. See `ComboBoxExt::set_focus_on_click`.

# Deprecated since 3.20

Use `WidgetExt::get_focus_on_click` instead

# Returns

`true` if the combo box grabs focus when it is
 clicked with the mouse.
<!-- trait ComboBoxExt::fn get_has_entry -->
Returns whether the combo box has an entry.

# Returns

whether there is an entry in `self`.
<!-- trait ComboBoxExt::fn get_id_column -->
Returns the column which `self` is using to get string IDs
for values from.

# Returns

A column in the data source model of `self`.
<!-- trait ComboBoxExt::fn get_model -->
Returns the `TreeModel` which is acting as data source for `self`.

# Returns

A `TreeModel` which was passed
 during construction.
<!-- trait ComboBoxExt::fn get_popup_accessible -->
Gets the accessible object corresponding to the combo box’s popup.

This function is mostly intended for use by accessibility technologies;
applications should have little use for it.

# Returns

the accessible object corresponding
 to the combo box’s popup.
<!-- trait ComboBoxExt::fn get_popup_fixed_width -->
Gets whether the popup uses a fixed width matching
the allocated width of the combo box.

# Returns

`true` if the popup uses a fixed width
<!-- trait ComboBoxExt::fn get_row_separator_func -->
Returns the current row separator function.

# Returns

the current row separator function.
<!-- trait ComboBoxExt::fn get_row_span_column -->
Returns the column with row span information for `self`.

# Returns

the row span column.
<!-- trait ComboBoxExt::fn get_wrap_width -->
Returns the wrap width which is used to determine the number of columns
for the popup menu. If the wrap width is larger than 1, the combo box
is in table mode.

# Returns

the wrap width.
<!-- trait ComboBoxExt::fn popdown -->
Hides the menu or dropdown list of `self`.

This function is mostly intended for use by accessibility technologies;
applications should have little use for it.
<!-- trait ComboBoxExt::fn popup -->
Pops up the menu or dropdown list of `self`.

This function is mostly intended for use by accessibility technologies;
applications should have little use for it.

Before calling this, `self` must be mapped, or nothing will happen.
<!-- trait ComboBoxExt::fn popup_for_device -->
Pops up the menu or dropdown list of `self`, the popup window
will be grabbed so only `device` and its associated pointer/keyboard
are the only ``GdkDevices`` able to send events to it.
## `device`
a `gdk::Device`
<!-- trait ComboBoxExtManual::fn set_active -->
Sets the active item of `self` to be the item at `index`.
## `index_`
An index in the model passed during construction, or -1 to have
no active item
<!-- trait ComboBoxExt::fn set_active_id -->
Changes the active row of `self` to the one that has an ID equal to
`active_id`, or unsets the active row if `active_id` is `None`. Rows having
a `None` ID string cannot be made active by this function.

If the `ComboBox:id-column` property of `self` is unset or if no
row has the given ID then the function does nothing and returns `false`.
## `active_id`
the ID of the row to select, or `None`

# Returns

`true` if a row with a matching ID was found. If a `None`
 `active_id` was given to unset the active row, the function
 always returns `true`.
<!-- trait ComboBoxExt::fn set_active_iter -->
Sets the current active item to be the one referenced by `iter`, or
unsets the active item if `iter` is `None`.
## `iter`
The `TreeIter`, or `None`
<!-- trait ComboBoxExt::fn set_button_sensitivity -->
Sets whether the dropdown button of the combo box should be
always sensitive (`SensitivityType::On`), never sensitive (`SensitivityType::Off`)
or only if there is at least one item to display (`SensitivityType::Auto`).
## `sensitivity`
specify the sensitivity of the dropdown button
<!-- trait ComboBoxExt::fn set_column_span_column -->
Sets the column with column span information for `self` to be
`column_span`. The column span column contains integers which indicate
how many columns an item should span.
## `column_span`
A column in the model passed during construction
<!-- trait ComboBoxExt::fn set_entry_text_column -->
Sets the model column which `self` should use to get strings from
to be `text_column`. The column `text_column` in the model of `self`
must be of type `G_TYPE_STRING`.

This is only relevant if `self` has been created with
`ComboBox:has-entry` as `true`.
## `text_column`
A column in `model` to get the strings from for
 the internal entry
<!-- trait ComboBoxExt::fn set_focus_on_click -->
Sets whether the combo box will 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.

# Deprecated since 3.20

Use `WidgetExt::set_focus_on_click` instead
## `focus_on_click`
whether the combo box grabs focus when clicked
 with the mouse
<!-- trait ComboBoxExt::fn set_id_column -->
Sets the model column which `self` should use to get string IDs
for values from. The column `id_column` in the model of `self`
must be of type `G_TYPE_STRING`.
## `id_column`
A column in `model` to get string IDs for values from
<!-- trait ComboBoxExt::fn set_model -->
Sets the model used by `self` to be `model`. Will unset a previously set
model (if applicable). If model is `None`, then it will unset the model.

Note that this function does not clear the cell renderers, you have to
call `CellLayout::clear` yourself if you need to set up different
cell renderers for the new model.
## `model`
A `TreeModel`
<!-- trait ComboBoxExt::fn set_popup_fixed_width -->
Specifies whether the popup’s width should be a fixed width
matching the allocated width of the combo box.
## `fixed`
whether to use a fixed popup width
<!-- trait ComboBoxExt::fn set_row_separator_func -->
Sets the row separator function, which is used to determine
whether a row should be drawn as a separator. If the row separator
function is `None`, no separators are drawn. This is the default value.
## `func`
a ``GtkTreeViewRowSeparatorFunc``
## `data`
user data to pass to `func`, or `None`
## `destroy`
destroy notifier for `data`, or `None`
<!-- trait ComboBoxExt::fn set_row_span_column -->
Sets the column with row span information for `self` to be `row_span`.
The row span column contains integers which indicate how many rows
an item should span.
## `row_span`
A column in the model passed during construction.
<!-- trait ComboBoxExt::fn set_wrap_width -->
Sets the wrap width of `self` to be `width`. The wrap width is basically
the preferred number of columns when you want the popup to be layed out
in a table.
## `width`
Preferred number of columns
<!-- trait ComboBoxExt::fn connect_changed -->
The changed signal is emitted when the active
item is changed. The can be due to the user selecting
a different item from the list, or due to a
call to `ComboBoxExt::set_active_iter`.
It will also be emitted while typing into the entry of a combo box
with an entry.
<!-- trait ComboBoxExt::fn connect_format_entry_text -->
For combo boxes that are created with an entry (See `ComboBox`:has-entry).

A signal which allows you to change how the text displayed in a combo box's
entry is displayed.

Connect a signal handler which returns an allocated string representing
`path`. That string will then be used to set the text in the combo box's entry.
The default signal handler uses the text from the `ComboBox`::entry-text-column
model column.

Here's an example signal handler which fetches data from the model and
displays it in the entry.

```C
static gchar*
format_entry_text_callback (GtkComboBox *combo,
                            const gchar *path,
                            gpointer     user_data)
{
  GtkTreeIter iter;
  GtkTreeModel model;
  gdouble      value;

  model = gtk_combo_box_get_model (combo);

  gtk_tree_model_get_iter_from_string (model, &iter, path);
  gtk_tree_model_get (model, &iter,
                      THE_DOUBLE_VALUE_COLUMN, &value,
                      -1);

  return g_strdup_printf ("%g", value);
}
```
## `path`
the `TreePath` string from the combo box's current model to format text for

# Returns

a newly allocated string representing `path`
for the current `ComboBox` model.
<!-- trait ComboBoxExt::fn connect_move_active -->
The ::move-active signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to move the active selection.
## `scroll_type`
a `ScrollType`
<!-- trait ComboBoxExt::fn connect_popdown -->
The ::popdown signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to popdown the combo box list.

The default bindings for this signal are Alt+Up and Escape.
<!-- trait ComboBoxExt::fn connect_popup -->
The ::popup signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to popup the combo box list.

The default binding for this signal is Alt+Down.
<!-- trait ComboBoxExt::fn get_property_active -->
The item which is currently active. If the model is a non-flat treemodel,
and the active item is not an immediate child of the root of the tree,
this property has the value
`gtk_tree_path_get_indices (path)[0]`,
where `path` is the `TreePath` of the active item.
<!-- trait ComboBoxExt::fn set_property_active -->
The item which is currently active. If the model is a non-flat treemodel,
and the active item is not an immediate child of the root of the tree,
this property has the value
`gtk_tree_path_get_indices (path)[0]`,
where `path` is the `TreePath` of the active item.
<!-- trait ComboBoxExt::fn get_property_active_id -->
The value of the ID column of the active row.
<!-- trait ComboBoxExt::fn set_property_active_id -->
The value of the ID column of the active row.
<!-- trait ComboBoxExt::fn get_property_button_sensitivity -->
Whether the dropdown button is sensitive when
the model is empty.
<!-- trait ComboBoxExt::fn set_property_button_sensitivity -->
Whether the dropdown button is sensitive when
the model is empty.
<!-- trait ComboBoxExt::fn get_property_cell_area -->
The `CellArea` used to layout cell renderers for this combo box.

If no area is specified when creating the combo box with `ComboBox::new_with_area`
a horizontally oriented `CellAreaBox` will be used.
<!-- trait ComboBoxExt::fn set_property_cell_area -->
The `CellArea` used to layout cell renderers for this combo box.

If no area is specified when creating the combo box with `ComboBox::new_with_area`
a horizontally oriented `CellAreaBox` will be used.
<!-- trait ComboBoxExt::fn get_property_column_span_column -->
If this is set to a non-negative value, it must be the index of a column
of type `G_TYPE_INT` in the model. The value in that column for each item
will determine how many columns that item will span in the popup.
Therefore, values in this column must be greater than zero, and the sum of
an item’s column position + span should not exceed `ComboBox:wrap-width`.
<!-- trait ComboBoxExt::fn set_property_column_span_column -->
If this is set to a non-negative value, it must be the index of a column
of type `G_TYPE_INT` in the model. The value in that column for each item
will determine how many columns that item will span in the popup.
Therefore, values in this column must be greater than zero, and the sum of
an item’s column position + span should not exceed `ComboBox:wrap-width`.
<!-- trait ComboBoxExt::fn get_property_entry_text_column -->
The column in the combo box's model to associate with strings from the entry
if the combo was created with `ComboBox:has-entry` = `true`.
<!-- trait ComboBoxExt::fn set_property_entry_text_column -->
The column in the combo box's model to associate with strings from the entry
if the combo was created with `ComboBox:has-entry` = `true`.
<!-- trait ComboBoxExt::fn get_property_has_entry -->
Whether the combo box has an entry.
<!-- trait ComboBoxExt::fn set_property_has_entry -->
Whether the combo box has an entry.
<!-- trait ComboBoxExt::fn get_property_has_frame -->
The has-frame property controls whether a frame
is drawn around the entry.
<!-- trait ComboBoxExt::fn set_property_has_frame -->
The has-frame property controls whether a frame
is drawn around the entry.
<!-- trait ComboBoxExt::fn get_property_id_column -->
The column in the combo box's model that provides string
IDs for the values in the model, if != -1.
<!-- trait ComboBoxExt::fn set_property_id_column -->
The column in the combo box's model that provides string
IDs for the values in the model, if != -1.
<!-- trait ComboBoxExt::fn get_property_model -->
The model from which the combo box takes the values shown
in the list.
<!-- trait ComboBoxExt::fn set_property_model -->
The model from which the combo box takes the values shown
in the list.
<!-- trait ComboBoxExt::fn get_property_popup_fixed_width -->
Whether the popup's width should be a fixed width matching the
allocated width of the combo box.
<!-- trait ComboBoxExt::fn set_property_popup_fixed_width -->
Whether the popup's width should be a fixed width matching the
allocated width of the combo box.
<!-- trait ComboBoxExt::fn get_property_popup_shown -->
Whether the combo boxes dropdown is popped up.
Note that this property is mainly useful, because
it allows you to connect to notify::popup-shown.
<!-- trait ComboBoxExt::fn get_property_row_span_column -->
If this is set to a non-negative value, it must be the index of a column
of type `G_TYPE_INT` in the model. The value in that column for each item
will determine how many rows that item will span in the popup. Therefore,
values in this column must be greater than zero.
<!-- trait ComboBoxExt::fn set_property_row_span_column -->
If this is set to a non-negative value, it must be the index of a column
of type `G_TYPE_INT` in the model. The value in that column for each item
will determine how many rows that item will span in the popup. Therefore,
values in this column must be greater than zero.
<!-- trait ComboBoxExt::fn get_property_wrap_width -->
If wrap-width is set to a positive value, items in the popup will be laid
out along multiple columns, starting a new row on reaching the wrap width.
<!-- trait ComboBoxExt::fn set_property_wrap_width -->
If wrap-width is set to a positive value, items in the popup will be laid
out along multiple columns, starting a new row on reaching the wrap width.
<!-- struct ComboBoxText -->
A `ComboBoxText` is a simple variant of `ComboBox` that hides
the model-view complexity for simple text-only use cases.

To create a `ComboBoxText`, use `ComboBoxText::new` or
`ComboBoxText::new_with_entry`.

You can add items to a `ComboBoxText` with
`ComboBoxTextExt::append_text`, `ComboBoxTextExt::insert_text`
or `ComboBoxTextExt::prepend_text` and remove options with
`ComboBoxTextExt::remove`.

If the `ComboBoxText` contains an entry (via the “has-entry” property),
its contents can be retrieved using `ComboBoxTextExt::get_active_text`.
The entry itself can be accessed by calling `BinExt::get_child` on the
combo box.

You should not call `ComboBoxExt::set_model` or attempt to pack more cells
into this combo box via its `CellLayout` interface.

# `ComboBoxText` as `Buildable`

The `ComboBoxText` implementation of the `Buildable` interface supports
adding items directly using the `<items>` element and specifying `<item>`
elements for each item. Each `<item>` element can specify the “id”
corresponding to the appended text and also supports the regular
translation attributes “translatable”, “context” and “comments”.

Here is a UI definition fragment specifying `ComboBoxText` items:

```plain
combobox
╰── box.linked
    ├── entry.combo
    ├── button.combo
    ╰── window.popup
```

`ComboBoxText` has a single CSS node with name combobox. It adds
the style class .combo to the main CSS nodes of its entry and button
children, and the .linked class to the node of its internal box.

# Implements

[`ComboBoxTextExt`](trait.ComboBoxTextExt.html), [`ComboBoxExt`](trait.ComboBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`ComboBoxExtManual`](prelude/trait.ComboBoxExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ComboBoxTextExt -->
Trait containing all `ComboBoxText` methods.

# Implementors

[`ComboBoxText`](struct.ComboBoxText.html)
<!-- impl ComboBoxText::fn new -->
Creates a new `ComboBoxText`, which is a `ComboBox` just displaying
strings.

# Returns

A new `ComboBoxText`
<!-- impl ComboBoxText::fn new_with_entry -->
Creates a new `ComboBoxText`, which is a `ComboBox` just displaying
strings. The combo box created by this function has an entry.

# Returns

a new `ComboBoxText`
<!-- trait ComboBoxTextExt::fn append -->
Appends `text` to the list of strings stored in `self`.
If `id` is non-`None` then it is used as the ID of the row.

This is the same as calling `ComboBoxTextExt::insert` with a
position of -1.
## `id`
a string ID for this value, or `None`
## `text`
A string
<!-- trait ComboBoxTextExt::fn append_text -->
Appends `text` to the list of strings stored in `self`.

This is the same as calling `ComboBoxTextExt::insert_text` with a
position of -1.
## `text`
A string
<!-- trait ComboBoxTextExt::fn get_active_text -->
Returns the currently active string in `self`, or `None`
if none is selected. If `self` contains an entry, this
function will return its contents (which will not necessarily
be an item from the list).

# Returns

a newly allocated string containing the
 currently active text. Must be freed with `g_free`.
<!-- trait ComboBoxTextExt::fn insert -->
Inserts `text` at `position` in the list of strings stored in `self`.
If `id` is non-`None` then it is used as the ID of the row. See
`ComboBox:id-column`.

If `position` is negative then `text` is appended.
## `position`
An index to insert `text`
## `id`
a string ID for this value, or `None`
## `text`
A string to display
<!-- trait ComboBoxTextExt::fn insert_text -->
Inserts `text` at `position` in the list of strings stored in `self`.

If `position` is negative then `text` is appended.

This is the same as calling `ComboBoxTextExt::insert` with a `None`
ID string.
## `position`
An index to insert `text`
## `text`
A string
<!-- trait ComboBoxTextExt::fn prepend -->
Prepends `text` to the list of strings stored in `self`.
If `id` is non-`None` then it is used as the ID of the row.

This is the same as calling `ComboBoxTextExt::insert` with a
position of 0.
## `id`
a string ID for this value, or `None`
## `text`
a string
<!-- trait ComboBoxTextExt::fn prepend_text -->
Prepends `text` to the list of strings stored in `self`.

This is the same as calling `ComboBoxTextExt::insert_text` with a
position of 0.
## `text`
A string
<!-- trait ComboBoxTextExt::fn remove -->
Removes the string at `position` from `self`.
## `position`
Index of the item to remove
<!-- trait ComboBoxTextExt::fn remove_all -->
Removes all the text entries from the combo box.
<!-- struct Container -->
A GTK+ user interface is constructed by nesting widgets inside widgets.
Container widgets are the inner nodes in the resulting tree of widgets:
they contain other widgets. So, for example, you might have a `Window`
containing a `Frame` containing a `Label`. If you wanted an image instead
of a textual label inside the frame, you might replace the `Label` widget
with a `Image` widget.

There are two major kinds of container widgets in GTK+. Both are subclasses
of the abstract `Container` base class.

The first type of container widget has a single child widget and derives
from `Bin`. These containers are decorators, which
add some kind of functionality to the child. For example, a `Button` makes
its child into a clickable button; a `Frame` draws a frame around its child
and a `Window` places its child widget inside a top-level window.

The second type of container can have more than one child; its purpose is to
manage layout. This means that these containers assign
sizes and positions to their children. For example, a `HBox` arranges its
children in a horizontal row, and a `Grid` arranges the widgets it contains
in a two-dimensional grid.

For implementations of `Container` the virtual method `ContainerClass.forall`()
is always required, since it's used for drawing and other internal operations
on the children.
If the `Container` implementation expect to have non internal children
it's needed to implement both `ContainerClass.add`() and `ContainerClass.remove`().
If the `Container` implementation has internal children, they should be added
with `WidgetExt::set_parent` on `init` and removed with `WidgetExt::unparent`
in the `WidgetClass.destroy`() implementation.
See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets

# 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).

There are some things to keep in mind when implementing container widgets
that make use of GTK+’s height for width geometry management system. First,
it’s important to note that a container must prioritize one of its
dimensions, that is to say that a widget or container can only have a
`SizeRequestMode` that is `SizeRequestMode::HeightForWidth` or
`SizeRequestMode::WidthForHeight`. However, every widget and container
must be able to respond to the APIs for both dimensions, i.e. even if a
widget has a request mode that is height-for-width, it is possible that
its parent will request its sizes using the width-for-height APIs.

To ensure that everything works properly, here are some guidelines to follow
when implementing height-for-width (or width-for-height) containers.

Each request mode involves 2 virtual methods. Height-for-width apis run
through `WidgetExt::get_preferred_width` and then through `WidgetExt::get_preferred_height_for_width`.
When handling requests in the opposite `SizeRequestMode` it is important that
every widget request at least enough space to display all of its content at all times.

When `WidgetExt::get_preferred_height` is called on a container that is height-for-width,
the container must return the height for its minimum width. This is easily achieved by
simply calling the reverse apis implemented for itself as follows:


```C
static void
foo_container_get_preferred_height (GtkWidget *widget,
                                    gint *min_height,
                                    gint *nat_height)
{
   if (i_am_in_height_for_width_mode)
     {
       gint min_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           &min_width,
                                                           NULL);
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
                                                          (widget,
                                                           min_width,
                                                           min_height,
                                                           nat_height);
     }
   else
     {
       ... many containers support both request modes, execute the
       real width-for-height request here by returning the
       collective heights of all widgets that are stacked
       vertically (or whatever is appropriate for this container)
       ...
     }
}
```

Similarly, when `WidgetExt::get_preferred_width_for_height` is called for a container or widget
that is height-for-width, it then only needs to return the base minimum width like so:


```C
static void
foo_container_get_preferred_width_for_height (GtkWidget *widget,
                                              gint for_height,
                                              gint *min_width,
                                              gint *nat_width)
{
   if (i_am_in_height_for_width_mode)
     {
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           min_width,
                                                           nat_width);
     }
   else
     {
       ... execute the real width-for-height request here based on
       the required width of the children collectively if the
       container were to be allocated the said height ...
     }
}
```

Height for width requests are generally implemented in terms of a virtual allocation
of widgets in the input orientation. Assuming an height-for-width request mode, a container
would implement the `get_preferred_height_for_width` virtual function by first calling
`WidgetExt::get_preferred_width` for each of its children.

For each potential group of children that are lined up horizontally, the values returned by
`WidgetExt::get_preferred_width` should be collected in an array of `RequestedSize` structures.
Any child spacing should be removed from the input `for_width` and then the collective size should be
allocated using the `gtk_distribute_natural_allocation` convenience function.

The container will then move on to request the preferred height for each child by using
`WidgetExt::get_preferred_height_for_width` and using the sizes stored in the `RequestedSize` array.

To allocate a height-for-width container, it’s again important
to consider that a container must prioritize one dimension over the other. So if
a container is a height-for-width container it must first allocate all widgets horizontally
using a `RequestedSize` array and `gtk_distribute_natural_allocation` and then add any
extra space (if and where appropriate) for the widget to expand.

After adding all the expand space, the container assumes it was allocated sufficient
height to fit all of its content. At this time, the container must use the total horizontal sizes
of each widget to request the height-for-width of each of its children and store the requests in a
`RequestedSize` array for any widgets that stack vertically (for tabular containers this can
be generalized into the heights and widths of rows and columns).
The vertical space must then again be distributed using `gtk_distribute_natural_allocation`
while this time considering the allocated height of the widget minus any vertical spacing
that the container adds. Then vertical expand space should be added where appropriate and available
and the container should go on to actually allocating the child widgets.

See [`Widget`’s geometry management section][geometry-management]
to learn more about implementing height-for-width geometry management for widgets.

# Child properties

`Container` introduces child properties.
These are object properties that are not specific
to either the container or the contained widget, but rather to their relation.
Typical examples of child properties are the position or pack-type of a widget
which is contained in a `Box`.

Use `ContainerClass::install_child_property` to install child properties
for a container class and `ContainerClass::find_child_property` or
`ContainerClass::list_child_properties` to get information about existing
child properties.

To set the value of a child property, use `Container::child_set_property`,
`ContainerExt::child_set` or `ContainerExt::child_set_valist`.
To obtain the value of a child property, use
`Container::child_get_property`, `ContainerExt::child_get` or
`ContainerExt::child_get_valist`. To emit notification about child property
changes, use `WidgetExt::child_notify`.

# `Container` as `Buildable`

The `Container` implementation of the `Buildable` interface supports
a `<packing>` element for children, which can contain multiple `<property>`
elements that specify child properties for the child.

Since 2.16, child properties can also be marked as translatable using
the same “translatable”, “comments” and “context” attributes that are used
for regular properties.

Since 3.16, containers can have a `<focus-chain>` element containing multiple
`<widget>` elements, one for each child that should be added to the focus
chain. The ”name” attribute gives the id of the widget.

An example of these properties in UI definitions:

```text
<object class="GtkBox">
  <child>
    <object class="GtkEntry" id="entry1"/>
    <packing>
      <property name="pack-type">start</property>
    </packing>
  </child>
  <child>
    <object class="GtkEntry" id="entry2"/>
  </child>
  <focus-chain>
    <widget name="entry1"/>
    <widget name="entry2"/>
  </focus-chain>
</object>
```

# Implements

[`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ContainerExt -->
Trait containing all `Container` methods.

# Implementors

[`Bin`](struct.Bin.html), [`Box`](struct.Box.html), [`Container`](struct.Container.html), [`Fixed`](struct.Fixed.html), [`FlowBox`](struct.FlowBox.html), [`Grid`](struct.Grid.html), [`HeaderBar`](struct.HeaderBar.html), [`IconView`](struct.IconView.html), [`Layout`](struct.Layout.html), [`ListBox`](struct.ListBox.html), [`MenuShell`](struct.MenuShell.html), [`Notebook`](struct.Notebook.html), [`Paned`](struct.Paned.html), [`Socket`](struct.Socket.html), [`Stack`](struct.Stack.html), [`TextView`](struct.TextView.html), [`ToolItemGroup`](struct.ToolItemGroup.html), [`ToolPalette`](struct.ToolPalette.html), [`Toolbar`](struct.Toolbar.html), [`TreeView`](struct.TreeView.html)
<!-- trait ContainerExt::fn add -->
Adds `widget` to `self`. Typically used for simple containers
such as `Window`, `Frame`, or `Button`; for more complicated
layout containers such as `Box` or `Grid`, this function will
pick default packing parameters that may not be correct. So
consider functions such as `BoxExt::pack_start` and
`GridExt::attach` as an alternative to `ContainerExt::add` in
those cases. A widget may be added to only one container at a time;
you can’t place the same widget inside two different containers.

Note that some containers, such as `ScrolledWindow` or `ListBox`,
may add intermediate children between the added widget and the
container.
## `widget`
a widget to be placed inside `self`
<!-- trait ContainerExt::fn add_with_properties -->
Adds `widget` to `self`, setting child properties at the same time.
See `ContainerExt::add` and `ContainerExt::child_set` for more details.
## `widget`
a widget to be placed inside `self`
## `first_prop_name`
the name of the first child property to set
<!-- trait ContainerExt::fn child_get -->
Gets the values of one or more child properties for `child` and `self`.
## `child`
a widget which is a child of `self`
## `first_prop_name`
the name of the first property to get
<!-- trait ContainerExt::fn child_get_property -->
Gets the value of a child property for `child` and `self`.
## `child`
a widget which is a child of `self`
## `property_name`
the name of the property to get
## `value`
a location to return the value
<!-- trait ContainerExt::fn child_get_valist -->
Gets the values of one or more child properties for `child` and `self`.
## `child`
a widget which is a child of `self`
## `first_property_name`
the name of the first property to get
## `var_args`
return location for the first property, followed
 optionally by more name/return location pairs, followed by `None`
<!-- trait ContainerExt::fn child_notify -->
Emits a `Widget::child-notify` signal for the
[child property][child-properties]
`child_property` on the child.

This is an analogue of `gobject::ObjectExt::notify` for child properties.

Also see `WidgetExt::child_notify`.
## `child`
the child widget
## `child_property`
the name of a child property installed on
 the class of `self`
<!-- trait ContainerExt::fn child_notify_by_pspec -->
Emits a `Widget::child-notify` signal for the
[child property][child-properties] specified by
`pspec` on the child.

This is an analogue of `gobject::ObjectExt::notify_by_pspec` for child properties.

Feature: `v3_18`

## `child`
the child widget
## `pspec`
the `gobject::ParamSpec` of a child property instealled on
 the class of `self`
<!-- trait ContainerExt::fn child_set -->
Sets one or more child properties for `child` and `self`.
## `child`
a widget which is a child of `self`
## `first_prop_name`
the name of the first property to set
<!-- trait ContainerExt::fn child_set_property -->
Sets a child property for `child` and `self`.
## `child`
a widget which is a child of `self`
## `property_name`
the name of the property to set
## `value`
the value to set the property to
<!-- trait ContainerExt::fn child_set_valist -->
Sets one or more child properties for `child` and `self`.
## `child`
a widget which is a child of `self`
## `first_property_name`
the name of the first property to set
## `var_args`
a `None`-terminated list of property names and values, starting
 with `first_prop_name`
<!-- trait ContainerExt::fn child_type -->
Returns the type of the children supported by the container.

Note that this may return `G_TYPE_NONE` to indicate that no more
children can be added, e.g. for a `Paned` which already has two
children.

# Returns

a `glib::Type`.
<!-- trait ContainerExt::fn forall -->
Invokes `callback` on each direct child of `self`, including
children that are considered “internal” (implementation details
of the container). “Internal” children generally weren’t added
by the user of the container, but were added by the container
implementation itself.

Most applications should use `ContainerExt::foreach`, rather
than `ContainerExt::forall`.
## `callback`
a callback
## `callback_data`
callback user data
<!-- trait ContainerExt::fn foreach -->
Invokes `callback` on each non-internal child of `self`.
See `ContainerExt::forall` for details on what constitutes
an “internal” child. For all practical purposes, this function
should iterate over precisely those child widgets that were
added to the container by the application with explicit `add`
calls.

It is permissible to remove the child from the `callback` handler.

Most applications should use `ContainerExt::foreach`,
rather than `ContainerExt::forall`.
## `callback`
a callback
## `callback_data`
callback user data
<!-- trait ContainerExt::fn get_border_width -->
Retrieves the border width of the container. See
`ContainerExt::set_border_width`.

# Returns

the current border width
<!-- trait ContainerExt::fn get_children -->
Returns the container’s non-internal children. See
`ContainerExt::forall` for details on what constitutes an "internal" child.

# Returns

a newly-allocated list of the container’s non-internal children.
<!-- trait ContainerExt::fn get_focus_chain -->
Retrieves the focus chain of the container, if one has been
set explicitly. If no focus chain has been explicitly
set, GTK+ computes the focus chain based on the positions
of the children. In that case, GTK+ stores `None` in
`focusable_widgets` and returns `false`.

# Deprecated since 3.24

For overriding focus behavior, use the
 `WidgetClass`::focus signal.
## `focusable_widgets`
location
 to store the focus chain of the
 container, or `None`. You should free this list
 using `glib::List::free` when you are done with it, however
 no additional reference count is added to the
 individual widgets in the focus chain.

# Returns

`true` if the focus chain of the container
has been set explicitly.
<!-- trait ContainerExt::fn get_focus_child -->
Returns the current focus child widget inside `self`. This is not the
currently focused widget. That can be obtained by calling
`GtkWindowExt::get_focus`.

# Returns

The child widget which will receive the
 focus inside `self` when the `self` is focused,
 or `None` if none is set.
<!-- trait ContainerExt::fn get_focus_hadjustment -->
Retrieves the horizontal focus adjustment for the container. See
gtk_container_set_focus_hadjustment ().

# Returns

the horizontal focus adjustment, or `None` if
 none has been set.
<!-- trait ContainerExt::fn get_focus_vadjustment -->
Retrieves the vertical focus adjustment for the container. See
`ContainerExt::set_focus_vadjustment`.

# Returns

the vertical focus adjustment, or
 `None` if none has been set.
<!-- trait ContainerExt::fn get_path_for_child -->
Returns a newly created widget path representing all the widget hierarchy
from the toplevel down to and including `child`.
## `child`
a child of `self`

# Returns

A newly created `WidgetPath`
<!-- trait ContainerExt::fn propagate_draw -->
When a container receives a call to the draw function, it must send
synthetic `Widget::draw` calls to all children that don’t have their
own ``GdkWindows``. This function provides a convenient way of doing this.
A container, when it receives a call to its `Widget::draw` function,
calls `ContainerExt::propagate_draw` once for each child, passing in
the `cr` the container received.

`ContainerExt::propagate_draw` takes care of translating the origin of `cr`,
and deciding whether the draw needs to be sent to the child. It is a
convenient and optimized way of getting the same effect as calling
`WidgetExt::draw` on the child directly.

In most cases, a container can simply either inherit the
`Widget::draw` implementation from `Container`, or do some drawing
and then chain to the ::draw implementation from `Container`.
## `child`
a child of `self`
## `cr`
Cairo context as passed to the container. If you want to use `cr`
 in container’s draw function, consider using `cairo_save` and
 `cairo_restore` before calling this function.
<!-- trait ContainerExt::fn remove -->
Removes `widget` from `self`. `widget` must be inside `self`.
Note that `self` will own a reference to `widget`, and that this
may be the last reference held; so removing a widget from its
container can destroy that widget. If you want to use `widget`
again, you need to add a reference to it before removing it from
a container, using `gobject::ObjectExt::ref`. If you don’t want to use `widget`
again it’s usually more efficient to simply destroy it directly
using `Widget::destroy` since this will remove it from the
container and help break any circular reference count cycles.
## `widget`
a current child of `self`
<!-- trait ContainerExt::fn set_border_width -->
Sets the border width of the container.

The border width of a container is the amount of space to leave
around the outside of the container. The only exception to this is
`Window`; because toplevel windows can’t leave space outside,
they leave the space inside. The border is added on all sides of
the container. To add space to only one side, use a specific
`Widget:margin` property on the child widget, for example
`Widget:margin-top`.
## `border_width`
amount of blank space to leave outside
 the container. Valid values are in the range 0-65535 pixels.
<!-- trait ContainerExt::fn set_focus_chain -->
Sets a focus chain, overriding the one computed automatically by GTK+.

In principle each widget in the chain should be a descendant of the
container, but this is not enforced by this method, since it’s allowed
to set the focus chain before you pack the widgets, or have a widget
in the chain that isn’t always packed. The necessary checks are done
when the focus chain is actually traversed.

# Deprecated since 3.24

For overriding focus behavior, use the
 `WidgetClass`::focus signal.
## `focusable_widgets`

 the new focus chain
<!-- trait ContainerExt::fn set_focus_child -->
Sets, or unsets if `child` is `None`, the focused child of `self`.

This function emits the `Container`::set_focus_child signal of
`self`. Implementations of `Container` can override the
default behaviour by overriding the class closure of this signal.

This is function is mostly meant to be used by widgets. Applications can use
`WidgetExt::grab_focus` to manually set the focus to a specific widget.
## `child`
a `Widget`, or `None`
<!-- trait ContainerExt::fn set_focus_hadjustment -->
Hooks up an adjustment to focus handling in a container, so when a child
of the container is focused, the adjustment is scrolled to show that
widget. This function sets the horizontal alignment.
See `ScrolledWindowExt::get_hadjustment` for a typical way of obtaining
the adjustment and `ContainerExt::set_focus_vadjustment` for setting
the vertical adjustment.

The adjustments have to be in pixel units and in the same coordinate
system as the allocation for immediate children of the container.
## `adjustment`
an adjustment which should be adjusted when the focus is
 moved among the descendents of `self`
<!-- trait ContainerExt::fn set_focus_vadjustment -->
Hooks up an adjustment to focus handling in a container, so when a
child of the container is focused, the adjustment is scrolled to
show that widget. This function sets the vertical alignment. See
`ScrolledWindowExt::get_vadjustment` for a typical way of obtaining
the adjustment and `ContainerExt::set_focus_hadjustment` for setting
the horizontal adjustment.

The adjustments have to be in pixel units and in the same coordinate
system as the allocation for immediate children of the container.
## `adjustment`
an adjustment which should be adjusted when the focus
 is moved among the descendents of `self`
<!-- trait ContainerExt::fn unset_focus_chain -->
Removes a focus chain explicitly set with `ContainerExt::set_focus_chain`.

# Deprecated since 3.24

For overriding focus behavior, use the
 `WidgetClass`::focus signal.
<!-- enum CornerType -->
Specifies which corner a child widget should be placed in when packed into
a `ScrolledWindow`. This is effectively the opposite of where the scroll
bars are placed.
<!-- enum CornerType::variant TopLeft -->
Place the scrollbars on the right and bottom of the
 widget (default behaviour).
<!-- enum CornerType::variant BottomLeft -->
Place the scrollbars on the top and right of the
 widget.
<!-- enum CornerType::variant TopRight -->
Place the scrollbars on the left and bottom of the
 widget.
<!-- enum CornerType::variant BottomRight -->
Place the scrollbars on the top and left of the
 widget.
<!-- struct CssProvider -->
`CssProvider` is an object implementing the `StyleProvider` interface.
It is able to parse [CSS-like][css-overview] input in order to style widgets.

An application can make GTK+ parse a specific CSS style sheet by calling
`CssProviderExt::load_from_file` or `CssProviderExt::load_from_resource`
and adding the provider with `StyleContextExt::add_provider` or
`StyleContext::add_provider_for_screen`.

In addition, certain files will be read when GTK+ is initialized. First, the
file `$XDG_CONFIG_HOME/gtk-3.0/gtk.css` is loaded if it exists. Then, GTK+
loads the first existing file among
`XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk.css`,
`$HOME/.themes/THEME/gtk-VERSION/gtk.css`,
`$XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk.css` and
`DATADIR/share/themes/THEME/gtk-VERSION/gtk.css`, where `THEME` is the name of
the current theme (see the `Settings:gtk-theme-name` setting), `DATADIR`
is the prefix configured when GTK+ was compiled (unless overridden by the
`GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK+ version number.
If no file is found for the current version, GTK+ tries older versions all the
way back to 3.0.

In the same way, GTK+ tries to load a gtk-keys.css file for the current
key theme, as defined by `Settings:gtk-key-theme-name`.

# Implements

[`CssProviderExt`](trait.CssProviderExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`StyleProviderExt`](trait.StyleProviderExt.html)
<!-- trait CssProviderExt -->
Trait containing all `CssProvider` methods.

# Implementors

[`CssProvider`](struct.CssProvider.html)
<!-- impl CssProvider::fn new -->
Returns a newly created `CssProvider`.

# Returns

A new `CssProvider`
<!-- impl CssProvider::fn get_default -->
Returns the provider containing the style settings used as a
fallback for all widgets.

# Deprecated since 3.24

Use `CssProvider::new` instead.

# Returns

The provider used for fallback styling.
 This memory is owned by GTK+, and you must not free it.
<!-- impl CssProvider::fn get_named -->
Loads a theme from the usual theme paths
## `name`
A theme name
## `variant`
variant to load, for example, "dark", or
 `None` for the default

# Returns

a `CssProvider` with the theme loaded.
 This memory is owned by GTK+, and you must not free it.
<!-- trait CssProviderExt::fn load_from_data -->
Loads `data` into `self`, and by doing so clears any previously loaded
information.
## `data`
CSS data loaded in memory
## `length`
the length of `data` in bytes, or -1 for NUL terminated strings. If
 `length` is not -1, the code will assume it is not NUL terminated and will
 potentially do a copy.

# Returns

`true`. The return value is deprecated and `false` will only be
 returned for backwards compatibility reasons if an `error` is not
 `None` and a loading error occurred. To track errors while loading
 CSS, connect to the `CssProvider::parsing-error` signal.
<!-- trait CssProviderExt::fn load_from_file -->
Loads the data contained in `file` into `self`, making it
clear any previously loaded information.
## `file`
`gio::File` pointing to a file to load

# Returns

`true`. The return value is deprecated and `false` will only be
 returned for backwards compatibility reasons if an `error` is not
 `None` and a loading error occurred. To track errors while loading
 CSS, connect to the `CssProvider::parsing-error` signal.
<!-- trait CssProviderExt::fn load_from_path -->
Loads the data contained in `path` into `self`, making it clear
any previously loaded information.
## `path`
the path of a filename to load, in the GLib filename encoding

# Returns

`true`. The return value is deprecated and `false` will only be
 returned for backwards compatibility reasons if an `error` is not
 `None` and a loading error occurred. To track errors while loading
 CSS, connect to the `CssProvider::parsing-error` signal.
<!-- trait CssProviderExt::fn load_from_resource -->
Loads the data contained in the resource at `resource_path` into
the `CssProvider`, clearing any previously loaded information.

To track errors while loading CSS, connect to the
`CssProvider::parsing-error` signal.

Feature: `v3_16`

## `resource_path`
a `gio::Resource` resource path
<!-- trait CssProviderExt::fn to_string -->
Converts the `self` into a string representation in CSS
format.

Using `CssProviderExt::load_from_data` with the return value
from this function on a new provider created with
`CssProvider::new` will basically create a duplicate of
this `self`.

# Returns

a new string representing the `self`.
<!-- trait CssProviderExt::fn connect_parsing_error -->
Signals that a parsing error occurred. the `path`, `line` and `position`
describe the actual location of the error as accurately as possible.

Parsing errors are never fatal, so the parsing will resume after
the error. Errors may however cause parts of the given
data or even all of it to not be parsed at all. So it is a useful idea
to check that the parsing succeeds by connecting to this signal.

Note that this signal may be emitted at any time as the css provider
may opt to defer parsing parts or all of the input to a later time
than when a loading function was called.
## `section`
section the error happened in
## `error`
The parsing error
<!-- enum CssProviderError -->
Error codes for `GTK_CSS_PROVIDER_ERROR`.
<!-- enum CssProviderError::variant Failed -->
Failed.
<!-- enum CssProviderError::variant Syntax -->
Syntax error.
<!-- enum CssProviderError::variant Import -->
Import error.
<!-- enum CssProviderError::variant Name -->
Name error.
<!-- enum CssProviderError::variant Deprecated -->
Deprecation error.
<!-- enum CssProviderError::variant UnknownValue -->
Unknown value.
<!-- struct CssSection -->
Defines a part of a CSS document. Because sections are nested into
one another, you can use `CssSection::get_parent` to get the
containing region.
<!-- impl CssSection::fn get_end_line -->
Returns the line in the CSS document where this section end.
The line number is 0-indexed, so the first line of the document
will return 0.
This value may change in future invocations of this function if
`self` is not yet parsed completely. This will for example
happen in the `CssProvider`::parsing-error signal.
The end position and line may be identical to the start
position and line for sections which failed to parse anything
successfully.

# Returns

the line number
<!-- impl CssSection::fn get_end_position -->
Returns the offset in bytes from the start of the current line
returned via `CssSection::get_end_line`.
This value may change in future invocations of this function if
`self` is not yet parsed completely. This will for example
happen in the `CssProvider`::parsing-error signal.
The end position and line may be identical to the start
position and line for sections which failed to parse anything
successfully.

# Returns

the offset in bytes from the start of the line.
<!-- impl CssSection::fn get_file -->
Gets the file that `self` was parsed from. If no such file exists,
for example because the CSS was loaded via
`CssProviderExt::load_from_data`(), then `None` is returned.

# Returns

the `gio::File` that `self` was parsed from
 or `None` if `self` was parsed from other data
<!-- impl CssSection::fn get_parent -->
Gets the parent section for the given `self`. The parent section is
the section that contains this `self`. A special case are sections of
type `CssSectionType::Document`. Their parent will either be `None`
if they are the original CSS document that was loaded by
`CssProviderExt::load_from_file` or a section of type
`CssSectionType::Import` if it was loaded with an import rule from
a different file.

# Returns

the parent section or `None` if none
<!-- impl CssSection::fn get_section_type -->
Gets the type of information that `self` describes.

# Returns

the type of `self`
<!-- impl CssSection::fn get_start_line -->
Returns the line in the CSS document where this section starts.
The line number is 0-indexed, so the first line of the document
will return 0.

# Returns

the line number
<!-- impl CssSection::fn get_start_position -->
Returns the offset in bytes from the start of the current line
returned via `CssSection::get_start_line`.

# Returns

the offset in bytes from the start of the line.
<!-- impl CssSection::fn ref -->
Increments the reference count on `self`.

# Returns

`self` itself.
<!-- impl CssSection::fn unref -->
Decrements the reference count on `self`, freeing the
structure if the reference count reaches 0.
<!-- enum CssSectionType -->
The different types of sections indicate parts of a CSS document as
parsed by GTK’s CSS parser. They are oriented towards the
[CSS Grammar](http://www.w3.org/TR/CSS21/grammar.html),
but may contain extensions.

More types might be added in the future as the parser incorporates
more features.
<!-- enum CssSectionType::variant Document -->
The section describes a complete document.
 This section time is the only one where `CssSection::get_parent`
 might return `None`.
<!-- enum CssSectionType::variant Import -->
The section defines an import rule.
<!-- enum CssSectionType::variant ColorDefinition -->
The section defines a color. This
 is a GTK extension to CSS.
<!-- enum CssSectionType::variant BindingSet -->
The section defines a binding set. This
 is a GTK extension to CSS.
<!-- enum CssSectionType::variant Ruleset -->
The section defines a CSS ruleset.
<!-- enum CssSectionType::variant Selector -->
The section defines a CSS selector.
<!-- enum CssSectionType::variant Declaration -->
The section defines the declaration of
 a CSS variable.
<!-- enum CssSectionType::variant Value -->
The section defines the value of a CSS declaration.
<!-- enum CssSectionType::variant Keyframes -->
The section defines keyframes. See [CSS
 Animations](http://dev.w3.org/csswg/css3-animations/`keyframes`) for details. Since 3.6
<!-- enum DeleteType -->
See also: `Entry::delete-from-cursor`.
<!-- enum DeleteType::variant Chars -->
Delete characters.
<!-- enum DeleteType::variant WordEnds -->
Delete only the portion of the word to the
 left/right of cursor if we’re in the middle of a word.
<!-- enum DeleteType::variant Words -->
Delete words.
<!-- enum DeleteType::variant DisplayLines -->
Delete display-lines. Display-lines
 refers to the visible lines, with respect to to the current line
 breaks. As opposed to paragraphs, which are defined by line
 breaks in the input.
<!-- enum DeleteType::variant DisplayLineEnds -->
Delete only the portion of the
 display-line to the left/right of cursor.
<!-- enum DeleteType::variant ParagraphEnds -->
Delete to the end of the
 paragraph. Like C-k in Emacs (or its reverse).
<!-- enum DeleteType::variant Paragraphs -->
Delete entire line. Like C-k in pico.
<!-- enum DeleteType::variant Whitespace -->
Delete only whitespace. Like M-\ in Emacs.
<!-- struct DestDefaults -->
The `DestDefaults` enumeration specifies the various
types of action that will be taken on behalf
of the user for a drag destination site.
<!-- struct DestDefaults::const MOTION -->
If set for a widget, GTK+, during a drag over this
 widget will check if the drag matches this widget’s list of possible targets
 and actions.
 GTK+ will then call `gdk_drag_status` as appropriate.
<!-- struct DestDefaults::const HIGHLIGHT -->
If set for a widget, GTK+ will draw a highlight on
 this widget as long as a drag is over this widget and the widget drag format
 and action are acceptable.
<!-- struct DestDefaults::const DROP -->
If set for a widget, when a drop occurs, GTK+ will
 will check if the drag matches this widget’s list of possible targets and
 actions. If so, GTK+ will call `WidgetExt::drag_get_data` on behalf of the widget.
 Whether or not the drop is successful, GTK+ will call `gtk_drag_finish`. If
 the action was a move, then if the drag was successful, then `true` will be
 passed for the `delete` parameter to `gtk_drag_finish`.
<!-- struct DestDefaults::const ALL -->
If set, specifies that all default actions should
 be taken.
<!-- struct Dialog -->
Dialog boxes are a convenient way to prompt the user for a small amount
of input, e.g. to display a message, ask a question, or anything else
that does not require extensive effort on the user’s part.

GTK+ treats a dialog as a window split vertically. The top section is a
`VBox`, and is where widgets such as a `Label` or a `Entry` should
be packed. The bottom area is known as the
“action area”. This is generally used for
packing buttons into the dialog which may perform functions such as
cancel, ok, or apply.

`Dialog` boxes are created with a call to `Dialog::new` or
`Dialog::new_with_buttons`. `Dialog::new_with_buttons` is
recommended; it allows you to set the dialog title, some convenient
flags, and add simple buttons.

If “dialog” is a newly created dialog, the two primary areas of the
window can be accessed through `DialogExt::get_content_area` and
`Dialog::get_action_area`, as can be seen from the example below.

A “modal” dialog (that is, one which freezes the rest of the application
from user input), can be created by calling `GtkWindowExt::set_modal` on the
dialog. Use the GTK_WINDOW() macro to cast the widget returned from
`Dialog::new` into a `Window`. When using `Dialog::new_with_buttons`
you can also pass the `DialogFlags::Modal` flag to make a dialog modal.

If you add buttons to `Dialog` using `Dialog::new_with_buttons`,
`DialogExt::add_button`, `DialogExt::add_buttons`, or
`DialogExt::add_action_widget`, clicking the button will emit a signal
called `Dialog::response` with a response ID that you specified. GTK+
will never assign a meaning to positive response IDs; these are entirely
user-defined. But for convenience, you can use the response IDs in the
`ResponseType` enumeration (these all have values less than zero). If
a dialog receives a delete event, the `Dialog::response` signal will
be emitted with a response ID of `ResponseType::DeleteEvent`.

If you want to block waiting for a dialog to return before returning
control flow to your code, you can call `DialogExt::run`. This function
enters a recursive main loop and waits for the user to respond to the
dialog, returning the response ID corresponding to the button the user
clicked.

For the simple dialog in the following example, in reality you’d probably
use `MessageDialog` to save yourself some effort. But you’d need to
create the dialog contents manually if you had more than a simple message
in the dialog.

An example for simple `Dialog` usage:

```C
// Function to open a dialog box with a message
void
quick_message (GtkWindow *parent, gchar *message)
{
 GtkWidget *dialog, *label, *content_area;
 GtkDialogFlags flags;

 // Create the widgets
 flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_dialog_new_with_buttons ("Message",
                                       parent,
                                       flags,
                                       _("_OK"),
                                       GTK_RESPONSE_NONE,
                                       NULL);
 content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
 label = gtk_label_new (message);

 // Ensure that the dialog box is destroyed when the user responds

 g_signal_connect_swapped (dialog,
                           "response",
                           G_CALLBACK (gtk_widget_destroy),
                           dialog);

 // Add the label, and show everything we’ve added

 gtk_container_add (GTK_CONTAINER (content_area), label);
 gtk_widget_show_all (dialog);
}
```

# `Dialog` as `Buildable`

The `Dialog` implementation of the `Buildable` interface exposes the
`vbox` and `action_area` as internal children with the names “vbox” and
“action_area”.

`Dialog` supports a custom `<action-widgets>` element, which can contain
multiple `<action-widget>` elements. The “response” attribute specifies a
numeric response, and the content of the element is the id of widget
(which should be a child of the dialogs `action_area`). To mark a response
as default, set the “default“ attribute of the `<action-widget>` element
to true.

`Dialog` supports adding action widgets by specifying “action“ as
the “type“ attribute of a `<child>` element. The widget will be added
either to the action area or the headerbar of the dialog, depending
on the “use-header-bar“ property. The response id has to be associated
with the action widget using the `<action-widgets>` element.

An example of a `Dialog` UI definition fragment:

```text
<object class="GtkDialog" id="dialog1">
  <child type="action">
    <object class="GtkButton" id="button_cancel"/>
  </child>
  <child type="action">
    <object class="GtkButton" id="button_ok">
      <property name="can-default">True</property>
    </object>
  </child>
  <action-widgets>
    <action-widget response="cancel">button_cancel</action-widget>
    <action-widget response="ok" default="true">button_ok</action-widget>
  </action-widgets>
</object>
```

# Implements

[`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait DialogExt -->
Trait containing all `Dialog` methods.

# Implementors

[`AboutDialog`](struct.AboutDialog.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`ColorChooserDialog`](struct.ColorChooserDialog.html), [`Dialog`](struct.Dialog.html), [`FileChooserDialog`](struct.FileChooserDialog.html), [`FontChooserDialog`](struct.FontChooserDialog.html), [`MessageDialog`](struct.MessageDialog.html), [`RecentChooserDialog`](struct.RecentChooserDialog.html)
<!-- impl Dialog::fn new -->
Creates a new dialog box.

Widgets should not be packed into this `Window`
directly, but into the `vbox` and `action_area`, as described above.

# Returns

the new dialog as a `Widget`
<!-- impl Dialog::fn new_with_buttons -->
Creates a new `Dialog` with title `title` (or `None` for the default
title; see `GtkWindowExt::set_title`) and transient parent `parent` (or
`None` for none; see `GtkWindowExt::set_transient_for`). The `flags`
argument can be used to make the dialog modal (`DialogFlags::Modal`)
and/or to have it destroyed along with its transient parent
(`DialogFlags::DestroyWithParent`). After `flags`, button
text/response ID pairs should be listed, with a `None` pointer ending
the list. Button text can be arbitrary text. A response ID can be
any positive number, or one of the values in the `ResponseType`
enumeration. If the user clicks one of these dialog buttons,
`Dialog` will emit the `Dialog::response` signal with the corresponding
response ID. If a `Dialog` receives the `Widget::delete-event` signal,
it will emit ::response with a response ID of `ResponseType::DeleteEvent`.
However, destroying a dialog does not emit the ::response signal;
so be careful relying on ::response when using the
`DialogFlags::DestroyWithParent` flag. Buttons are from left to right,
so the first button in the list will be the leftmost button in the dialog.

Here’s a simple example:

```C
 GtkWidget *main_app_window; // Window the dialog should show up on
 GtkWidget *dialog;
 GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_dialog_new_with_buttons ("My dialog",
                                       main_app_window,
                                       flags,
                                       _("_OK"),
                                       GTK_RESPONSE_ACCEPT,
                                       _("_Cancel"),
                                       GTK_RESPONSE_REJECT,
                                       NULL);
```
## `title`
Title of the dialog, or `None`
## `parent`
Transient parent of the dialog, or `None`
## `flags`
from `DialogFlags`
## `first_button_text`
text to go in first button, or `None`

# Returns

a new `Dialog`
<!-- trait DialogExt::fn add_action_widget -->
Adds an activatable widget to the action area of a `Dialog`,
connecting a signal handler that will emit the `Dialog::response`
signal on the dialog when the widget is activated. The widget is
appended to the end of the dialog’s action area. If you want to add a
non-activatable widget, simply pack it into the `action_area` field
of the `Dialog` struct.
## `child`
an activatable widget
## `response_id`
response ID for `child`
<!-- trait DialogExt::fn add_button -->
Adds a button with the given text and sets things up so that
clicking the button will emit the `Dialog::response` signal with
the given `response_id`. The button is appended to the end of the
dialog’s action area. The button widget is returned, but usually
you don’t need it.
## `button_text`
text of button
## `response_id`
response ID for the button

# Returns

the `Button` widget that was added
<!-- trait DialogExt::fn add_buttons -->
Adds more buttons, same as calling `DialogExt::add_button`
repeatedly. The variable argument list should be `None`-terminated
as with `Dialog::new_with_buttons`. Each button must have both
text and response ID.
## `first_button_text`
button text
<!-- trait DialogExt::fn get_content_area -->
Returns the content area of `self`.

# Returns

the content area `Box`.
<!-- trait DialogExt::fn get_header_bar -->
Returns the header bar of `self`. Note that the
headerbar is only used by the dialog if the
`Dialog:use-header-bar` property is `true`.

# Returns

the header bar
<!-- trait DialogExt::fn get_response_for_widget -->
Gets the response id of a widget in the action area
of a dialog.
## `widget`
a widget in the action area of `self`

# Returns

the response id of `widget`, or `ResponseType::None`
 if `widget` doesn’t have a response id set.
<!-- trait DialogExt::fn get_widget_for_response -->
Gets the widget button that uses the given response ID in the action area
of a dialog.
## `response_id`
the response ID used by the `self` widget

# Returns

the `widget` button that uses the given
 `response_id`, or `None`.
<!-- trait DialogExt::fn response -->
Emits the `Dialog::response` signal with the given response ID.
Used to indicate that the user has responded to the dialog in some way;
typically either you or `DialogExt::run` will be monitoring the
::response signal and take appropriate action.
## `response_id`
response ID
<!-- trait DialogExt::fn run -->
Blocks in a recursive main loop until the `self` either emits the
`Dialog::response` signal, or is destroyed. If the dialog is
destroyed during the call to `DialogExt::run`, `DialogExt::run` returns
`ResponseType::None`. Otherwise, it returns the response ID from the
::response signal emission.

Before entering the recursive main loop, `DialogExt::run` calls
`WidgetExt::show` on the dialog for you. Note that you still
need to show any children of the dialog yourself.

During `DialogExt::run`, the default behavior of `Widget::delete-event`
is disabled; if the dialog receives ::delete_event, it will not be
destroyed as windows usually are, and `DialogExt::run` will return
`ResponseType::DeleteEvent`. Also, during `DialogExt::run` the dialog
will be modal. You can force `DialogExt::run` to return at any time by
calling `DialogExt::response` to emit the ::response signal. Destroying
the dialog during `DialogExt::run` is a very bad idea, because your
post-run code won’t know whether the dialog was destroyed or not.

After `DialogExt::run` returns, you are responsible for hiding or
destroying the dialog if you wish to do so.

Typical usage of this function might be:

```C
  GtkWidget *dialog = gtk_dialog_new ();
  // Set up dialog...

  int result = gtk_dialog_run (GTK_DIALOG (dialog));
  switch (result)
    {
      case GTK_RESPONSE_ACCEPT:
         // do_application_specific_something ();
         break;
      default:
         // do_nothing_since_dialog_was_cancelled ();
         break;
    }
  gtk_widget_destroy (dialog);
```

Note that even though the recursive main loop gives the effect of a
modal dialog (it prevents the user from interacting with other
windows in the same window group while the dialog is run), callbacks
such as timeouts, IO channel watches, DND drops, etc, will
be triggered during a `DialogExt::run` call.

# Returns

response ID
<!-- trait DialogExt::fn set_default_response -->
Sets the last widget in the dialog’s action area with the given `response_id`
as the default widget for the dialog. Pressing “Enter” normally activates
the default widget.
## `response_id`
a response ID
<!-- trait DialogExt::fn set_response_sensitive -->
Calls `gtk_widget_set_sensitive (widget, @setting)`
for each widget in the dialog’s action area with the given `response_id`.
A convenient way to sensitize/desensitize dialog buttons.
## `response_id`
a response ID
## `setting`
`true` for sensitive
<!-- trait DialogExt::fn connect_close -->
The ::close signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user uses a keybinding to close
the dialog.

The default binding for this signal is the Escape key.
<!-- trait DialogExt::fn connect_response -->
Emitted when an action widget is clicked, the dialog receives a
delete event, or the application programmer calls `DialogExt::response`.
On a delete event, the response ID is `ResponseType::DeleteEvent`.
Otherwise, it depends on which action widget was clicked.
## `response_id`
the response ID
<!-- trait DialogExt::fn get_property_use_header_bar -->
`true` if the dialog uses a `HeaderBar` for action buttons
instead of the action-area.

For technical reasons, this property is declared as an integer
property, but you should only set it to `true` or `false`.
<!-- trait DialogExt::fn set_property_use_header_bar -->
`true` if the dialog uses a `HeaderBar` for action buttons
instead of the action-area.

For technical reasons, this property is declared as an integer
property, but you should only set it to `true` or `false`.
<!-- struct DialogFlags -->
Flags used to influence dialog construction.
<!-- struct DialogFlags::const MODAL -->
Make the constructed dialog modal,
 see `GtkWindowExt::set_modal`
<!-- struct DialogFlags::const DESTROY_WITH_PARENT -->
Destroy the dialog when its
 parent is destroyed, see `GtkWindowExt::set_destroy_with_parent`
<!-- struct DialogFlags::const USE_HEADER_BAR -->
Create dialog with actions in header
 bar instead of action area. Since 3.12.
<!-- enum DirectionType -->
Focus movement types.
<!-- enum DirectionType::variant TabForward -->
Move forward.
<!-- enum DirectionType::variant TabBackward -->
Move backward.
<!-- enum DirectionType::variant Up -->
Move up.
<!-- enum DirectionType::variant Down -->
Move down.
<!-- enum DirectionType::variant Left -->
Move left.
<!-- enum DirectionType::variant Right -->
Move right.
<!-- enum DragResult -->
Gives an indication why a drag operation failed.
The value can by obtained by connecting to the
`Widget::drag-failed` signal.
<!-- enum DragResult::variant Success -->
The drag operation was successful.
<!-- enum DragResult::variant NoTarget -->
No suitable drag target.
<!-- enum DragResult::variant UserCancelled -->
The user cancelled the drag operation.
<!-- enum DragResult::variant TimeoutExpired -->
The drag operation timed out.
<!-- enum DragResult::variant GrabBroken -->
The pointer or keyboard grab used
 for the drag operation was broken.
<!-- enum DragResult::variant Error -->
The drag operation failed due to some
 unspecified error.
<!-- struct DrawingArea -->
The `DrawingArea` widget is used for creating custom user interface
elements. It’s essentially a blank widget; you can draw on it. After
creating a drawing area, the application may want to connect to:

- Mouse and button press signals to respond to input from
 the user. (Use `Widget::add_events` to enable events
 you wish to receive.)

- The `Widget::realize` signal to take any necessary actions
 when the widget is instantiated on a particular display.
 (Create GDK resources in response to this signal.)

- The `Widget::size-allocate` signal to take any necessary
 actions when the widget changes size.

- The `Widget::draw` signal to handle redrawing the
 contents of the widget.

The following code portion demonstrates using a drawing
area to display a circle in the normal widget foreground
color.

Note that GDK automatically clears the exposed area before sending
the expose event, and that drawing is implicitly clipped to the exposed
area. If you want to have a theme-provided background, you need
to call `gtk_render_background` in your ::draw method.

## Simple `DrawingArea` usage


```C
gboolean
draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data)
{
  guint width, height;
  GdkRGBA color;
  GtkStyleContext *context;

  context = gtk_widget_get_style_context (widget);

  width = gtk_widget_get_allocated_width (widget);
  height = gtk_widget_get_allocated_height (widget);

  gtk_render_background (context, cr, 0, 0, width, height);

  cairo_arc (cr,
             width / 2.0, height / 2.0,
             MIN (width, height) / 2.0,
             0, 2 * G_PI);

  gtk_style_context_get_color (context,
                               gtk_style_context_get_state (context),
                               &color);
  gdk_cairo_set_source_rgba (cr, &color);

  cairo_fill (cr);

 return FALSE;
}
[...]
  GtkWidget *drawing_area = gtk_drawing_area_new ();
  gtk_widget_set_size_request (drawing_area, 100, 100);
  g_signal_connect (G_OBJECT (drawing_area), "draw",
                    G_CALLBACK (draw_callback), NULL);
```

Draw signals are normally delivered when a drawing area first comes
onscreen, or when it’s covered by another window and then uncovered.
You can also force an expose event by adding to the “damage region”
of the drawing area’s window; `WidgetExt::queue_draw_area` and
`gdk::WindowExt::invalidate_rect` are equally good ways to do this.
You’ll then get a draw signal for the invalid region.

The available routines for drawing are documented on the
[GDK Drawing Primitives][gdk3-Cairo-Interaction] page
and the cairo documentation.

To receive mouse events on a drawing area, you will need to enable
them with `Widget::add_events`. To receive keyboard events, you
will need to set the “can-focus” property on the drawing area, and you
should probably draw some user-visible indication that the drawing
area is focused. Use `WidgetExt::has_focus` in your expose event
handler to decide whether to draw the focus indicator. See
`gtk_render_focus` for one way to draw focus.

# Implements

[`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl DrawingArea::fn new -->
Creates a new drawing area.

# Returns

a new `DrawingArea`
<!-- struct Editable -->
The `Editable` interface is an interface which should be implemented by
text editing widgets, such as `Entry` and `SpinButton`. It contains functions
for generically manipulating an editable widget, a large number of action
signals used for key bindings, and several signals that an application can
connect to to modify the behavior of a widget.

As an example of the latter usage, by connecting
the following handler to `Editable::insert-text`, an application
can convert all entry into a widget into uppercase.

## Forcing entry to uppercase.


```C
#include <ctype.h>;

void
insert_text_handler (GtkEditable *editable,
                     const gchar *text,
                     gint         length,
                     gint        *position,
                     gpointer     data)
{
  gchar *result = g_utf8_strup (text, length);

  g_signal_handlers_block_by_func (editable,
                               (gpointer) insert_text_handler, data);
  gtk_editable_insert_text (editable, result, length, position);
  g_signal_handlers_unblock_by_func (editable,
                                     (gpointer) insert_text_handler, data);

  g_signal_stop_emission_by_name (editable, "insert_text");

  g_free (result);
}
```

# Implements

[`EditableExt`](trait.EditableExt.html), [`EditableSignals`](prelude/trait.EditableSignals.html)
<!-- trait EditableExt -->
Trait containing all `Editable` methods.

# Implementors

[`Editable`](struct.Editable.html), [`Entry`](struct.Entry.html), [`SearchEntry`](struct.SearchEntry.html), [`SpinButton`](struct.SpinButton.html)
<!-- trait EditableExt::fn copy_clipboard -->
Copies the contents of the currently selected content in the editable and
puts it on the clipboard.
<!-- trait EditableExt::fn cut_clipboard -->
Removes the contents of the currently selected content in the editable and
puts it on the clipboard.
<!-- trait EditableExt::fn delete_selection -->
Deletes the currently selected text of the editable.
This call doesn’t do anything if there is no selected text.
<!-- trait EditableExt::fn delete_text -->
Deletes a sequence of characters. The characters that are deleted are
those characters at positions from `start_pos` up to, but not including
`end_pos`. If `end_pos` is negative, then the characters deleted
are those from `start_pos` to the end of the text.

Note that the positions are specified in characters, not bytes.
## `start_pos`
start position
## `end_pos`
end position
<!-- trait EditableExt::fn get_chars -->
Retrieves a sequence of characters. The characters that are retrieved
are those characters at positions from `start_pos` up to, but not
including `end_pos`. If `end_pos` is negative, then the characters
retrieved are those characters from `start_pos` to the end of the text.

Note that positions are specified in characters, not bytes.
## `start_pos`
start of text
## `end_pos`
end of text

# Returns

a pointer to the contents of the widget as a
 string. This string is allocated by the `Editable`
 implementation and should be freed by the caller.
<!-- trait EditableExt::fn get_editable -->
Retrieves whether `self` is editable. See
`Editable::set_editable`.

# Returns

`true` if `self` is editable.
<!-- trait EditableExt::fn get_position -->
Retrieves the current position of the cursor relative to the start
of the content of the editable.

Note that this position is in characters, not in bytes.

# Returns

the cursor position
<!-- trait EditableExt::fn get_selection_bounds -->
Retrieves the selection bound of the editable. start_pos will be filled
with the start of the selection and `end_pos` with end. If no text was
selected both will be identical and `false` will be returned.

Note that positions are specified in characters, not bytes.
## `start_pos`
location to store the starting position, or `None`
## `end_pos`
location to store the end position, or `None`

# Returns

`true` if an area is selected, `false` otherwise
<!-- trait EditableExt::fn insert_text -->
Inserts `new_text_length` bytes of `new_text` into the contents of the
widget, at position `position`.

Note that the position is in characters, not in bytes.
The function updates `position` to point after the newly inserted text.
## `new_text`
the text to append
## `new_text_length`
the length of the text in bytes, or -1
## `position`
location of the position text will be inserted at
<!-- trait EditableExt::fn paste_clipboard -->
Pastes the content of the clipboard to the current position of the
cursor in the editable.
<!-- trait EditableExt::fn select_region -->
Selects a region of text. The characters that are selected are
those characters at positions from `start_pos` up to, but not
including `end_pos`. If `end_pos` is negative, then the
characters selected are those characters from `start_pos` to
the end of the text.

Note that positions are specified in characters, not bytes.
## `start_pos`
start of region
## `end_pos`
end of region
<!-- trait EditableExt::fn set_editable -->
Determines if the user can edit the text in the editable
widget or not.
## `is_editable`
`true` if the user is allowed to edit the text
 in the widget
<!-- trait EditableExt::fn set_position -->
Sets the cursor position in the editable to the given value.

The cursor is displayed before the character with the given (base 0)
index in the contents of the editable. The value must be less than or
equal to the number of characters in the editable. A value of -1
indicates that the position should be set after the last character
of the editable. Note that `position` is in characters, not in bytes.
## `position`
the position of the cursor
<!-- trait EditableSignals::fn connect_changed -->
The ::changed signal is emitted at the end of a single
user-visible operation on the contents of the `Editable`.

E.g., a paste operation that replaces the contents of the
selection will cause only one signal emission (even though it
is implemented by first deleting the selection, then inserting
the new content, and may cause multiple ::notify::text signals
to be emitted).
<!-- trait EditableSignals::fn connect_delete_text -->
This signal is emitted when text is deleted from
the widget by the user. The default handler for
this signal will normally be responsible for deleting
the text, so by connecting to this signal and then
stopping the signal with `g_signal_stop_emission`, it
is possible to modify the range of deleted text, or
prevent it from being deleted entirely. The `start_pos`
and `end_pos` parameters are interpreted as for
`Editable::delete_text`.
## `start_pos`
the starting position
## `end_pos`
the end position
<!-- trait EditableSignals::fn connect_insert_text -->
This signal is emitted when text is inserted into
the widget by the user. The default handler for
this signal will normally be responsible for inserting
the text, so by connecting to this signal and then
stopping the signal with `g_signal_stop_emission`, it
is possible to modify the inserted text, or prevent
it from being inserted entirely.
## `new_text`
the new text to insert
## `new_text_length`
the length of the new text, in bytes,
 or -1 if new_text is nul-terminated
## `position`
the position, in characters,
 at which to insert the new text. this is an in-out
 parameter. After the signal emission is finished, it
 should point after the newly inserted text.
<!-- struct Entry -->
The `Entry` widget is a single line text entry
widget. A fairly large set of key bindings are supported
by default. If the entered text is longer than the allocation
of the widget, the widget will scroll so that the cursor
position is visible.

When using an entry for passwords and other sensitive information,
it can be put into “password mode” using `EntryExt::set_visibility`.
In this mode, entered text is displayed using a “invisible” character.
By default, GTK+ picks the best invisible character that is available
in the current font, but it can be changed with
`EntryExt::set_invisible_char`. Since 2.16, GTK+ displays a warning
when Caps Lock or input methods might interfere with entering text in
a password entry. The warning can be turned off with the
`Entry:caps-lock-warning` property.

Since 2.16, `Entry` has the ability to display progress or activity
information behind the text. To make an entry display such information,
use `EntryExt::set_progress_fraction` or `EntryExt::set_progress_pulse_step`.

Additionally, `Entry` can show icons at either side of the entry. These
icons can be activatable by clicking, can be set up as drag source and
can have tooltips. To add an icon, use `EntryExt::set_icon_from_gicon` or
one of the various other functions that set an icon from a stock id, an
icon name or a pixbuf. To trigger an action when the user clicks an icon,
connect to the `Entry::icon-press` signal. To allow DND operations
from an icon, use `EntryExt::set_icon_drag_source`. To set a tooltip on
an icon, use `EntryExt::set_icon_tooltip_text` or the corresponding function
for markup.

Note that functionality or information that is only available by clicking
on an icon in an entry may not be accessible at all to users which are not
able to use a mouse or other pointing device. It is therefore recommended
that any such functionality should also be available by other means, e.g.
via the context menu of the entry.

# CSS nodes


```plain
entry[.read-only][.flat][.warning][.error]
├── image.left
├── image.right
├── undershoot.left
├── undershoot.right
├── [selection]
├── [progress[.pulse]]
╰── [window.popup]
```

`Entry` has a main node with the name entry. Depending on the properties
of the entry, the style classes .read-only and .flat may appear. The style
classes .warning and .error may also be used with entries.

When the entry shows icons, it adds subnodes with the name image and the
style class .left or .right, depending on where the icon appears.

When the entry has a selection, it adds a subnode with the name selection.

When the entry shows progress, it adds a subnode with the name progress.
The node has the style class .pulse when the shown progress is pulsing.

The CSS node for a context menu is added as a subnode below entry as well.

The undershoot nodes are used to draw the underflow indication when content
is scrolled out of view. These nodes get the .left and .right style classes
added depending on where the indication is drawn.

When touch is used and touch selection handles are shown, they are using
CSS nodes with name cursor-handle. They get the .top or .bottom style class
depending on where they are shown in relation to the selection. If there is
just a single handle for the text cursor, it gets the style class
.insertion-cursor.

# Implements

[`EntryExt`](trait.EntryExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`EditableExt`](trait.EditableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`EditableSignals`](prelude/trait.EditableSignals.html)
<!-- trait EntryExt -->
Trait containing all `Entry` methods.

# Implementors

[`Entry`](struct.Entry.html), [`SearchEntry`](struct.SearchEntry.html), [`SpinButton`](struct.SpinButton.html)
<!-- impl Entry::fn new -->
Creates a new entry.

# Returns

a new `Entry`.
<!-- impl Entry::fn new_with_buffer -->
Creates a new entry with the specified text buffer.
## `buffer`
The buffer to use for the new `Entry`.

# Returns

a new `Entry`
<!-- trait EntryExt::fn get_activates_default -->
Retrieves the value set by `EntryExt::set_activates_default`.

# Returns

`true` if the entry will activate the default widget
<!-- trait EntryExt::fn get_alignment -->
Gets the value set by `EntryExt::set_alignment`.

# Returns

the alignment
<!-- trait EntryExt::fn get_attributes -->
Gets the attribute list that was set on the entry using
`EntryExt::set_attributes`, if any.

# Returns

the attribute list, or `None`
 if none was set.
<!-- trait EntryExt::fn get_buffer -->
Get the `EntryBuffer` object which holds the text for
this widget.

# Returns

A `EntryBuffer` object.
<!-- trait EntryExt::fn get_completion -->
Returns the auxiliary completion object currently in use by `self`.

# Returns

The auxiliary completion object currently
 in use by `self`.
<!-- trait EntryExt::fn get_current_icon_drag_source -->
Returns the index of the icon which is the source of the current
DND operation, or -1.

This function is meant to be used in a `Widget::drag-data-get`
callback.

# Returns

index of the icon which is the source of the current
 DND operation, or -1.
<!-- trait EntryExt::fn get_cursor_hadjustment -->
Retrieves the horizontal cursor adjustment for the entry.
See `EntryExt::set_cursor_hadjustment`.

# Returns

the horizontal cursor adjustment, or `None`
 if none has been set.
<!-- trait EntryExt::fn get_has_frame -->
Gets the value set by `EntryExt::set_has_frame`.

# Returns

whether the entry has a beveled frame
<!-- trait EntryExt::fn get_icon_activatable -->
Returns whether the icon is activatable.
## `icon_pos`
Icon position

# Returns

`true` if the icon is activatable.
<!-- trait EntryExt::fn get_icon_area -->
Gets the area where entry’s icon at `icon_pos` is drawn.
This function is useful when drawing something to the
entry in a draw callback.

If the entry is not realized or has no icon at the given position,
`icon_area` is filled with zeros. Otherwise, `icon_area` will be filled
with the icon’s allocation, relative to `self`’s allocation.

See also `EntryExt::get_text_area`
## `icon_pos`
Icon position
## `icon_area`
Return location for the icon’s area
<!-- trait EntryExt::fn get_icon_at_pos -->
Finds the icon at the given position and return its index. The
position’s coordinates are relative to the `self`’s top left corner.
If `x`, `y` doesn’t lie inside an icon, -1 is returned.
This function is intended for use in a `Widget::query-tooltip`
signal handler.
## `x`
the x coordinate of the position to find
## `y`
the y coordinate of the position to find

# Returns

the index of the icon at the given position, or -1
<!-- trait EntryExt::fn get_icon_gicon -->
Retrieves the `gio::Icon` used for the icon, or `None` if there is
no icon or if the icon was set by some other method (e.g., by
stock, pixbuf, or icon name).
## `icon_pos`
Icon position

# Returns

A `gio::Icon`, or `None` if no icon is set
 or if the icon is not a `gio::Icon`
<!-- trait EntryExt::fn get_icon_name -->
Retrieves the icon name used for the icon, or `None` if there is
no icon or if the icon was set by some other method (e.g., by
pixbuf, stock or gicon).
## `icon_pos`
Icon position

# Returns

An icon name, or `None` if no icon is set or if the icon
 wasn’t set from an icon name
<!-- trait EntryExt::fn get_icon_pixbuf -->
Retrieves the image used for the icon.

Unlike the other methods of setting and getting icon data, this
method will work regardless of whether the icon was set using a
`gdk_pixbuf::Pixbuf`, a `gio::Icon`, a stock item, or an icon name.
## `icon_pos`
Icon position

# Returns

A `gdk_pixbuf::Pixbuf`, or `None` if no icon is
 set for this position.
<!-- trait EntryExt::fn get_icon_sensitive -->
Returns whether the icon appears sensitive or insensitive.
## `icon_pos`
Icon position

# Returns

`true` if the icon is sensitive.
<!-- trait EntryExt::fn get_icon_storage_type -->
Gets the type of representation being used by the icon
to store image data. If the icon has no image data,
the return value will be `ImageType::Empty`.
## `icon_pos`
Icon position

# Returns

image representation being used
<!-- trait EntryExt::fn get_icon_tooltip_markup -->
Gets the contents of the tooltip on the icon at the specified
position in `self`.
## `icon_pos`
the icon position

# Returns

the tooltip text, or `None`. Free the returned
 string with `g_free` when done.
<!-- trait EntryExt::fn get_icon_tooltip_text -->
Gets the contents of the tooltip on the icon at the specified
position in `self`.
## `icon_pos`
the icon position

# Returns

the tooltip text, or `None`. Free the returned
 string with `g_free` when done.
<!-- trait EntryExt::fn get_input_hints -->
Gets the value of the `Entry:input-hints` property.
<!-- trait EntryExt::fn get_input_purpose -->
Gets the value of the `Entry:input-purpose` property.
<!-- trait EntryExt::fn get_invisible_char -->
Retrieves the character displayed in place of the real characters
for entries with visibility set to false. See `EntryExt::set_invisible_char`.

# Returns

the current invisible char, or 0, if the entry does not
 show invisible text at all.
<!-- trait EntryExt::fn get_layout -->
Gets the `pango::Layout` used to display the entry.
The layout is useful to e.g. convert text positions to
pixel positions, in combination with `EntryExt::get_layout_offsets`.
The returned layout is owned by the entry and must not be
modified or freed by the caller.

Keep in mind that the layout text may contain a preedit string, so
`EntryExt::layout_index_to_text_index` and
`EntryExt::text_index_to_layout_index` are needed to convert byte
indices in the layout to byte indices in the entry contents.

# Returns

the `pango::Layout` for this entry
<!-- trait EntryExt::fn get_layout_offsets -->
Obtains the position of the `pango::Layout` used to render text
in the entry, in widget coordinates. Useful if you want to line
up the text in an entry with some other text, e.g. when using the
entry to implement editable cells in a sheet widget.

Also useful to convert mouse events into coordinates inside the
`pango::Layout`, e.g. to take some action if some part of the entry text
is clicked.

Note that as the user scrolls around in the entry the offsets will
change; you’ll need to connect to the “notify::scroll-offset”
signal to track this. Remember when using the `pango::Layout`
functions you need to convert to and from pixels using
PANGO_PIXELS() or `PANGO_SCALE`.

Keep in mind that the layout text may contain a preedit string, so
`EntryExt::layout_index_to_text_index` and
`EntryExt::text_index_to_layout_index` are needed to convert byte
indices in the layout to byte indices in the entry contents.
## `x`
location to store X offset of layout, or `None`
## `y`
location to store Y offset of layout, or `None`
<!-- trait EntryExt::fn get_max_length -->
Retrieves the maximum allowed length of the text in
`self`. See `EntryExt::set_max_length`.

This is equivalent to getting `self`'s `EntryBuffer` and
calling `EntryBufferExt::get_max_length` on it.

# Returns

the maximum allowed number of characters
 in `Entry`, or 0 if there is no maximum.
<!-- trait EntryExt::fn get_max_width_chars -->
Retrieves the desired maximum width of `self`, in characters.
See `EntryExt::set_max_width_chars`.

# Returns

the maximum width of the entry, in characters
<!-- trait EntryExt::fn get_overwrite_mode -->
Gets the value set by `EntryExt::set_overwrite_mode`.

# Returns

whether the text is overwritten when typing.
<!-- trait EntryExt::fn get_placeholder_text -->
Retrieves the text that will be displayed when `self` is empty and unfocused

# Returns

a pointer to the placeholder text as a string. This string points to internally allocated
storage in the widget and must not be freed, modified or stored.
<!-- trait EntryExt::fn get_progress_fraction -->
Returns the current fraction of the task that’s been completed.
See `EntryExt::set_progress_fraction`.

# Returns

a fraction from 0.0 to 1.0
<!-- trait EntryExt::fn get_progress_pulse_step -->
Retrieves the pulse step set with `EntryExt::set_progress_pulse_step`.

# Returns

a fraction from 0.0 to 1.0
<!-- trait EntryExt::fn get_tabs -->
Gets the tabstops that were set on the entry using `EntryExt::set_tabs`, if
any.

# Returns

the tabstops, or `None` if none was set.
<!-- trait EntryExt::fn get_text -->
Retrieves the contents of the entry widget.
See also `Editable::get_chars`.

This is equivalent to getting `self`'s `EntryBuffer` and calling
`EntryBufferExt::get_text` on it.

# Returns

a pointer to the contents of the widget as a
 string. This string points to internally allocated
 storage in the widget and must not be freed, modified or
 stored.
<!-- trait EntryExt::fn get_text_area -->
Gets the area where the entry’s text is drawn. This function is
useful when drawing something to the entry in a draw callback.

If the entry is not realized, `text_area` is filled with zeros.

See also `EntryExt::get_icon_area`.
## `text_area`
Return location for the text area.
<!-- trait EntryExt::fn get_text_length -->
Retrieves the current length of the text in
`self`.

This is equivalent to getting `self`'s `EntryBuffer` and
calling `EntryBufferExt::get_length` on it.

# Returns

the current number of characters
 in `Entry`, or 0 if there are none.
<!-- trait EntryExt::fn get_visibility -->
Retrieves whether the text in `self` is visible. See
`EntryExt::set_visibility`.

# Returns

`true` if the text is currently visible
<!-- trait EntryExt::fn get_width_chars -->
Gets the value set by `EntryExt::set_width_chars`.

# Returns

number of chars to request space for, or negative if unset
<!-- trait EntryExt::fn grab_focus_without_selecting -->
Causes `self` to have keyboard focus.

It behaves like `WidgetExt::grab_focus`,
except that it doesn't select the contents of the entry.
You only want to call this on some special entries
which the user usually doesn't want to replace all text in,
such as search-as-you-type entries.

Feature: `v3_16`

<!-- trait EntryExt::fn im_context_filter_keypress -->
Allow the `Entry` input method to internally handle key press
and release events. If this function returns `true`, then no further
processing should be done for this key event. See
`IMContextExt::filter_keypress`.

Note that you are expected to call this function from your handler
when overriding key event handling. This is needed in the case when
you need to insert your own key handling between the input method
and the default key event handling of the `Entry`.
See `TextViewExt::reset_im_context` for an example of use.
## `event`
the key event

# Returns

`true` if the input method handled the key event.
<!-- trait EntryExt::fn layout_index_to_text_index -->
Converts from a position in the entry’s `pango::Layout` (returned by
`EntryExt::get_layout`) to a position in the entry contents
(returned by `EntryExt::get_text`).
## `layout_index`
byte index into the entry layout text

# Returns

byte index into the entry contents
<!-- trait EntryExt::fn progress_pulse -->
Indicates that some progress is made, but you don’t know how much.
Causes the entry’s progress indicator to enter “activity mode,”
where a block bounces back and forth. Each call to
`EntryExt::progress_pulse` causes the block to move by a little bit
(the amount of movement per pulse is determined by
`EntryExt::set_progress_pulse_step`).
<!-- trait EntryExt::fn reset_im_context -->
Reset the input method context of the entry if needed.

This can be necessary in the case where modifying the buffer
would confuse on-going input method behavior.
<!-- trait EntryExt::fn set_activates_default -->
If `setting` is `true`, pressing Enter in the `self` will activate the default
widget for the window containing the entry. This usually means that
the dialog box containing the entry will be closed, since the default
widget is usually one of the dialog buttons.

(For experts: if `setting` is `true`, the entry calls
`GtkWindowExt::activate_default` on the window containing the entry, in
the default handler for the `Entry::activate` signal.)
## `setting`
`true` to activate window’s default widget on Enter keypress
<!-- trait EntryExt::fn set_alignment -->
Sets the alignment for the contents of the entry. This controls
the horizontal positioning of the contents when the displayed
text is shorter than the width of the entry.
## `xalign`
The horizontal alignment, from 0 (left) to 1 (right).
 Reversed for RTL layouts
<!-- trait EntryExt::fn set_attributes -->
Sets a `pango::AttrList`; the attributes in the list are applied to the
entry text.
## `attrs`
a `pango::AttrList`
<!-- trait EntryExt::fn set_buffer -->
Set the `EntryBuffer` object which holds the text for
this widget.
## `buffer`
a `EntryBuffer`
<!-- trait EntryExt::fn set_completion -->
Sets `completion` to be the auxiliary completion object to use with `self`.
All further configuration of the completion mechanism is done on
`completion` using the `EntryCompletion` API. Completion is disabled if
`completion` is set to `None`.
## `completion`
The `EntryCompletion` or `None`
<!-- trait EntryExt::fn set_cursor_hadjustment -->
Hooks up an adjustment to the cursor position in an entry, so that when
the cursor is moved, the adjustment is scrolled to show that position.
See `ScrolledWindowExt::get_hadjustment` for a typical way of obtaining
the adjustment.

The adjustment has to be in pixel units and in the same coordinate system
as the entry.
## `adjustment`
an adjustment which should be adjusted when the cursor
 is moved, or `None`
<!-- trait EntryExt::fn set_has_frame -->
Sets whether the entry has a beveled frame around it.
## `setting`
new value
<!-- trait EntryExt::fn set_icon_activatable -->
Sets whether the icon is activatable.
## `icon_pos`
Icon position
## `activatable`
`true` if the icon should be activatable
<!-- trait EntryExt::fn set_icon_drag_source -->
Sets up the icon at the given position so that GTK+ will start a drag
operation when the user clicks and drags the icon.

To handle the drag operation, you need to connect to the usual
`Widget::drag-data-get` (or possibly `Widget::drag-data-delete`)
signal, and use `EntryExt::get_current_icon_drag_source` in
your signal handler to find out if the drag was started from
an icon.

By default, GTK+ uses the icon as the drag icon. You can use the
`Widget::drag-begin` signal to set a different icon. Note that you
have to use `g_signal_connect_after` to ensure that your signal handler
gets executed after the default handler.
## `icon_pos`
icon position
## `target_list`
the targets (data formats) in which the data can be provided
## `actions`
a bitmask of the allowed drag actions
<!-- trait EntryExt::fn set_icon_from_gicon -->
Sets the icon shown in the entry at the specified position
from the current icon theme.
If the icon isn’t known, a “broken image” icon will be displayed
instead.

If `icon` is `None`, no icon will be shown in the specified position.
## `icon_pos`
The position at which to set the icon
## `icon`
The icon to set, or `None`
<!-- trait EntryExt::fn set_icon_from_icon_name -->
Sets the icon shown in the entry at the specified position
from the current icon theme.

If the icon name isn’t known, a “broken image” icon will be displayed
instead.

If `icon_name` is `None`, no icon will be shown in the specified position.
## `icon_pos`
The position at which to set the icon
## `icon_name`
An icon name, or `None`
<!-- trait EntryExt::fn set_icon_from_pixbuf -->
Sets the icon shown in the specified position using a pixbuf.

If `pixbuf` is `None`, no icon will be shown in the specified position.
## `icon_pos`
Icon position
## `pixbuf`
A `gdk_pixbuf::Pixbuf`, or `None`
<!-- trait EntryExt::fn set_icon_sensitive -->
Sets the sensitivity for the specified icon.
## `icon_pos`
Icon position
## `sensitive`
Specifies whether the icon should appear
 sensitive or insensitive
<!-- trait EntryExt::fn set_icon_tooltip_markup -->
Sets `tooltip` as the contents of the tooltip for the icon at
the specified position. `tooltip` is assumed to be marked up with
the [Pango text markup language][PangoMarkupFormat].

Use `None` for `tooltip` to remove an existing tooltip.

See also `WidgetExt::set_tooltip_markup` and
`EntryExt::set_icon_tooltip_text`.
## `icon_pos`
the icon position
## `tooltip`
the contents of the tooltip for the icon, or `None`
<!-- trait EntryExt::fn set_icon_tooltip_text -->
Sets `tooltip` as the contents of the tooltip for the icon
at the specified position.

Use `None` for `tooltip` to remove an existing tooltip.

See also `WidgetExt::set_tooltip_text` and
`EntryExt::set_icon_tooltip_markup`.

If you unset the widget tooltip via `WidgetExt::set_tooltip_text` or
`WidgetExt::set_tooltip_markup`, this sets `Widget`:has-tooltip to `false`,
which suppresses icon tooltips too. You can resolve this by then calling
`WidgetExt::set_has_tooltip` to set `Widget`:has-tooltip back to `true`, or
setting at least one non-empty tooltip on any icon achieves the same result.
## `icon_pos`
the icon position
## `tooltip`
the contents of the tooltip for the icon, or `None`
<!-- trait EntryExt::fn set_input_hints -->
Sets the `Entry:input-hints` property, which
allows input methods to fine-tune their behaviour.
## `hints`
the hints
<!-- trait EntryExt::fn set_input_purpose -->
Sets the `Entry:input-purpose` property which
can be used by on-screen keyboards and other input
methods to adjust their behaviour.
## `purpose`
the purpose
<!-- trait EntryExt::fn set_invisible_char -->
Sets the character to use in place of the actual text when
`EntryExt::set_visibility` has been called to set text visibility
to `false`. i.e. this is the character used in “password mode” to
show the user how many characters have been typed. By default, GTK+
picks the best invisible char available in the current font. If you
set the invisible char to 0, then the user will get no feedback
at all; there will be no text on the screen as they type.
## `ch`
a Unicode character
<!-- trait EntryExt::fn set_max_length -->
Sets the maximum allowed length of the contents of the widget. If
the current contents are longer than the given length, then they
will be truncated to fit.

This is equivalent to getting `self`'s `EntryBuffer` and
calling `EntryBufferExt::set_max_length` on it.
]|
## `max`
the maximum length of the entry, or 0 for no maximum.
 (other than the maximum length of entries.) The value passed in will
 be clamped to the range 0-65536.
<!-- trait EntryExt::fn set_max_width_chars -->
Sets the desired maximum width in characters of `self`.
## `n_chars`
the new desired maximum width, in characters
<!-- trait EntryExt::fn set_overwrite_mode -->
Sets whether the text is overwritten when typing in the `Entry`.
## `overwrite`
new value
<!-- trait EntryExt::fn set_placeholder_text -->
Sets text to be displayed in `self` when it is empty and unfocused.
This can be used to give a visual hint of the expected contents of
the `Entry`.

Note that since the placeholder text gets removed when the entry
received focus, using this feature is a bit problematic if the entry
is given the initial focus in a window. Sometimes this can be
worked around by delaying the initial focus setting until the
first key event arrives.
## `text`
a string to be displayed when `self` is empty and unfocused, or `None`
<!-- trait EntryExt::fn set_progress_fraction -->
Causes the entry’s progress indicator to “fill in” the given
fraction of the bar. The fraction should be between 0.0 and 1.0,
inclusive.
## `fraction`
fraction of the task that’s been completed
<!-- trait EntryExt::fn set_progress_pulse_step -->
Sets the fraction of total entry width to move the progress
bouncing block for each call to `EntryExt::progress_pulse`.
## `fraction`
fraction between 0.0 and 1.0
<!-- trait EntryExt::fn set_tabs -->
Sets a `pango::TabArray`; the tabstops in the array are applied to the entry
text.
## `tabs`
a `pango::TabArray`
<!-- trait EntryExt::fn set_text -->
Sets the text in the widget to the given
value, replacing the current contents.

See `EntryBufferExt::set_text`.
## `text`
the new text
<!-- trait EntryExt::fn set_visibility -->
Sets whether the contents of the entry are visible or not.
When visibility is set to `false`, characters are displayed
as the invisible char, and will also appear that way when
the text in the entry widget is copied elsewhere.

By default, GTK+ picks the best invisible character available
in the current font, but it can be changed with
`EntryExt::set_invisible_char`.

Note that you probably want to set `Entry:input-purpose`
to `InputPurpose::Password` or `InputPurpose::Pin` to
inform input methods about the purpose of this entry,
in addition to setting visibility to `false`.
## `visible`
`true` if the contents of the entry are displayed
 as plaintext
<!-- trait EntryExt::fn set_width_chars -->
Changes the size request of the entry to be about the right size
for `n_chars` characters. Note that it changes the size
request, the size can still be affected by
how you pack the widget into containers. If `n_chars` is -1, the
size reverts to the default entry size.
## `n_chars`
width in chars
<!-- trait EntryExt::fn text_index_to_layout_index -->
Converts from a position in the entry contents (returned
by `EntryExt::get_text`) to a position in the
entry’s `pango::Layout` (returned by `EntryExt::get_layout`,
with text retrieved via `pango::Layout::get_text`).
## `text_index`
byte index into the entry contents

# Returns

byte index into the entry layout text
<!-- trait EntryExt::fn unset_invisible_char -->
Unsets the invisible char previously set with
`EntryExt::set_invisible_char`. So that the
default invisible char is used again.
<!-- trait EntryExt::fn connect_activate -->
The ::activate signal is emitted when the user hits
the Enter key.

While this signal is used as a
[keybinding signal][`BindingSignal`],
it is also commonly used by applications to intercept
activation of entries.

The default bindings for this signal are all forms of the Enter key.
<!-- trait EntryExt::fn connect_backspace -->
The ::backspace signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

The default bindings for this signal are
Backspace and Shift-Backspace.
<!-- trait EntryExt::fn connect_copy_clipboard -->
The ::copy-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to copy the selection to the clipboard.

The default bindings for this signal are
Ctrl-c and Ctrl-Insert.
<!-- trait EntryExt::fn connect_cut_clipboard -->
The ::cut-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to cut the selection to the clipboard.

The default bindings for this signal are
Ctrl-x and Shift-Delete.
<!-- trait EntryExt::fn connect_delete_from_cursor -->
The ::delete-from-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a text deletion.

If the `type_` is `DeleteType::Chars`, GTK+ deletes the selection
if there is one, otherwise it deletes the requested number
of characters.

The default bindings for this signal are
Delete for deleting a character and Ctrl-Delete for
deleting a word.
## `type_`
the granularity of the deletion, as a `DeleteType`
## `count`
the number of `type_` units to delete
<!-- trait EntryExt::fn connect_icon_press -->
The ::icon-press signal is emitted when an activatable icon
is clicked.
## `icon_pos`
The position of the clicked icon
## `event`
the button press event
<!-- trait EntryExt::fn connect_icon_release -->
The ::icon-release signal is emitted on the button release from a
mouse click over an activatable icon.
## `icon_pos`
The position of the clicked icon
## `event`
the button release event
<!-- trait EntryExt::fn connect_insert_at_cursor -->
The ::insert-at-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates the insertion of a
fixed string at the cursor.

This signal has no default bindings.
## `string`
the string to insert
<!-- trait EntryExt::fn connect_insert_emoji -->
The ::insert-emoji signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to present the Emoji chooser for the `entry`.

The default bindings for this signal are Ctrl-. and Ctrl-;

Feature: `v3_22_27`

<!-- trait EntryExt::fn connect_move_cursor -->
The ::move-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a cursor movement.
If the cursor is not visible in `entry`, this signal causes
the viewport to be moved instead.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically.

The default bindings for this signal come in two variants,
the variant with the Shift modifier extends the selection,
the variant without the Shift modifer does not.
There are too many key combinations to list them all here.
- Arrow keys move by individual characters/lines
- Ctrl-arrow key combinations move by words/paragraphs
- Home/End keys move to the ends of the buffer
## `step`
the granularity of the move, as a `MovementStep`
## `count`
the number of `step` units to move
## `extend_selection`
`true` if the move should extend the selection
<!-- trait EntryExt::fn connect_paste_clipboard -->
The ::paste-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to paste the contents of the clipboard
into the text view.

The default bindings for this signal are
Ctrl-v and Shift-Insert.
<!-- trait EntryExt::fn connect_populate_popup -->
The ::populate-popup signal gets emitted before showing the
context menu of the entry.

If you need to add items to the context menu, connect
to this signal and append your items to the `widget`, which
will be a `Menu` in this case.

If `Entry:populate-all` is `true`, this signal will
also be emitted to populate touch popups. In this case,
`widget` will be a different container, e.g. a `Toolbar`.
The signal handler should not make assumptions about the
type of `widget`.
## `widget`
the container that is being populated
<!-- trait EntryExt::fn connect_preedit_changed -->
If an input method is used, the typed text will not immediately
be committed to the buffer. So if you are interested in the text,
connect to this signal.
## `preedit`
the current preedit string
<!-- trait EntryExt::fn connect_toggle_overwrite -->
The ::toggle-overwrite signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to toggle the overwrite mode of the entry.

The default bindings for this signal is Insert.
<!-- trait EntryExt::fn get_property_attributes -->
A list of Pango attributes to apply to the text of the entry.

This is mainly useful to change the size or weight of the text.

The `pango::Attribute`'s `start_index` and `end_index` must refer to the
`EntryBuffer` text, i.e. without the preedit string.
<!-- trait EntryExt::fn set_property_attributes -->
A list of Pango attributes to apply to the text of the entry.

This is mainly useful to change the size or weight of the text.

The `pango::Attribute`'s `start_index` and `end_index` must refer to the
`EntryBuffer` text, i.e. without the preedit string.
<!-- trait EntryExt::fn get_property_caps_lock_warning -->
Whether password entries will show a warning when Caps Lock is on.

Note that the warning is shown using a secondary icon, and thus
does not work if you are using the secondary icon position for some
other purpose.
<!-- trait EntryExt::fn set_property_caps_lock_warning -->
Whether password entries will show a warning when Caps Lock is on.

Note that the warning is shown using a secondary icon, and thus
does not work if you are using the secondary icon position for some
other purpose.
<!-- trait EntryExt::fn get_property_completion -->
The auxiliary completion object to use with the entry.
<!-- trait EntryExt::fn set_property_completion -->
The auxiliary completion object to use with the entry.
<!-- trait EntryExt::fn get_property_im_module -->
Which IM (input method) module should be used for this entry.
See `IMContext`.

Setting this to a non-`None` value overrides the
system-wide IM module setting. See the `Settings`
`Settings:gtk-im-module` property.
<!-- trait EntryExt::fn set_property_im_module -->
Which IM (input method) module should be used for this entry.
See `IMContext`.

Setting this to a non-`None` value overrides the
system-wide IM module setting. See the `Settings`
`Settings:gtk-im-module` property.
<!-- trait EntryExt::fn get_property_input_hints -->
Additional hints (beyond `Entry:input-purpose`) that
allow input methods to fine-tune their behaviour.
<!-- trait EntryExt::fn set_property_input_hints -->
Additional hints (beyond `Entry:input-purpose`) that
allow input methods to fine-tune their behaviour.
<!-- trait EntryExt::fn get_property_input_purpose -->
The purpose of this text field.

This property can be used by on-screen keyboards and other input
methods to adjust their behaviour.

Note that setting the purpose to `InputPurpose::Password` or
`InputPurpose::Pin` is independent from setting
`Entry:visibility`.
<!-- trait EntryExt::fn set_property_input_purpose -->
The purpose of this text field.

This property can be used by on-screen keyboards and other input
methods to adjust their behaviour.

Note that setting the purpose to `InputPurpose::Password` or
`InputPurpose::Pin` is independent from setting
`Entry:visibility`.
<!-- trait EntryExt::fn get_property_invisible_char -->
The invisible character is used when masking entry contents (in
\"password mode\")"). When it is not explicitly set with the
`Entry:invisible-char` property, GTK+ determines the character
to use from a list of possible candidates, depending on availability
in the current font.

This style property allows the theme to prepend a character
to the list of candidates.
<!-- trait EntryExt::fn set_property_invisible_char -->
The invisible character is used when masking entry contents (in
\"password mode\")"). When it is not explicitly set with the
`Entry:invisible-char` property, GTK+ determines the character
to use from a list of possible candidates, depending on availability
in the current font.

This style property allows the theme to prepend a character
to the list of candidates.
<!-- trait EntryExt::fn get_property_invisible_char_set -->
Whether the invisible char has been set for the `Entry`.
<!-- trait EntryExt::fn set_property_invisible_char_set -->
Whether the invisible char has been set for the `Entry`.
<!-- trait EntryExt::fn get_property_max_width_chars -->
The desired maximum width of the entry, in characters.
If this property is set to -1, the width will be calculated
automatically.
<!-- trait EntryExt::fn set_property_max_width_chars -->
The desired maximum width of the entry, in characters.
If this property is set to -1, the width will be calculated
automatically.
<!-- trait EntryExt::fn get_property_overwrite_mode -->
If text is overwritten when typing in the `Entry`.
<!-- trait EntryExt::fn set_property_overwrite_mode -->
If text is overwritten when typing in the `Entry`.
<!-- trait EntryExt::fn get_property_placeholder_text -->
The text that will be displayed in the `Entry` when it is empty
and unfocused.
<!-- trait EntryExt::fn set_property_placeholder_text -->
The text that will be displayed in the `Entry` when it is empty
and unfocused.
<!-- trait EntryExt::fn get_property_populate_all -->
If :populate-all is `true`, the `Entry::populate-popup`
signal is also emitted for touch popups.
<!-- trait EntryExt::fn set_property_populate_all -->
If :populate-all is `true`, the `Entry::populate-popup`
signal is also emitted for touch popups.
<!-- trait EntryExt::fn get_property_primary_icon_activatable -->
Whether the primary icon is activatable.

GTK+ emits the `Entry::icon-press` and `Entry::icon-release`
signals only on sensitive, activatable icons.

Sensitive, but non-activatable icons can be used for purely
informational purposes.
<!-- trait EntryExt::fn set_property_primary_icon_activatable -->
Whether the primary icon is activatable.

GTK+ emits the `Entry::icon-press` and `Entry::icon-release`
signals only on sensitive, activatable icons.

Sensitive, but non-activatable icons can be used for purely
informational purposes.
<!-- trait EntryExt::fn get_property_primary_icon_gicon -->
The `gio::Icon` to use for the primary icon for the entry.
<!-- trait EntryExt::fn set_property_primary_icon_gicon -->
The `gio::Icon` to use for the primary icon for the entry.
<!-- trait EntryExt::fn get_property_primary_icon_name -->
The icon name to use for the primary icon for the entry.
<!-- trait EntryExt::fn set_property_primary_icon_name -->
The icon name to use for the primary icon for the entry.
<!-- trait EntryExt::fn get_property_primary_icon_pixbuf -->
A pixbuf to use as the primary icon for the entry.
<!-- trait EntryExt::fn set_property_primary_icon_pixbuf -->
A pixbuf to use as the primary icon for the entry.
<!-- trait EntryExt::fn get_property_primary_icon_sensitive -->
Whether the primary icon is sensitive.

An insensitive icon appears grayed out. GTK+ does not emit the
`Entry::icon-press` and `Entry::icon-release` signals and
does not allow DND from insensitive icons.

An icon should be set insensitive if the action that would trigger
when clicked is currently not available.
<!-- trait EntryExt::fn set_property_primary_icon_sensitive -->
Whether the primary icon is sensitive.

An insensitive icon appears grayed out. GTK+ does not emit the
`Entry::icon-press` and `Entry::icon-release` signals and
does not allow DND from insensitive icons.

An icon should be set insensitive if the action that would trigger
when clicked is currently not available.
<!-- trait EntryExt::fn get_property_primary_icon_storage_type -->
The representation which is used for the primary icon of the entry.
<!-- trait EntryExt::fn get_property_primary_icon_tooltip_markup -->
The contents of the tooltip on the primary icon, which is marked up
with the [Pango text markup language][PangoMarkupFormat].

Also see `EntryExt::set_icon_tooltip_markup`.
<!-- trait EntryExt::fn set_property_primary_icon_tooltip_markup -->
The contents of the tooltip on the primary icon, which is marked up
with the [Pango text markup language][PangoMarkupFormat].

Also see `EntryExt::set_icon_tooltip_markup`.
<!-- trait EntryExt::fn get_property_primary_icon_tooltip_text -->
The contents of the tooltip on the primary icon.

Also see `EntryExt::set_icon_tooltip_text`.
<!-- trait EntryExt::fn set_property_primary_icon_tooltip_text -->
The contents of the tooltip on the primary icon.

Also see `EntryExt::set_icon_tooltip_text`.
<!-- trait EntryExt::fn get_property_progress_fraction -->
The current fraction of the task that's been completed.
<!-- trait EntryExt::fn set_property_progress_fraction -->
The current fraction of the task that's been completed.
<!-- trait EntryExt::fn get_property_progress_pulse_step -->
The fraction of total entry width to move the progress
bouncing block for each call to `EntryExt::progress_pulse`.
<!-- trait EntryExt::fn set_property_progress_pulse_step -->
The fraction of total entry width to move the progress
bouncing block for each call to `EntryExt::progress_pulse`.
<!-- trait EntryExt::fn get_property_secondary_icon_activatable -->
Whether the secondary icon is activatable.

GTK+ emits the `Entry::icon-press` and `Entry::icon-release`
signals only on sensitive, activatable icons.

Sensitive, but non-activatable icons can be used for purely
informational purposes.
<!-- trait EntryExt::fn set_property_secondary_icon_activatable -->
Whether the secondary icon is activatable.

GTK+ emits the `Entry::icon-press` and `Entry::icon-release`
signals only on sensitive, activatable icons.

Sensitive, but non-activatable icons can be used for purely
informational purposes.
<!-- trait EntryExt::fn get_property_secondary_icon_gicon -->
The `gio::Icon` to use for the secondary icon for the entry.
<!-- trait EntryExt::fn set_property_secondary_icon_gicon -->
The `gio::Icon` to use for the secondary icon for the entry.
<!-- trait EntryExt::fn get_property_secondary_icon_name -->
The icon name to use for the secondary icon for the entry.
<!-- trait EntryExt::fn set_property_secondary_icon_name -->
The icon name to use for the secondary icon for the entry.
<!-- trait EntryExt::fn get_property_secondary_icon_pixbuf -->
An pixbuf to use as the secondary icon for the entry.
<!-- trait EntryExt::fn set_property_secondary_icon_pixbuf -->
An pixbuf to use as the secondary icon for the entry.
<!-- trait EntryExt::fn get_property_secondary_icon_sensitive -->
Whether the secondary icon is sensitive.

An insensitive icon appears grayed out. GTK+ does not emit the
`Entry::icon-press` and `Entry::icon-release` signals and
does not allow DND from insensitive icons.

An icon should be set insensitive if the action that would trigger
when clicked is currently not available.
<!-- trait EntryExt::fn set_property_secondary_icon_sensitive -->
Whether the secondary icon is sensitive.

An insensitive icon appears grayed out. GTK+ does not emit the
`Entry::icon-press` and `Entry::icon-release` signals and
does not allow DND from insensitive icons.

An icon should be set insensitive if the action that would trigger
when clicked is currently not available.
<!-- trait EntryExt::fn get_property_secondary_icon_storage_type -->
The representation which is used for the secondary icon of the entry.
<!-- trait EntryExt::fn get_property_secondary_icon_tooltip_markup -->
The contents of the tooltip on the secondary icon, which is marked up
with the [Pango text markup language][PangoMarkupFormat].

Also see `EntryExt::set_icon_tooltip_markup`.
<!-- trait EntryExt::fn set_property_secondary_icon_tooltip_markup -->
The contents of the tooltip on the secondary icon, which is marked up
with the [Pango text markup language][PangoMarkupFormat].

Also see `EntryExt::set_icon_tooltip_markup`.
<!-- trait EntryExt::fn get_property_secondary_icon_tooltip_text -->
The contents of the tooltip on the secondary icon.

Also see `EntryExt::set_icon_tooltip_text`.
<!-- trait EntryExt::fn set_property_secondary_icon_tooltip_text -->
The contents of the tooltip on the secondary icon.

Also see `EntryExt::set_icon_tooltip_text`.
<!-- trait EntryExt::fn get_property_shadow_type -->
Which kind of shadow to draw around the entry when
`Entry:has-frame` is set to `true`.

# Deprecated since 3.20

Use CSS to determine the style of the border;
 the value of this style property is ignored.
<!-- trait EntryExt::fn set_property_shadow_type -->
Which kind of shadow to draw around the entry when
`Entry:has-frame` is set to `true`.

# Deprecated since 3.20

Use CSS to determine the style of the border;
 the value of this style property is ignored.
<!-- trait EntryExt::fn get_property_text_length -->
The length of the text in the `Entry`.
<!-- trait EntryExt::fn get_property_truncate_multiline -->
When `true`, pasted multi-line text is truncated to the first line.
<!-- trait EntryExt::fn set_property_truncate_multiline -->
When `true`, pasted multi-line text is truncated to the first line.
<!-- trait EntryExt::fn get_property_xalign -->
The horizontal alignment, from 0 (left) to 1 (right).
Reversed for RTL layouts.
<!-- trait EntryExt::fn set_property_xalign -->
The horizontal alignment, from 0 (left) to 1 (right).
Reversed for RTL layouts.
<!-- struct EntryBuffer -->
The `EntryBuffer` class contains the actual text displayed in a
`Entry` widget.

A single `EntryBuffer` object can be shared by multiple `Entry`
widgets which will then share the same text content, but not the cursor
position, visibility attributes, icon etc.

`EntryBuffer` may be derived from. Such a derived class might allow
text to be stored in an alternate location, such as non-pageable memory,
useful in the case of important passwords. Or a derived class could
integrate with an application’s concept of undo/redo.

# Implements

[`EntryBufferExt`](trait.EntryBufferExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait EntryBufferExt -->
Trait containing all `EntryBuffer` methods.

# Implementors

[`EntryBuffer`](struct.EntryBuffer.html)
<!-- impl EntryBuffer::fn new -->
Create a new `EntryBuffer` object.

Optionally, specify initial text to set in the buffer.
## `initial_chars`
initial buffer text, or `None`
## `n_initial_chars`
number of characters in `initial_chars`, or -1

# Returns

A new `EntryBuffer` object.
<!-- trait EntryBufferExt::fn delete_text -->
Deletes a sequence of characters from the buffer. `n_chars` characters are
deleted starting at `position`. If `n_chars` is negative, then all characters
until the end of the text are deleted.

If `position` or `n_chars` are out of bounds, then they are coerced to sane
values.

Note that the positions are specified in characters, not bytes.
## `position`
position at which to delete text
## `n_chars`
number of characters to delete

# Returns

The number of characters deleted.
<!-- trait EntryBufferExt::fn emit_deleted_text -->
Used when subclassing `EntryBuffer`
## `position`
position at which text was deleted
## `n_chars`
number of characters deleted
<!-- trait EntryBufferExt::fn emit_inserted_text -->
Used when subclassing `EntryBuffer`
## `position`
position at which text was inserted
## `chars`
text that was inserted
## `n_chars`
number of characters inserted
<!-- trait EntryBufferExt::fn get_bytes -->
Retrieves the length in bytes of the buffer.
See `EntryBufferExt::get_length`.

# Returns

The byte length of the buffer.
<!-- trait EntryBufferExt::fn get_length -->
Retrieves the length in characters of the buffer.

# Returns

The number of characters in the buffer.
<!-- trait EntryBufferExt::fn get_max_length -->
Retrieves the maximum allowed length of the text in
`self`. See `EntryBufferExt::set_max_length`.

# Returns

the maximum allowed number of characters
 in `EntryBuffer`, or 0 if there is no maximum.
<!-- trait EntryBufferExt::fn get_text -->
Retrieves the contents of the buffer.

The memory pointer returned by this call will not change
unless this object emits a signal, or is finalized.

# Returns

a pointer to the contents of the widget as a
 string. This string points to internally allocated
 storage in the buffer and must not be freed, modified or
 stored.
<!-- trait EntryBufferExt::fn insert_text -->
Inserts `n_chars` characters of `chars` into the contents of the
buffer, at position `position`.

If `n_chars` is negative, then characters from chars will be inserted
until a null-terminator is found. If `position` or `n_chars` are out of
bounds, or the maximum buffer text length is exceeded, then they are
coerced to sane values.

Note that the position and length are in characters, not in bytes.
## `position`
the position at which to insert text.
## `chars`
the text to insert into the buffer.
## `n_chars`
the length of the text in characters, or -1

# Returns

The number of characters actually inserted.
<!-- trait EntryBufferExt::fn set_max_length -->
Sets the maximum allowed length of the contents of the buffer. If
the current contents are longer than the given length, then they
will be truncated to fit.
## `max_length`
the maximum length of the entry buffer, or 0 for no maximum.
 (other than the maximum length of entries.) The value passed in will
 be clamped to the range 0-65536.
<!-- trait EntryBufferExt::fn set_text -->
Sets the text in the buffer.

This is roughly equivalent to calling `EntryBufferExt::delete_text`
and `EntryBufferExt::insert_text`.

Note that `n_chars` is in characters, not in bytes.
## `chars`
the new text
## `n_chars`
the number of characters in `text`, or -1
<!-- trait EntryBufferExt::fn connect_deleted_text -->
This signal is emitted after text is deleted from the buffer.
## `position`
the position the text was deleted at.
## `n_chars`
The number of characters that were deleted.
<!-- trait EntryBufferExt::fn connect_inserted_text -->
This signal is emitted after text is inserted into the buffer.
## `position`
the position the text was inserted at.
## `chars`
The text that was inserted.
## `n_chars`
The number of characters that were inserted.
<!-- trait EntryBufferExt::fn get_property_length -->
The length (in characters) of the text in buffer.
<!-- trait EntryBufferExt::fn get_property_max_length -->
The maximum length (in characters) of the text in the buffer.
<!-- trait EntryBufferExt::fn set_property_max_length -->
The maximum length (in characters) of the text in the buffer.
<!-- trait EntryBufferExt::fn get_property_text -->
The contents of the buffer.
<!-- trait EntryBufferExt::fn set_property_text -->
The contents of the buffer.
<!-- struct EntryCompletion -->
`EntryCompletion` is an auxiliary object to be used in conjunction with
`Entry` to provide the completion functionality. It implements the
`CellLayout` interface, to allow the user to add extra cells to the
`TreeView` with completion matches.

“Completion functionality” means that when the user modifies the text
in the entry, `EntryCompletion` checks which rows in the model match
the current content of the entry, and displays a list of matches.
By default, the matching is done by comparing the entry text
case-insensitively against the text column of the model (see
`EntryCompletionExt::set_text_column`), but this can be overridden
with a custom match function (see `EntryCompletionExt::set_match_func`).

When the user selects a completion, the content of the entry is
updated. By default, the content of the entry is replaced by the
text column of the model, but this can be overridden by connecting
to the `EntryCompletion::match-selected` signal and updating the
entry in the signal handler. Note that you should return `true` from
the signal handler to suppress the default behaviour.

To add completion functionality to an entry, use `EntryExt::set_completion`.

In addition to regular completion matches, which will be inserted into the
entry when they are selected, `EntryCompletion` also allows to display
“actions” in the popup window. Their appearance is similar to menuitems,
to differentiate them clearly from completion strings. When an action is
selected, the `EntryCompletion::action-activated` signal is emitted.

`EntryCompletion` uses a `TreeModelFilter` model to represent the
subset of the entire model that is currently matching. While the
`EntryCompletion` signals `EntryCompletion::match-selected` and
`EntryCompletion::cursor-on-match` take the original model and an
iter pointing to that model as arguments, other callbacks and signals
(such as ``GtkCellLayoutDataFuncs`` or `CellArea::apply-attributes`)
will generally take the filter model as argument. As long as you are
only calling `TreeModel::get`, this will make no difference to
you. If for some reason, you need the original model, use
`TreeModelFilterExt::get_model`. Don’t forget to use
`TreeModelFilterExt::convert_iter_to_child_iter` to obtain a
matching iter.

# Implements

[`EntryCompletionExt`](trait.EntryCompletionExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`EntryCompletionExtManual`](prelude/trait.EntryCompletionExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait EntryCompletionExt -->
Trait containing all `EntryCompletion` methods.

# Implementors

[`EntryCompletion`](struct.EntryCompletion.html)
<!-- impl EntryCompletion::fn new -->
Creates a new `EntryCompletion` object.

# Returns

A newly created `EntryCompletion` object
<!-- impl EntryCompletion::fn new_with_area -->
Creates a new `EntryCompletion` object using the
specified `area` to layout cells in the underlying
`TreeViewColumn` for the drop-down menu.
## `area`
the `CellArea` used to layout cells

# Returns

A newly created `EntryCompletion` object
<!-- trait EntryCompletionExt::fn complete -->
Requests a completion operation, or in other words a refiltering of the
current list with completions, using the current key. The completion list
view will be updated accordingly.
<!-- trait EntryCompletionExt::fn compute_prefix -->
Computes the common prefix that is shared by all rows in `self`
that start with `key`. If no row matches `key`, `None` will be returned.
Note that a text column must have been set for this function to work,
see `EntryCompletionExt::set_text_column` for details.
## `key`
The text to complete for

# Returns

The common prefix all rows starting with
 `key` or `None` if no row matches `key`.
<!-- trait EntryCompletionExt::fn delete_action -->
Deletes the action at `index_` from `self`’s action list.

Note that `index_` is a relative position and the position of an
action may have changed since it was inserted.
## `index_`
the index of the item to delete
<!-- trait EntryCompletionExt::fn get_completion_prefix -->
Get the original text entered by the user that triggered
the completion or `None` if there’s no completion ongoing.

# Returns

the prefix for the current completion
<!-- trait EntryCompletionExtManual::fn get_entry -->
Gets the entry `self` has been attached to.

# Returns

The entry `self` has been attached to
<!-- trait EntryCompletionExt::fn get_inline_completion -->
Returns whether the common prefix of the possible completions should
be automatically inserted in the entry.

# Returns

`true` if inline completion is turned on
<!-- trait EntryCompletionExt::fn get_inline_selection -->
Returns `true` if inline-selection mode is turned on.

# Returns

`true` if inline-selection mode is on
<!-- trait EntryCompletionExt::fn get_minimum_key_length -->
Returns the minimum key length as set for `self`.

# Returns

The currently used minimum key length
<!-- trait EntryCompletionExt::fn get_model -->
Returns the model the `EntryCompletion` is using as data source.
Returns `None` if the model is unset.

# Returns

A `TreeModel`, or `None` if none
 is currently being used
<!-- trait EntryCompletionExt::fn get_popup_completion -->
Returns whether the completions should be presented in a popup window.

# Returns

`true` if popup completion is turned on
<!-- trait EntryCompletionExt::fn get_popup_set_width -->
Returns whether the completion popup window will be resized to the
width of the entry.

# Returns

`true` if the popup window will be resized to the width of
 the entry
<!-- trait EntryCompletionExt::fn get_popup_single_match -->
Returns whether the completion popup window will appear even if there is
only a single match.

# Returns

`true` if the popup window will appear regardless of the
 number of matches
<!-- trait EntryCompletionExt::fn get_text_column -->
Returns the column in the model of `self` to get strings from.

# Returns

the column containing the strings
<!-- trait EntryCompletionExt::fn insert_action_markup -->
Inserts an action in `self`’s action item list at position `index_`
with markup `markup`.
## `index_`
the index of the item to insert
## `markup`
markup of the item to insert
<!-- trait EntryCompletionExt::fn insert_action_text -->
Inserts an action in `self`’s action item list at position `index_`
with text `text`. If you want the action item to have markup, use
`EntryCompletionExt::insert_action_markup`.

Note that `index_` is a relative position in the list of actions and
the position of an action can change when deleting a different action.
## `index_`
the index of the item to insert
## `text`
text of the item to insert
<!-- trait EntryCompletionExt::fn insert_prefix -->
Requests a prefix insertion.
<!-- trait EntryCompletionExt::fn set_inline_completion -->
Sets whether the common prefix of the possible completions should
be automatically inserted in the entry.
## `inline_completion`
`true` to do inline completion
<!-- trait EntryCompletionExt::fn set_inline_selection -->
Sets whether it is possible to cycle through the possible completions
inside the entry.
## `inline_selection`
`true` to do inline selection
<!-- trait EntryCompletionExt::fn set_match_func -->
Sets the match function for `self` to be `func`. The match function
is used to determine if a row should or should not be in the completion
list.
## `func`
the ``GtkEntryCompletionMatchFunc`` to use
## `func_data`
user data for `func`
## `func_notify`
destroy notify for `func_data`.
<!-- trait EntryCompletionExt::fn set_minimum_key_length -->
Requires the length of the search key for `self` to be at least
`length`. This is useful for long lists, where completing using a small
key takes a lot of time and will come up with meaningless results anyway
(ie, a too large dataset).
## `length`
the minimum length of the key in order to start completing
<!-- trait EntryCompletionExt::fn set_model -->
Sets the model for a `EntryCompletion`. If `self` already has
a model set, it will remove it before setting the new model.
If model is `None`, then it will unset the model.
## `model`
the `TreeModel`
<!-- trait EntryCompletionExt::fn set_popup_completion -->
Sets whether the completions should be presented in a popup window.
## `popup_completion`
`true` to do popup completion
<!-- trait EntryCompletionExt::fn set_popup_set_width -->
Sets whether the completion popup window will be resized to be the same
width as the entry.
## `popup_set_width`
`true` to make the width of the popup the same as the entry
<!-- trait EntryCompletionExt::fn set_popup_single_match -->
Sets whether the completion popup window will appear even if there is
only a single match. You may want to set this to `false` if you
are using [inline completion][`EntryCompletion`--inline-completion].
## `popup_single_match`
`true` if the popup should appear even for a single
 match
<!-- trait EntryCompletionExt::fn set_text_column -->
Convenience function for setting up the most used case of this code: a
completion list with just strings. This function will set up `self`
to have a list displaying all (and just) strings in the completion list,
and to get those strings from `column` in the model of `self`.

This functions creates and adds a `CellRendererText` for the selected
column. If you need to set the text column, but don't want the cell
renderer, use `gobject::ObjectExt::set` to set the `EntryCompletion:text-column`
property directly.
## `column`
the column in the model of `self` to get strings from
<!-- trait EntryCompletionExt::fn connect_action_activated -->
Gets emitted when an action is activated.
## `index`
the index of the activated action
<!-- trait EntryCompletionExt::fn connect_cursor_on_match -->
Gets emitted when a match from the cursor is on a match
of the list. The default behaviour is to replace the contents
of the entry with the contents of the text column in the row
pointed to by `iter`.

Note that `model` is the model that was passed to
`EntryCompletionExt::set_model`.
## `model`
the `TreeModel` containing the matches
## `iter`
a `TreeIter` positioned at the selected match

# Returns

`true` if the signal has been handled
<!-- trait EntryCompletionExt::fn connect_insert_prefix -->
Gets emitted when the inline autocompletion is triggered.
The default behaviour is to make the entry display the
whole prefix and select the newly inserted part.

Applications may connect to this signal in order to insert only a
smaller part of the `prefix` into the entry - e.g. the entry used in
the `FileChooser` inserts only the part of the prefix up to the
next '/'.
## `prefix`
the common prefix of all possible completions

# Returns

`true` if the signal has been handled
<!-- trait EntryCompletionExt::fn connect_match_selected -->
Gets emitted when a match from the list is selected.
The default behaviour is to replace the contents of the
entry with the contents of the text column in the row
pointed to by `iter`.

Note that `model` is the model that was passed to
`EntryCompletionExt::set_model`.
## `model`
the `TreeModel` containing the matches
## `iter`
a `TreeIter` positioned at the selected match

# Returns

`true` if the signal has been handled
<!-- trait EntryCompletionExt::fn connect_no_matches -->
Gets emitted when the filter model has zero
number of rows in completion_complete method.
(In other words when `EntryCompletion` is out of
 suggestions)
<!-- trait EntryCompletionExt::fn get_property_cell_area -->
The `CellArea` used to layout cell renderers in the treeview column.

If no area is specified when creating the entry completion with
`EntryCompletion::new_with_area` a horizontally oriented
`CellAreaBox` will be used.
<!-- trait EntryCompletionExt::fn set_property_cell_area -->
The `CellArea` used to layout cell renderers in the treeview column.

If no area is specified when creating the entry completion with
`EntryCompletion::new_with_area` a horizontally oriented
`CellAreaBox` will be used.
<!-- trait EntryCompletionExt::fn get_property_inline_completion -->
Determines whether the common prefix of the possible completions
should be inserted automatically in the entry. Note that this
requires text-column to be set, even if you are using a custom
match function.
<!-- trait EntryCompletionExt::fn set_property_inline_completion -->
Determines whether the common prefix of the possible completions
should be inserted automatically in the entry. Note that this
requires text-column to be set, even if you are using a custom
match function.
<!-- trait EntryCompletionExt::fn get_property_inline_selection -->
Determines whether the possible completions on the popup
will appear in the entry as you navigate through them.
<!-- trait EntryCompletionExt::fn set_property_inline_selection -->
Determines whether the possible completions on the popup
will appear in the entry as you navigate through them.
<!-- trait EntryCompletionExt::fn get_property_popup_completion -->
Determines whether the possible completions should be
shown in a popup window.
<!-- trait EntryCompletionExt::fn set_property_popup_completion -->
Determines whether the possible completions should be
shown in a popup window.
<!-- trait EntryCompletionExt::fn get_property_popup_set_width -->
Determines whether the completions popup window will be
resized to the width of the entry.
<!-- trait EntryCompletionExt::fn set_property_popup_set_width -->
Determines whether the completions popup window will be
resized to the width of the entry.
<!-- trait EntryCompletionExt::fn get_property_popup_single_match -->
Determines whether the completions popup window will shown
for a single possible completion. You probably want to set
this to `false` if you are using
[inline completion][`EntryCompletion`--inline-completion].
<!-- trait EntryCompletionExt::fn set_property_popup_single_match -->
Determines whether the completions popup window will shown
for a single possible completion. You probably want to set
this to `false` if you are using
[inline completion][`EntryCompletion`--inline-completion].
<!-- trait EntryCompletionExt::fn get_property_text_column -->
The column of the model containing the strings.
Note that the strings must be UTF-8.
<!-- trait EntryCompletionExt::fn set_property_text_column -->
The column of the model containing the strings.
Note that the strings must be UTF-8.
<!-- enum EntryIconPosition -->
Specifies the side of the entry at which an icon is placed.
<!-- enum EntryIconPosition::variant Primary -->
At the beginning of the entry (depending on the text direction).
<!-- enum EntryIconPosition::variant Secondary -->
At the end of the entry (depending on the text direction).
<!-- struct EventBox -->
The `EventBox` widget is a subclass of `Bin` which also has its
own window. It is useful since it allows you to catch events for widgets
which do not have their own window.

# Implements

[`EventBoxExt`](trait.EventBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait EventBoxExt -->
Trait containing all `EventBox` methods.

# Implementors

[`EventBox`](struct.EventBox.html)
<!-- impl EventBox::fn new -->
Creates a new `EventBox`.

# Returns

a new `EventBox`
<!-- trait EventBoxExt::fn get_above_child -->
Returns whether the event box window is above or below the
windows of its child. See `EventBoxExt::set_above_child`
for details.

# Returns

`true` if the event box window is above the
 window of its child
<!-- trait EventBoxExt::fn get_visible_window -->
Returns whether the event box has a visible window.
See `EventBoxExt::set_visible_window` for details.

# Returns

`true` if the event box window is visible
<!-- trait EventBoxExt::fn set_above_child -->
Set whether the event box window is positioned above the windows
of its child, as opposed to below it. If the window is above, all
events inside the event box will go to the event box. If the window
is below, events in windows of child widgets will first got to that
widget, and then to its parents.

The default is to keep the window below the child.
## `above_child`
`true` if the event box window is above its child
<!-- trait EventBoxExt::fn set_visible_window -->
Set whether the event box uses a visible or invisible child
window. The default is to use visible windows.

In an invisible window event box, the window that the
event box creates is a `gdk::WindowWindowClass::InputOnly` window, which
means that it is invisible and only serves to receive
events.

A visible window event box creates a visible (`gdk::WindowWindowClass::InputOutput`)
window that acts as the parent window for all the widgets
contained in the event box.

You should generally make your event box invisible if
you just want to trap events. Creating a visible window
may cause artifacts that are visible to the user, especially
if the user is using a theme with gradients or pixmaps.

The main reason to create a non input-only event box is if
you want to set the background to a different color or
draw on it.

There is one unexpected issue for an invisible event box that has its
window below the child. (See `EventBoxExt::set_above_child`.)
Since the input-only window is not an ancestor window of any windows
that descendent widgets of the event box create, events on these
windows aren’t propagated up by the windowing system, but only by GTK+.
The practical effect of this is if an event isn’t in the event
mask for the descendant window (see `Widget::add_events`),
it won’t be received by the event box.

This problem doesn’t occur for visible event boxes, because in
that case, the event box window is actually the ancestor of the
descendant windows, not just at the same place on the screen.
## `visible_window`
`true` to make the event box have a visible window
<!-- struct EventController -->
`EventController` is a base, low-level implementation for event
controllers. Those react to a series of ``GdkEvents``, and possibly trigger
actions as a consequence of those.

# Implements

[`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait EventControllerExt -->
Trait containing all `EventController` methods.

# Implementors

[`EventControllerKey`](struct.EventControllerKey.html), [`EventControllerMotion`](struct.EventControllerMotion.html), [`EventControllerScroll`](struct.EventControllerScroll.html), [`EventController`](struct.EventController.html), [`Gesture`](struct.Gesture.html), [`PadController`](struct.PadController.html)
<!-- trait EventControllerExt::fn get_propagation_phase -->
Gets the propagation phase at which `self` handles events.

# Returns

the propagation phase
<!-- trait EventControllerExt::fn get_widget -->
Returns the `Widget` this controller relates to.

# Returns

a `Widget`
<!-- trait EventControllerExt::fn handle_event -->
Feeds an events into `self`, so it can be interpreted
and the controller actions triggered.
## `event`
a ``GdkEvent``

# Returns

`true` if the event was potentially useful to trigger the
 controller action
<!-- trait EventControllerExt::fn reset -->
Resets the `self` to a clean state. Every interaction
the controller did through `EventController::handle-event`
will be dropped at this point.
<!-- trait EventControllerExt::fn set_propagation_phase -->
Sets the propagation phase at which a controller handles events.

If `phase` is `PropagationPhase::None`, no automatic event handling will be
performed, but other additional gesture maintenance will. In that phase,
the events can be managed by calling `EventControllerExt::handle_event`.
## `phase`
a propagation phase
<!-- trait EventControllerExt::fn get_property_propagation_phase -->
The propagation phase at which this controller will handle events.
<!-- trait EventControllerExt::fn set_property_propagation_phase -->
The propagation phase at which this controller will handle events.
<!-- trait EventControllerExt::fn get_property_widget -->
The widget receiving the ``GdkEvents`` that the controller will handle.
<!-- trait EventControllerExt::fn set_property_widget -->
The widget receiving the ``GdkEvents`` that the controller will handle.
<!-- struct EventControllerKey -->
`EventControllerKey` is an event controller meant for situations
where you need access to key events.

This object was added in 3.24.

Feature: `v3_24`

# Implements

[`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl EventControllerKey::fn get_im_context -->
Gets the IM context of a key controller.

Feature: `v3_24`


# Returns

the IM context
<!-- impl EventControllerKey::fn connect_key_pressed -->
This signal is emitted whenever a key is pressed.

Feature: `v3_24`

## `keyval`
the pressed key.
## `keycode`
the raw code of the pressed key.
## `state`
the bitmask, representing the state of modifier keys and pointer buttons. See `gdk::ModifierType`.

# Returns

`true` if the key press was handled, `false` otherwise.
<!-- impl EventControllerKey::fn connect_key_released -->
This signal is emitted whenever a key is released.

Feature: `v3_24`

## `keyval`
the released key.
## `keycode`
the raw code of the released key.
## `state`
the bitmask, representing the state of modifier keys and pointer buttons. See `gdk::ModifierType`.
<!-- struct EventControllerMotion -->
`EventControllerMotion` is an event controller meant for situations
where you need to track the position of the pointer.

This object was added in 3.24.

Feature: `v3_24`

# Implements

[`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl EventControllerMotion::fn new -->
Creates a new event controller that will handle motion events
for the given `widget`.

Feature: `v3_24`

## `widget`
a `Widget`

# Returns

a new `EventControllerMotion`
<!-- impl EventControllerMotion::fn connect_enter -->
Signals that the pointer has entered the widget.
## `x`
the x coordinate
## `y`
the y coordinate
<!-- impl EventControllerMotion::fn connect_leave -->
Signals that pointer has left the widget.
<!-- impl EventControllerMotion::fn connect_motion -->
Emitted when the pointer moves inside the widget.
## `x`
the x coordinate
## `y`
the y coordinate
<!-- struct EventControllerScroll -->
`EventControllerScroll` is an event controller meant to handle
scroll events from mice and touchpads. It is capable of handling
both discrete and continuous scroll events, abstracting them both
on the `EventControllerScroll::scroll` signal (deltas in the
discrete case are multiples of 1).

In the case of continuous scroll events, `EventControllerScroll`
encloses all `EventControllerScroll::scroll` events between two
`EventControllerScroll::scroll-begin` and `EventControllerScroll::scroll-end`
signals.

The behavior of the event controller can be modified by the
flags given at creation time, or modified at a later point through
`EventControllerScroll::set_flags` (e.g. because the scrolling
conditions of the widget changed).

The controller can be set up to emit motion for either/both vertical
and horizontal scroll events through `EventControllerScrollFlags::Vertical`,
`EventControllerScrollFlags::Horizontal` and `GTK_EVENT_CONTROLLER_SCROLL_BOTH`.
If any axis is disabled, the respective `EventControllerScroll::scroll`
delta will be 0. Vertical scroll events will be translated to horizontal
motion for the devices incapable of horizontal scrolling.

The event controller can also be forced to emit discrete events on all devices
through `EventControllerScrollFlags::Discrete`. This can be used to implement
discrete actions triggered through scroll events (e.g. switching across
combobox options).

The `EventControllerScrollFlags::Kinetic` flag toggles the emission of the
`EventControllerScroll::decelerate` signal, emitted at the end of scrolling
with two X/Y velocity arguments that are consistent with the motion that
was received.

This object was added in 3.24.

Feature: `v3_24`

# Implements

[`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl EventControllerScroll::fn new -->
Creates a new event controller that will handle scroll events
for the given `widget`.

Feature: `v3_24`

## `widget`
a `Widget`
## `flags`
behavior flags

# Returns

a new `EventControllerScroll`
<!-- impl EventControllerScroll::fn get_flags -->
Gets the flags conditioning the scroll controller behavior.

Feature: `v3_24`


# Returns

the controller flags.
<!-- impl EventControllerScroll::fn set_flags -->
Sets the flags conditioning scroll controller behavior.

Feature: `v3_24`

## `flags`
behavior flags
<!-- impl EventControllerScroll::fn connect_decelerate -->
Emitted after scroll is finished if the `EventControllerScrollFlags::Kinetic`
flag is set. `vel_x` and `vel_y` express the initial velocity that was
imprinted by the scroll events. `vel_x` and `vel_y` are expressed in
pixels/ms.
## `vel_x`
X velocity
## `vel_y`
Y velocity
<!-- impl EventControllerScroll::fn connect_scroll -->
Signals that the widget should scroll by the
amount specified by `dx` and `dy`.
## `dx`
X delta
## `dy`
Y delta
<!-- impl EventControllerScroll::fn connect_scroll_begin -->
Signals that a new scrolling operation has begun. It will
only be emitted on devices capable of it.
<!-- impl EventControllerScroll::fn connect_scroll_end -->
Signals that a new scrolling operation has finished. It will
only be emitted on devices capable of it.
<!-- impl EventControllerScroll::fn get_property_flags -->
The flags affecting event controller behavior

Feature: `v3_24`

<!-- impl EventControllerScroll::fn set_property_flags -->
The flags affecting event controller behavior

Feature: `v3_24`

<!-- struct EventControllerScrollFlags -->
Describes the behavior of a `EventControllerScroll`.
<!-- struct EventControllerScrollFlags::const NONE -->
Don't emit scroll.
<!-- struct EventControllerScrollFlags::const VERTICAL -->
Emit scroll with vertical deltas.
<!-- struct EventControllerScrollFlags::const HORIZONTAL -->
Emit scroll with horizontal deltas.
<!-- struct EventControllerScrollFlags::const DISCRETE -->
Only emit deltas that are multiples of 1.
<!-- struct EventControllerScrollFlags::const KINETIC -->
Emit `EventControllerScroll::decelerate`
 after continuous scroll finishes.
<!-- struct EventControllerScrollFlags::const BOTH_AXES -->
Emit scroll on both axes.

Feature: `v3_24`

<!-- enum EventSequenceState -->
Describes the state of a `gdk::EventSequence` in a `Gesture`.
<!-- enum EventSequenceState::variant None -->
The sequence is handled, but not grabbed.
<!-- enum EventSequenceState::variant Claimed -->
The sequence is handled and grabbed.
<!-- enum EventSequenceState::variant Denied -->
The sequence is denied.
<!-- struct Expander -->
A `Expander` allows the user to hide or show its child by clicking
on an expander triangle similar to the triangles used in a `TreeView`.

Normally you use an expander as you would use any other descendant
of `Bin`; you create the child widget and use `ContainerExt::add`
to add it to the expander. When the expander is toggled, it will take
care of showing and hiding the child automatically.

# Special Usage

There are situations in which you may prefer to show and hide the
expanded widget yourself, such as when you want to actually create
the widget at expansion time. In this case, create a `Expander`
but do not add a child to it. The expander widget has an
`Expander:expanded` property which can be used to monitor
its expansion state. You should watch this property with a signal
connection as follows:


```C
static void
expander_callback (GObject    *object,
                   GParamSpec *param_spec,
                   gpointer    user_data)
{
  GtkExpander *expander;

  expander = GTK_EXPANDER (object);

  if (gtk_expander_get_expanded (expander))
    {
      // Show or create widgets
    }
  else
    {
      // Hide or destroy widgets
    }
}

static void
create_expander (void)
{
  GtkWidget *expander = gtk_expander_new_with_mnemonic ("_More Options");
  g_signal_connect (expander, "notify::expanded",
                    G_CALLBACK (expander_callback), NULL);

  // ...
}
```

# `Expander` as `Buildable`

The `Expander` implementation of the `Buildable` interface supports
placing a child in the label position by specifying “label” as the
“type” attribute of a `<child>` element. A normal content child can be
specified without specifying a `<child>` type attribute.

An example of a UI definition fragment with `Expander`:

```plain
expander
├── title
│   ├── arrow
│   ╰── <label widget>
╰── <child>
```

`Expander` has three CSS nodes, the main node with the name expander,
a subnode with name title and node below it with name arrow. The arrow of an
expander that is showing its child gets the :checked pseudoclass added to it.

# Implements

[`ExpanderExt`](trait.ExpanderExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ExpanderExt -->
Trait containing all `Expander` methods.

# Implementors

[`Expander`](struct.Expander.html)
<!-- impl Expander::fn new -->
Creates a new expander using `label` as the text of the label.
## `label`
the text of the label

# Returns

a new `Expander` widget.
<!-- impl Expander::fn new_with_mnemonic -->
Creates a new expander using `label` as the text of the label.
If characters in `label` are preceded by an underscore, they are underlined.
If you need a literal underscore character in a label, use “__” (two
underscores). The first underlined character represents a keyboard
accelerator called a mnemonic.
Pressing Alt and that key activates the button.
## `label`
the text of the label with an underscore
 in front of the mnemonic character

# Returns

a new `Expander` widget.
<!-- trait ExpanderExt::fn get_expanded -->
Queries a `Expander` and returns its current state. Returns `true`
if the child widget is revealed.

See `ExpanderExt::set_expanded`.

# Returns

the current state of the expander
<!-- trait ExpanderExt::fn get_label -->
Fetches the text from a label widget including any embedded
underlines indicating mnemonics and Pango markup, as set by
`ExpanderExt::set_label`. If the label text has not been set the
return value will be `None`. This will be the case if you create an
empty button with `Button::new` to use as a container.

Note that this function behaved differently in versions prior to
2.14 and used to return the label text stripped of embedded
underlines indicating mnemonics and Pango markup. This problem can
be avoided by fetching the label text directly from the label
widget.

# Returns

The text of the label widget. This string is owned
 by the widget and must not be modified or freed.
<!-- trait ExpanderExt::fn get_label_fill -->
Returns whether the label widget will fill all available
horizontal space allocated to `self`.

# Returns

`true` if the label widget will fill all
 available horizontal space
<!-- trait ExpanderExt::fn get_label_widget -->
Retrieves the label widget for the frame. See
`ExpanderExt::set_label_widget`.

# Returns

the label widget,
 or `None` if there is none
<!-- trait ExpanderExt::fn get_resize_toplevel -->
Returns whether the expander will resize the toplevel widget
containing the expander upon resizing and collpasing.

# Returns

the “resize toplevel” setting.
<!-- trait ExpanderExt::fn get_spacing -->
Gets the value set by `ExpanderExt::set_spacing`.

# Deprecated since 3.20

Use margins on the child instead.

# Returns

spacing between the expander and child
<!-- trait ExpanderExt::fn get_use_markup -->
Returns whether the label’s text is interpreted as marked up with
the [Pango text markup language][PangoMarkupFormat].
See `ExpanderExt::set_use_markup`.

# Returns

`true` if the label’s text will be parsed for markup
<!-- trait ExpanderExt::fn get_use_underline -->
Returns whether an embedded underline in the expander label
indicates a mnemonic. See `ExpanderExt::set_use_underline`.

# Returns

`true` if an embedded underline in the expander
 label indicates the mnemonic accelerator keys
<!-- trait ExpanderExt::fn set_expanded -->
Sets the state of the expander. Set to `true`, if you want
the child widget to be revealed, and `false` if you want the
child widget to be hidden.
## `expanded`
whether the child widget is revealed
<!-- trait ExpanderExt::fn set_label -->
Sets the text of the label of the expander to `label`.

This will also clear any previously set labels.
## `label`
a string
<!-- trait ExpanderExt::fn set_label_fill -->
Sets whether the label widget should fill all available
horizontal space allocated to `self`.
## `label_fill`
`true` if the label should should fill
 all available horizontal space
<!-- trait ExpanderExt::fn set_label_widget -->
Set the label widget for the expander. This is the widget
that will appear embedded alongside the expander arrow.
## `label_widget`
the new label widget
<!-- trait ExpanderExt::fn set_resize_toplevel -->
Sets whether the expander will resize the toplevel widget
containing the expander upon resizing and collpasing.
## `resize_toplevel`
whether to resize the toplevel
<!-- trait ExpanderExt::fn set_spacing -->
Sets the spacing field of `self`, which is the number of
pixels to place between expander and the child.

# Deprecated since 3.20

Use margins on the child instead.
## `spacing`
distance between the expander and child in pixels
<!-- trait ExpanderExt::fn set_use_markup -->
Sets whether the text of the label contains markup in
[Pango’s text markup language][PangoMarkupFormat].
See `LabelExt::set_markup`.
## `use_markup`
`true` if the label’s text should be parsed for markup
<!-- trait ExpanderExt::fn set_use_underline -->
If true, an underline in the text of the expander label indicates
the next character should be used for the mnemonic accelerator key.
## `use_underline`
`true` if underlines in the text indicate mnemonics
<!-- trait ExpanderExt::fn get_property_resize_toplevel -->
When this property is `true`, the expander will resize the toplevel
widget containing the expander upon expanding and collapsing.
<!-- trait ExpanderExt::fn set_property_resize_toplevel -->
When this property is `true`, the expander will resize the toplevel
widget containing the expander upon expanding and collapsing.
<!-- trait ExpanderExt::fn get_property_spacing -->
Space to put between the label and the child when the
expander is expanded.

# Deprecated since 3.20

This property is deprecated and ignored.
 Use margins on the child instead.
<!-- trait ExpanderExt::fn set_property_spacing -->
Space to put between the label and the child when the
expander is expanded.

# Deprecated since 3.20

This property is deprecated and ignored.
 Use margins on the child instead.
<!-- struct FileChooser -->
`FileChooser` is an interface that can be implemented by file
selection widgets. In GTK+, the main objects that implement this
interface are `FileChooserWidget`, `FileChooserDialog`, and
`FileChooserButton`. You do not need to write an object that
implements the `FileChooser` interface unless you are trying to
adapt an existing file selector to expose a standard programming
interface.

`FileChooser` allows for shortcuts to various places in the filesystem.
In the default implementation these are displayed in the left pane. It
may be a bit confusing at first that these shortcuts come from various
sources and in various flavours, so lets explain the terminology here:

- Bookmarks: are created by the user, by dragging folders from the
 right pane to the left pane, or by using the “Add”. Bookmarks
 can be renamed and deleted by the user.

- Shortcuts: can be provided by the application. For example, a Paint
 program may want to add a shortcut for a Clipart folder. Shortcuts
 cannot be modified by the user.

- Volumes: are provided by the underlying filesystem abstraction. They are
 the “roots” of the filesystem.

# File Names and Encodings

When the user is finished selecting files in a
`FileChooser`, your program can get the selected names
either as filenames or as URIs. For URIs, the normal escaping
rules are applied if the URI contains non-ASCII characters.
However, filenames are always returned in
the character set specified by the
`G_FILENAME_ENCODING` environment variable.
Please see the GLib documentation for more details about this
variable.

This means that while you can pass the result of
`FileChooser::get_filename` to `open` or `fopen`,
you may not be able to directly set it as the text of a
`Label` widget unless you convert it first to UTF-8,
which all GTK+ widgets expect. You should use `g_filename_to_utf8`
to convert filenames into strings that can be passed to GTK+
widgets.

# Adding a Preview Widget

You can add a custom preview widget to a file chooser and then
get notification about when the preview needs to be updated.
To install a preview widget, use
`FileChooser::set_preview_widget`. Then, connect to the
`FileChooser::update-preview` signal to get notified when
you need to update the contents of the preview.

Your callback should use
`FileChooser::get_preview_filename` to see what needs
previewing. Once you have generated the preview for the
corresponding file, you must call
`FileChooser::set_preview_widget_active` with a boolean
flag that indicates whether your callback could successfully
generate a preview.

## Example: Using a Preview Widget ## {`gtkfilechooser`-preview}

```C
{
  GtkImage *preview;

  ...

  preview = gtk_image_new ();

  gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  g_signal_connect (my_file_chooser, "update-preview",
            G_CALLBACK (update_preview_cb), preview);
}

static void
update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
{
  GtkWidget *preview;
  char *filename;
  GdkPixbuf *pixbuf;
  gboolean have_preview;

  preview = GTK_WIDGET (data);
  filename = gtk_file_chooser_get_preview_filename (file_chooser);

  pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
  have_preview = (pixbuf != NULL);
  g_free (filename);

  gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
  if (pixbuf)
    g_object_unref (pixbuf);

  gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}
```

# Adding Extra Widgets

You can add extra widgets to a file chooser to provide options
that are not present in the default design. For example, you
can add a toggle button to give the user the option to open a
file in read-only mode. You can use
`FileChooser::set_extra_widget` to insert additional
widgets in a file chooser.

An example for adding extra widgets:

```C

  GtkWidget *toggle;

  ...

  toggle = gtk_check_button_new_with_label ("Open file read-only");
  gtk_widget_show (toggle);
  gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
}
```

If you want to set more than one extra widget in the file
chooser, you can a container such as a `Box` or a `Grid`
and include your widgets in it. Then, set the container as
the whole extra widget.

# Implements

[`FileChooserExt`](trait.FileChooserExt.html)
<!-- trait FileChooserExt -->
Trait containing all `FileChooser` methods.

# Implementors

[`FileChooserButton`](struct.FileChooserButton.html), [`FileChooserDialog`](struct.FileChooserDialog.html), [`FileChooserNative`](struct.FileChooserNative.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FileChooser`](struct.FileChooser.html)
<!-- trait FileChooserExt::fn add_choice -->
Adds a 'choice' to the file chooser. This is typically implemented
as a combobox or, for boolean choices, as a checkbutton. You can select
a value using `FileChooser::set_choice` before the dialog is shown,
and you can obtain the user-selected value in the ::response signal handler
using `FileChooser::get_choice`.

Compare `FileChooser::set_extra_widget`.

Feature: `v3_22`

## `id`
id for the added choice
## `label`
user-visible label for the added choice
## `options`
ids for the options of the choice, or `None` for a boolean choice
## `option_labels`
user-visible labels for the options, must be the same length as `options`
<!-- trait FileChooserExt::fn add_filter -->
Adds `filter` to the list of filters that the user can select between.
When a filter is selected, only files that are passed by that
filter are displayed.

Note that the `self` takes ownership of the filter, so you have to
ref and sink it if you want to keep a reference.
## `filter`
a `FileFilter`
<!-- trait FileChooserExt::fn add_shortcut_folder -->
Adds a folder to be displayed with the shortcut folders in a file chooser.
Note that shortcut folders do not get saved, as they are provided by the
application. For example, you can use this to add a
“/usr/share/mydrawprogram/Clipart” folder to the volume list.
## `folder`
filename of the folder to add

# Returns

`true` if the folder could be added successfully, `false`
otherwise. In the latter case, the `error` will be set as appropriate.
<!-- trait FileChooserExt::fn add_shortcut_folder_uri -->
Adds a folder URI to be displayed with the shortcut folders in a file
chooser. Note that shortcut folders do not get saved, as they are provided
by the application. For example, you can use this to add a
“file:///usr/share/mydrawprogram/Clipart” folder to the volume list.
## `uri`
URI of the folder to add

# Returns

`true` if the folder could be added successfully, `false`
otherwise. In the latter case, the `error` will be set as appropriate.
<!-- trait FileChooserExt::fn get_action -->
Gets the type of operation that the file chooser is performing; see
`FileChooser::set_action`.

# Returns

the action that the file selector is performing
<!-- trait FileChooserExt::fn get_choice -->
Gets the currently selected option in the 'choice' with the given ID.

Feature: `v3_22`

## `id`
the ID of the choice to get

# Returns

the ID of the currenly selected option
<!-- trait FileChooserExt::fn get_create_folders -->
Gets whether file choser will offer to create new folders.
See `FileChooser::set_create_folders`.

# Returns

`true` if the Create Folder button should be displayed.
<!-- trait FileChooserExt::fn get_current_folder -->
Gets the current folder of `self` as a local filename.
See `FileChooser::set_current_folder`.

Note that this is the folder that the file chooser is currently displaying
(e.g. "/home/username/Documents"), which is not the same
as the currently-selected folder if the chooser is in
`FileChooserAction::SelectFolder` mode
(e.g. "/home/username/Documents/selected-folder/". To get the
currently-selected folder in that mode, use `FileChooser::get_uri` as the
usual way to get the selection.

# Returns

the full path of the current
folder, or `None` if the current path cannot be represented as a local
filename. Free with `g_free`. This function will also return
`None` if the file chooser was unable to load the last folder that
was requested from it; for example, as would be for calling
`FileChooser::set_current_folder` on a nonexistent folder.
<!-- trait FileChooserExt::fn get_current_folder_file -->
Gets the current folder of `self` as `gio::File`.
See `FileChooser::get_current_folder_uri`.

# Returns

the `gio::File` for the current folder.
<!-- trait FileChooserExt::fn get_current_folder_uri -->
Gets the current folder of `self` as an URI.
See `FileChooser::set_current_folder_uri`.

Note that this is the folder that the file chooser is currently displaying
(e.g. "file:///home/username/Documents"), which is not the same
as the currently-selected folder if the chooser is in
`FileChooserAction::SelectFolder` mode
(e.g. "file:///home/username/Documents/selected-folder/". To get the
currently-selected folder in that mode, use `FileChooser::get_uri` as the
usual way to get the selection.

# Returns

the URI for the current folder.
Free with `g_free`. This function will also return `None` if the file chooser
was unable to load the last folder that was requested from it; for example,
as would be for calling `FileChooser::set_current_folder_uri` on a
nonexistent folder.
<!-- trait FileChooserExt::fn get_current_name -->
Gets the current name in the file selector, as entered by the user in the
text entry for “Name”.

This is meant to be used in save dialogs, to get the currently typed filename
when the file itself does not exist yet. For example, an application that
adds a custom extra widget to the file chooser for “file format” may want to
change the extension of the typed filename based on the chosen format, say,
from “.jpg” to “.png”.

# Returns

The raw text from the file chooser’s “Name” entry. Free this with
`g_free`. Note that this string is not a full pathname or URI; it is
whatever the contents of the entry are. Note also that this string is in
UTF-8 encoding, which is not necessarily the system’s encoding for filenames.
<!-- trait FileChooserExt::fn get_do_overwrite_confirmation -->
Queries whether a file chooser is set to confirm for overwriting when the user
types a file name that already exists.

# Returns

`true` if the file chooser will present a confirmation dialog;
`false` otherwise.
<!-- trait FileChooserExt::fn get_extra_widget -->
Gets the current extra widget; see
`FileChooser::set_extra_widget`.

# Returns

the current extra widget, or `None`
<!-- trait FileChooserExt::fn get_file -->
Gets the `gio::File` for the currently selected file in
the file selector. If multiple files are selected,
one of the files will be returned at random.

If the file chooser is in folder mode, this function returns the selected
folder.

# Returns

a selected `gio::File`. You own the returned file;
 use `gobject::ObjectExt::unref` to release it.
<!-- trait FileChooserExt::fn get_filename -->
Gets the filename for the currently selected file in
the file selector. The filename is returned as an absolute path. If
multiple files are selected, one of the filenames will be returned at
random.

If the file chooser is in folder mode, this function returns the selected
folder.

# Returns

The currently selected filename,
 or `None` if no file is selected, or the selected file can't
 be represented with a local filename. Free with `g_free`.
<!-- trait FileChooserExt::fn get_filenames -->
Lists all the selected files and subfolders in the current folder of
`self`. The returned names are full absolute paths. If files in the current
folder cannot be represented as local filenames they will be ignored. (See
`FileChooser::get_uris`)

# Returns

a `glib::SList`
 containing the filenames of all selected files and subfolders in
 the current folder. Free the returned list with `glib::SList::free`,
 and the filenames with `g_free`.
<!-- trait FileChooserExt::fn get_files -->
Lists all the selected files and subfolders in the current folder of `self`
as `gio::File`. An internal function, see `FileChooser::get_uris`.

# Returns

a `glib::SList`
 containing a `gio::File` for each selected file and subfolder in the
 current folder. Free the returned list with `glib::SList::free`, and
 the files with `gobject::ObjectExt::unref`.
<!-- trait FileChooserExt::fn get_filter -->
Gets the current filter; see `FileChooser::set_filter`.

# Returns

the current filter, or `None`
<!-- trait FileChooserExt::fn get_local_only -->
Gets whether only local files can be selected in the
file selector. See `FileChooser::set_local_only`

# Returns

`true` if only local files can be selected.
<!-- trait FileChooserExt::fn get_preview_file -->
Gets the `gio::File` that should be previewed in a custom preview
Internal function, see `FileChooser::get_preview_uri`.

# Returns

the `gio::File` for the file to preview,
 or `None` if no file is selected. Free with `gobject::ObjectExt::unref`.
<!-- trait FileChooserExt::fn get_preview_filename -->
Gets the filename that should be previewed in a custom preview
widget. See `FileChooser::set_preview_widget`.

# Returns

the filename to preview, or `None` if
 no file is selected, or if the selected file cannot be represented
 as a local filename. Free with `g_free`
<!-- trait FileChooserExt::fn get_preview_uri -->
Gets the URI that should be previewed in a custom preview
widget. See `FileChooser::set_preview_widget`.

# Returns

the URI for the file to preview,
 or `None` if no file is selected. Free with `g_free`.
<!-- trait FileChooserExt::fn get_preview_widget -->
Gets the current preview widget; see
`FileChooser::set_preview_widget`.

# Returns

the current preview widget, or `None`
<!-- trait FileChooserExt::fn get_preview_widget_active -->
Gets whether the preview widget set by `FileChooser::set_preview_widget`
should be shown for the current filename. See
`FileChooser::set_preview_widget_active`.

# Returns

`true` if the preview widget is active for the current filename.
<!-- trait FileChooserExt::fn get_select_multiple -->
Gets whether multiple files can be selected in the file
selector. See `FileChooser::set_select_multiple`.

# Returns

`true` if multiple files can be selected.
<!-- trait FileChooserExt::fn get_show_hidden -->
Gets whether hidden files and folders are displayed in the file selector.
See `FileChooser::set_show_hidden`.

# Returns

`true` if hidden files and folders are displayed.
<!-- trait FileChooserExt::fn get_uri -->
Gets the URI for the currently selected file in
the file selector. If multiple files are selected,
one of the filenames will be returned at random.

If the file chooser is in folder mode, this function returns the selected
folder.

# Returns

The currently selected URI, or `None`
 if no file is selected. If `FileChooser::set_local_only` is set to
 `true` (the default) a local URI will be returned for any FUSE locations.
 Free with `g_free`
<!-- trait FileChooserExt::fn get_uris -->
Lists all the selected files and subfolders in the current folder of
`self`. The returned names are full absolute URIs.

# Returns

a `glib::SList` containing the URIs of all selected
 files and subfolders in the current folder. Free the returned list
 with `glib::SList::free`, and the filenames with `g_free`.
<!-- trait FileChooserExt::fn get_use_preview_label -->
Gets whether a stock label should be drawn with the name of the previewed
file. See `FileChooser::set_use_preview_label`.

# Returns

`true` if the file chooser is set to display a label with the
name of the previewed file, `false` otherwise.
<!-- trait FileChooserExt::fn list_filters -->
Lists the current set of user-selectable filters; see
`FileChooser::add_filter`, `FileChooser::remove_filter`.

# Returns

a
 `glib::SList` containing the current set of user selectable filters. The
 contents of the list are owned by GTK+, but you must free the list
 itself with `glib::SList::free` when you are done with it.
<!-- trait FileChooserExt::fn list_shortcut_folder_uris -->
Queries the list of shortcut folders in the file chooser, as set by
`FileChooser::add_shortcut_folder_uri`.

# Returns

A list of
folder URIs, or `None` if there are no shortcut folders. Free the
returned list with `glib::SList::free`, and the URIs with `g_free`.
<!-- trait FileChooserExt::fn list_shortcut_folders -->
Queries the list of shortcut folders in the file chooser, as set by
`FileChooser::add_shortcut_folder`.

# Returns

A list
of folder filenames, or `None` if there are no shortcut folders.
Free the returned list with `glib::SList::free`, and the filenames with
`g_free`.
<!-- trait FileChooserExt::fn remove_choice -->
Removes a 'choice' that has been added with `FileChooser::add_choice`.

Feature: `v3_22`

## `id`
the ID of the choice to remove
<!-- trait FileChooserExt::fn remove_filter -->
Removes `filter` from the list of filters that the user can select between.
## `filter`
a `FileFilter`
<!-- trait FileChooserExt::fn remove_shortcut_folder -->
Removes a folder from a file chooser’s list of shortcut folders.
## `folder`
filename of the folder to remove

# Returns

`true` if the operation succeeds, `false` otherwise.
In the latter case, the `error` will be set as appropriate.

See also: `FileChooser::add_shortcut_folder`
<!-- trait FileChooserExt::fn remove_shortcut_folder_uri -->
Removes a folder URI from a file chooser’s list of shortcut folders.
## `uri`
URI of the folder to remove

# Returns

`true` if the operation succeeds, `false` otherwise.
In the latter case, the `error` will be set as appropriate.

See also: `FileChooser::add_shortcut_folder_uri`
<!-- trait FileChooserExt::fn select_all -->
Selects all the files in the current folder of a file chooser.
<!-- trait FileChooserExt::fn select_file -->
Selects the file referred to by `file`. An internal function. See
`_gtk_file_chooser_select_uri`.
## `file`
the file to select

# Returns

Not useful.
<!-- trait FileChooserExt::fn select_filename -->
Selects a filename. If the file name isn’t in the current
folder of `self`, then the current folder of `self` will
be changed to the folder containing `filename`.
## `filename`
the filename to select

# Returns

Not useful.

See also: `FileChooser::set_filename`
<!-- trait FileChooserExt::fn select_uri -->
Selects the file to by `uri`. If the URI doesn’t refer to a
file in the current folder of `self`, then the current folder of
`self` will be changed to the folder containing `filename`.
## `uri`
the URI to select

# Returns

Not useful.
<!-- trait FileChooserExt::fn set_action -->
Sets the type of operation that the chooser is performing; the
user interface is adapted to suit the selected action. For example,
an option to create a new folder might be shown if the action is
`FileChooserAction::Save` but not if the action is
`FileChooserAction::Open`.
## `action`
the action that the file selector is performing
<!-- trait FileChooserExt::fn set_choice -->
Selects an option in a 'choice' that has been added with
`FileChooser::add_choice`. For a boolean choice, the
possible options are "true" and "false".

Feature: `v3_22`

## `id`
the ID of the choice to set
## `option`
the ID of the option to select
<!-- trait FileChooserExt::fn set_create_folders -->
Sets whether file choser will offer to create new folders.
This is only relevant if the action is not set to be
`FileChooserAction::Open`.
## `create_folders`
`true` if the Create Folder button should be displayed
<!-- trait FileChooserExt::fn set_current_folder -->
Sets the current folder for `self` from a local filename.
The user will be shown the full contents of the current folder,
plus user interface elements for navigating to other folders.

In general, you should not use this function. See the
[section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up]
for the rationale behind this.
## `filename`
the full path of the new current folder

# Returns

Not useful.
<!-- trait FileChooserExt::fn set_current_folder_file -->
Sets the current folder for `self` from a `gio::File`.
Internal function, see `FileChooser::set_current_folder_uri`.
## `file`
the `gio::File` for the new folder

# Returns

`true` if the folder could be changed successfully, `false`
otherwise.
<!-- trait FileChooserExt::fn set_current_folder_uri -->
Sets the current folder for `self` from an URI.
The user will be shown the full contents of the current folder,
plus user interface elements for navigating to other folders.

In general, you should not use this function. See the
[section on setting up a file chooser dialog][gtkfilechooserdialog-setting-up]
for the rationale behind this.
## `uri`
the URI for the new current folder

# Returns

`true` if the folder could be changed successfully, `false`
otherwise.
<!-- trait FileChooserExt::fn set_current_name -->
Sets the current name in the file selector, as if entered
by the user. Note that the name passed in here is a UTF-8
string rather than a filename. This function is meant for
such uses as a suggested name in a “Save As...” dialog. You can
pass “Untitled.doc” or a similarly suitable suggestion for the `name`.

If you want to preselect a particular existing file, you should use
`FileChooser::set_filename` or `FileChooser::set_uri` instead.
Please see the documentation for those functions for an example of using
`FileChooser::set_current_name` as well.
## `name`
the filename to use, as a UTF-8 string
<!-- trait FileChooserExt::fn set_do_overwrite_confirmation -->
Sets whether a file chooser in `FileChooserAction::Save` mode will present
a confirmation dialog if the user types a file name that already exists. This
is `false` by default.

If set to `true`, the `self` will emit the
`FileChooser::confirm-overwrite` signal when appropriate.

If all you need is the stock confirmation dialog, set this property to `true`.
You can override the way confirmation is done by actually handling the
`FileChooser::confirm-overwrite` signal; please refer to its documentation
for the details.
## `do_overwrite_confirmation`
whether to confirm overwriting in save mode
<!-- trait FileChooserExt::fn set_extra_widget -->
Sets an application-supplied widget to provide extra options to the user.
## `extra_widget`
widget for extra options
<!-- trait FileChooserExt::fn set_file -->
Sets `file` as the current filename for the file chooser, by changing
to the file’s parent folder and actually selecting the file in list. If
the `self` is in `FileChooserAction::Save` mode, the file’s base name
will also appear in the dialog’s file name entry.

If the file name isn’t in the current folder of `self`, then the current
folder of `self` will be changed to the folder containing `filename`. This
is equivalent to a sequence of `FileChooser::unselect_all` followed by
`FileChooser::select_filename`.

Note that the file must exist, or nothing will be done except
for the directory change.

If you are implementing a save dialog,
you should use this function if you already have a file name to which the
user may save; for example, when the user opens an existing file and then
does Save As... If you don’t have
a file name already — for example, if the user just created a new
file and is saving it for the first time, do not call this function.
Instead, use something similar to this:

```C
if (document_is_new)
  {
    // the user just created a new document
    gtk_file_chooser_set_current_folder_file (chooser, default_file_for_saving);
    gtk_file_chooser_set_current_name (chooser, "Untitled document");
  }
else
  {
    // the user edited an existing document
    gtk_file_chooser_set_file (chooser, existing_file);
  }
```
## `file`
the `gio::File` to set as current

# Returns

Not useful.
<!-- trait FileChooserExt::fn set_filename -->
Sets `filename` as the current filename for the file chooser, by changing to
the file’s parent folder and actually selecting the file in list; all other
files will be unselected. If the `self` is in
`FileChooserAction::Save` mode, the file’s base name will also appear in
the dialog’s file name entry.

Note that the file must exist, or nothing will be done except
for the directory change.

You should use this function only when implementing a save
dialog for which you already have a file name to which
the user may save. For example, when the user opens an existing file and
then does Save As... to save a copy or
a modified version. If you don’t have a file name already — for
example, if the user just created a new file and is saving it for the first
time, do not call this function. Instead, use something similar to this:

```C
if (document_is_new)
  {
    // the user just created a new document
    gtk_file_chooser_set_current_name (chooser, "Untitled document");
  }
else
  {
    // the user edited an existing document
    gtk_file_chooser_set_filename (chooser, existing_filename);
  }
```

In the first case, the file chooser will present the user with useful suggestions
as to where to save his new file. In the second case, the file’s existing location
is already known, so the file chooser will use it.
## `filename`
the filename to set as current

# Returns

Not useful.
<!-- trait FileChooserExt::fn set_filter -->
Sets the current filter; only the files that pass the
filter will be displayed. If the user-selectable list of filters
is non-empty, then the filter should be one of the filters
in that list. Setting the current filter when the list of
filters is empty is useful if you want to restrict the displayed
set of files without letting the user change it.
## `filter`
a `FileFilter`
<!-- trait FileChooserExt::fn set_local_only -->
Sets whether only local files can be selected in the
file selector. If `local_only` is `true` (the default),
then the selected file or files are guaranteed to be
accessible through the operating systems native file
system and therefore the application only
needs to worry about the filename functions in
`FileChooser`, like `FileChooser::get_filename`,
rather than the URI functions like
`FileChooser::get_uri`,

On some systems non-native files may still be
available using the native filesystem via a userspace
filesystem (FUSE).
## `local_only`
`true` if only local files can be selected
<!-- trait FileChooserExt::fn set_preview_widget -->
Sets an application-supplied widget to use to display a custom preview
of the currently selected file. To implement a preview, after setting the
preview widget, you connect to the `FileChooser::update-preview`
signal, and call `FileChooser::get_preview_filename` or
`FileChooser::get_preview_uri` on each change. If you can
display a preview of the new file, update your widget and
set the preview active using `FileChooser::set_preview_widget_active`.
Otherwise, set the preview inactive.

When there is no application-supplied preview widget, or the
application-supplied preview widget is not active, the file chooser
will display no preview at all.
## `preview_widget`
widget for displaying preview.
<!-- trait FileChooserExt::fn set_preview_widget_active -->
Sets whether the preview widget set by
`FileChooser::set_preview_widget` should be shown for the
current filename. When `active` is set to false, the file chooser
may display an internally generated preview of the current file
or it may display no preview at all. See
`FileChooser::set_preview_widget` for more details.
## `active`
whether to display the user-specified preview widget
<!-- trait FileChooserExt::fn set_select_multiple -->
Sets whether multiple files can be selected in the file selector. This is
only relevant if the action is set to be `FileChooserAction::Open` or
`FileChooserAction::SelectFolder`.
## `select_multiple`
`true` if multiple files can be selected.
<!-- trait FileChooserExt::fn set_show_hidden -->
Sets whether hidden files and folders are displayed in the file selector.
## `show_hidden`
`true` if hidden files and folders should be displayed.
<!-- trait FileChooserExt::fn set_uri -->
Sets the file referred to by `uri` as the current file for the file chooser,
by changing to the URI’s parent folder and actually selecting the URI in the
list. If the `self` is `FileChooserAction::Save` mode, the URI’s base
name will also appear in the dialog’s file name entry.

Note that the URI must exist, or nothing will be done except for the
directory change.

You should use this function only when implementing a save
dialog for which you already have a file name to which
the user may save. For example, when the user opens an existing file and then
does Save As... to save a copy or a
modified version. If you don’t have a file name already — for example,
if the user just created a new file and is saving it for the first time, do
not call this function. Instead, use something similar to this:

```C
if (document_is_new)
  {
    // the user just created a new document
    gtk_file_chooser_set_current_name (chooser, "Untitled document");
  }
else
  {
    // the user edited an existing document
    gtk_file_chooser_set_uri (chooser, existing_uri);
  }
```


In the first case, the file chooser will present the user with useful suggestions
as to where to save his new file. In the second case, the file’s existing location
is already known, so the file chooser will use it.
## `uri`
the URI to set as current

# Returns

Not useful.
<!-- trait FileChooserExt::fn set_use_preview_label -->
Sets whether the file chooser should display a stock label with the name of
the file that is being previewed; the default is `true`. Applications that
want to draw the whole preview area themselves should set this to `false` and
display the name themselves in their preview widget.

See also: `FileChooser::set_preview_widget`
## `use_label`
whether to display a stock label with the name of the previewed file
<!-- trait FileChooserExt::fn unselect_all -->
Unselects all the files in the current folder of a file chooser.
<!-- trait FileChooserExt::fn unselect_file -->
Unselects the file referred to by `file`. If the file is not in the current
directory, does not exist, or is otherwise not currently selected, does nothing.
## `file`
a `gio::File`
<!-- trait FileChooserExt::fn unselect_filename -->
Unselects a currently selected filename. If the filename
is not in the current directory, does not exist, or
is otherwise not currently selected, does nothing.
## `filename`
the filename to unselect
<!-- trait FileChooserExt::fn unselect_uri -->
Unselects the file referred to by `uri`. If the file
is not in the current directory, does not exist, or
is otherwise not currently selected, does nothing.
## `uri`
the URI to unselect
<!-- trait FileChooserExt::fn connect_confirm_overwrite -->
This signal gets emitted whenever it is appropriate to present a
confirmation dialog when the user has selected a file name that
already exists. The signal only gets emitted when the file
chooser is in `FileChooserAction::Save` mode.

Most applications just need to turn on the
`FileChooser:do-overwrite-confirmation` property (or call the
`FileChooser::set_do_overwrite_confirmation` function), and
they will automatically get a stock confirmation dialog.
Applications which need to customize this behavior should do
that, and also connect to the `FileChooser::confirm-overwrite`
signal.

A signal handler for this signal must return a
`FileChooserConfirmation` value, which indicates the action to
take. If the handler determines that the user wants to select a
different filename, it should return
`FileChooserConfirmation::SelectAgain`. If it determines
that the user is satisfied with his choice of file name, it
should return `FileChooserConfirmation::AcceptFilename`.
On the other hand, if it determines that the stock confirmation
dialog should be used, it should return
`FileChooserConfirmation::Confirm`. The following example
illustrates this.

## Custom confirmation ## {`gtkfilechooser`-confirmation}


```C
static GtkFileChooserConfirmation
confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
{
  char *uri;

  uri = gtk_file_chooser_get_uri (chooser);

  if (is_uri_read_only (uri))
    {
      if (user_wants_to_replace_read_only_file (uri))
        return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
      else
        return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
    } else
      return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; // fall back to the default dialog
}

...

chooser = gtk_file_chooser_dialog_new (...);

gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
g_signal_connect (chooser, "confirm-overwrite",
                  G_CALLBACK (confirm_overwrite_callback), NULL);

if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
        save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));

gtk_widget_destroy (chooser);
```

# Returns

a `FileChooserConfirmation` value that indicates which
 action to take after emitting the signal.
<!-- trait FileChooserExt::fn connect_current_folder_changed -->
This signal is emitted when the current folder in a `FileChooser`
changes. This can happen due to the user performing some action that
changes folders, such as selecting a bookmark or visiting a folder on the
file list. It can also happen as a result of calling a function to
explicitly change the current folder in a file chooser.

Normally you do not need to connect to this signal, unless you need to keep
track of which folder a file chooser is showing.

See also: `FileChooser::set_current_folder`,
`FileChooser::get_current_folder`,
`FileChooser::set_current_folder_uri`,
`FileChooser::get_current_folder_uri`.
<!-- trait FileChooserExt::fn connect_file_activated -->
This signal is emitted when the user "activates" a file in the file
chooser. This can happen by double-clicking on a file in the file list, or
by pressing `Enter`.

Normally you do not need to connect to this signal. It is used internally
by `FileChooserDialog` to know when to activate the default button in the
dialog.

See also: `FileChooser::get_filename`,
`FileChooser::get_filenames`, `FileChooser::get_uri`,
`FileChooser::get_uris`.
<!-- trait FileChooserExt::fn connect_selection_changed -->
This signal is emitted when there is a change in the set of selected files
in a `FileChooser`. This can happen when the user modifies the selection
with the mouse or the keyboard, or when explicitly calling functions to
change the selection.

Normally you do not need to connect to this signal, as it is easier to wait
for the file chooser to finish running, and then to get the list of
selected files using the functions mentioned below.

See also: `FileChooser::select_filename`,
`FileChooser::unselect_filename`, `FileChooser::get_filename`,
`FileChooser::get_filenames`, `FileChooser::select_uri`,
`FileChooser::unselect_uri`, `FileChooser::get_uri`,
`FileChooser::get_uris`.
<!-- trait FileChooserExt::fn connect_update_preview -->
This signal is emitted when the preview in a file chooser should be
regenerated. For example, this can happen when the currently selected file
changes. You should use this signal if you want your file chooser to have
a preview widget.

Once you have installed a preview widget with
`FileChooser::set_preview_widget`, you should update it when this
signal is emitted. You can use the functions
`FileChooser::get_preview_filename` or
`FileChooser::get_preview_uri` to get the name of the file to preview.
Your widget may not be able to preview all kinds of files; your callback
must call `FileChooser::set_preview_widget_active` to inform the file
chooser about whether the preview was generated successfully or not.

Please see the example code in
[Using a Preview Widget][gtkfilechooser-preview].

See also: `FileChooser::set_preview_widget`,
`FileChooser::set_preview_widget_active`,
`FileChooser::set_use_preview_label`,
`FileChooser::get_preview_filename`,
`FileChooser::get_preview_uri`.
<!-- trait FileChooserExt::fn get_property_create_folders -->
Whether a file chooser not in `FileChooserAction::Open` mode
will offer the user to create new folders.
<!-- trait FileChooserExt::fn set_property_create_folders -->
Whether a file chooser not in `FileChooserAction::Open` mode
will offer the user to create new folders.
<!-- trait FileChooserExt::fn get_property_do_overwrite_confirmation -->
Whether a file chooser in `FileChooserAction::Save` mode
will present an overwrite confirmation dialog if the user
selects a file name that already exists.
<!-- trait FileChooserExt::fn set_property_do_overwrite_confirmation -->
Whether a file chooser in `FileChooserAction::Save` mode
will present an overwrite confirmation dialog if the user
selects a file name that already exists.
<!-- enum FileChooserAction -->
Describes whether a `FileChooser` is being used to open existing files
or to save to a possibly new file.
<!-- enum FileChooserAction::variant Open -->
Indicates open mode. The file chooser
 will only let the user pick an existing file.
<!-- enum FileChooserAction::variant Save -->
Indicates save mode. The file chooser
 will let the user pick an existing file, or type in a new
 filename.
<!-- enum FileChooserAction::variant SelectFolder -->
Indicates an Open mode for
 selecting folders. The file chooser will let the user pick an
 existing folder.
<!-- enum FileChooserAction::variant CreateFolder -->
Indicates a mode for creating a
 new folder. The file chooser will let the user name an existing or
 new folder.
<!-- struct FileChooserButton -->
The `FileChooserButton` is a widget that lets the user select a
file. It implements the `FileChooser` interface. Visually, it is a
file name with a button to bring up a `FileChooserDialog`.
The user can then use that dialog to change the file associated with
that button. This widget does not support setting the
`FileChooser:select-multiple` property to `true`.

## Create a button to let the user select a file in /etc


```C
{
  GtkWidget *button;

  button = gtk_file_chooser_button_new (_("Select a file"),
                                        GTK_FILE_CHOOSER_ACTION_OPEN);
  gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button),
                                       "/etc");
}
```

The `FileChooserButton` supports the ``GtkFileChooserActions``
`FileChooserAction::Open` and `FileChooserAction::SelectFolder`.

> The `FileChooserButton` will ellipsize the label, and will thus
> request little horizontal space. To give the button more space,
> you should call `WidgetExt::get_preferred_size`,
> `FileChooserButtonExt::set_width_chars`, or pack the button in
> such a way that other interface elements give space to the
> widget.

# CSS nodes

`FileChooserButton` has a CSS node with name “filechooserbutton”, containing
a subnode for the internal button with name “button” and style class “.file”.

# Implements

[`FileChooserButtonExt`](trait.FileChooserButtonExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`FileChooserExt`](trait.FileChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FileChooserButtonExt -->
Trait containing all `FileChooserButton` methods.

# Implementors

[`FileChooserButton`](struct.FileChooserButton.html)
<!-- impl FileChooserButton::fn new -->
Creates a new file-selecting button widget.
## `title`
the title of the browse dialog.
## `action`
the open mode for the widget.

# Returns

a new button widget.
<!-- impl FileChooserButton::fn new_with_dialog -->
Creates a `FileChooserButton` widget which uses `dialog` as its
file-picking window.

Note that `dialog` must be a `Dialog` (or subclass) which
implements the `FileChooser` interface and must not have
`DialogFlags::DestroyWithParent` set.

Also note that the dialog needs to have its confirmative button
added with response `ResponseType::Accept` or `ResponseType::Ok` in
order for the button to take over the file selected in the dialog.
## `dialog`
the widget to use as dialog

# Returns

a new button widget.
<!-- trait FileChooserButtonExt::fn get_focus_on_click -->
Returns whether the button grabs focus when it is clicked with the mouse.
See `FileChooserButtonExt::set_focus_on_click`.

# Deprecated since 3.20

Use `WidgetExt::get_focus_on_click` instead

# Returns

`true` if the button grabs focus when it is clicked with
 the mouse.
<!-- trait FileChooserButtonExt::fn get_title -->
Retrieves the title of the browse dialog used by `self`. The returned value
should not be modified or freed.

# Returns

a pointer to the browse dialog’s title.
<!-- trait FileChooserButtonExt::fn get_width_chars -->
Retrieves the width in characters of the `self` widget’s entry and/or label.

# Returns

an integer width (in characters) that the button will use to size itself.
<!-- trait FileChooserButtonExt::fn set_focus_on_click -->
Sets whether the button will 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.

# Deprecated since 3.20

Use `WidgetExt::set_focus_on_click` instead
## `focus_on_click`
whether the button grabs focus when clicked with the mouse
<!-- trait FileChooserButtonExt::fn set_title -->
Modifies the `title` of the browse dialog used by `self`.
## `title`
the new browse dialog title.
<!-- trait FileChooserButtonExt::fn set_width_chars -->
Sets the width (in characters) that `self` will use to `n_chars`.
## `n_chars`
the new width, in characters.
<!-- trait FileChooserButtonExt::fn connect_file_set -->
The ::file-set signal is emitted when the user selects a file.

Note that this signal is only emitted when the user
changes the file.
<!-- trait FileChooserButtonExt::fn set_property_dialog -->
Instance of the `FileChooserDialog` associated with the button.
<!-- trait FileChooserButtonExt::fn get_property_title -->
Title to put on the `FileChooserDialog` associated with the button.
<!-- trait FileChooserButtonExt::fn set_property_title -->
Title to put on the `FileChooserDialog` associated with the button.
<!-- trait FileChooserButtonExt::fn get_property_width_chars -->
The width of the entry and label inside the button, in characters.
<!-- trait FileChooserButtonExt::fn set_property_width_chars -->
The width of the entry and label inside the button, in characters.
<!-- enum FileChooserConfirmation -->
Used as a return value of handlers for the
`FileChooser::confirm-overwrite` signal of a `FileChooser`. This
value determines whether the file chooser will present the stock
confirmation dialog, accept the user’s choice of a filename, or
let the user choose another filename.
<!-- enum FileChooserConfirmation::variant Confirm -->
The file chooser will present
 its stock dialog to confirm about overwriting an existing file.
<!-- enum FileChooserConfirmation::variant AcceptFilename -->
The file chooser will
 terminate and accept the user’s choice of a file name.
<!-- enum FileChooserConfirmation::variant SelectAgain -->
The file chooser will
 continue running, so as to let the user select another file name.
<!-- struct FileChooserDialog -->
`FileChooserDialog` is a dialog box suitable for use with
“File/Open” or “File/Save as” commands. This widget works by
putting a `FileChooserWidget` inside a `Dialog`. It exposes
the `FileChooser` interface, so you can use all of the
`FileChooser` functions on the file chooser dialog as well as
those for `Dialog`.

Note that `FileChooserDialog` does not have any methods of its
own. Instead, you should use the functions that work on a
`FileChooser`.

If you want to integrate well with the platform you should use the
`FileChooserNative` API, which will use a platform-specific
dialog if available and fall back to `FileChooserDialog`
otherwise.

## Typical usage ## {`gtkfilechooser`-typical-usage}

In the simplest of cases, you can the following code to use
`FileChooserDialog` to select a file for opening:


```text
GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

gtk_widget_destroy (dialog);
```

To use a dialog for saving, you can use this:


```text
GtkWidget *dialog;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

dialog = gtk_file_chooser_dialog_new ("Save File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Save"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);
chooser = GTK_FILE_CHOOSER (dialog);

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

if (user_edited_a_new_document)
  gtk_file_chooser_set_current_name (chooser,
                                     _("Untitled document"));
else
  gtk_file_chooser_set_filename (chooser,
                                 existing_filename);

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

gtk_widget_destroy (dialog);
```

## Setting up a file chooser dialog ## {`gtkfilechooserdialog`-setting-up}

There are various cases in which you may need to use a `FileChooserDialog`:

- To select a file for opening. Use `FileChooserAction::Open`.

- To save a file for the first time. Use `FileChooserAction::Save`,
 and suggest a name such as “Untitled” with `FileChooser::set_current_name`.

- To save a file under a different name. Use `FileChooserAction::Save`,
 and set the existing filename with `FileChooser::set_filename`.

- To choose a folder instead of a file. Use `FileChooserAction::SelectFolder`.

Note that old versions of the file chooser’s documentation suggested
using `FileChooser::set_current_folder` in various
situations, with the intention of letting the application
suggest a reasonable default folder. This is no longer
considered to be a good policy, as now the file chooser is
able to make good suggestions on its own. In general, you
should only cause the file chooser to show a specific folder
when it is appropriate to use `FileChooser::set_filename`,
i.e. when you are doing a Save As command and you already
have a file saved somewhere.

## Response Codes ## {`gtkfilechooserdialog`-responses}

`FileChooserDialog` inherits from `Dialog`, so buttons that
go in its action area have response codes such as
`ResponseType::Accept` and `ResponseType::Cancel`. For example, you
could call `FileChooserDialog::new` as follows:


```text
GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);
```

This will create buttons for “Cancel” and “Open” that use stock
response identifiers from `ResponseType`. For most dialog
boxes you can use your own custom response codes rather than the
ones in `ResponseType`, but `FileChooserDialog` assumes that
its “accept”-type action, e.g. an “Open” or “Save” button,
will have one of the following response codes:

- `ResponseType::Accept`
- `ResponseType::Ok`
- `ResponseType::Yes`
- `ResponseType::Apply`

This is because `FileChooserDialog` must intercept responses
and switch to folders if appropriate, rather than letting the
dialog terminate — the implementation uses these known
response codes to know which responses can be blocked if
appropriate.

To summarize, make sure you use a
[stock response code][gtkfilechooserdialog-responses]
when you use `FileChooserDialog` to ensure proper operation.

# Implements

[`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`FileChooserExt`](trait.FileChooserExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl FileChooserDialog::fn new -->
Creates a new `FileChooserDialog`. This function is analogous to
`Dialog::new_with_buttons`.
## `title`
Title of the dialog, or `None`
## `parent`
Transient parent of the dialog, or `None`
## `action`
Open or save mode for the dialog
## `first_button_text`
stock ID or text to go in the first button, or `None`

# Returns

a new `FileChooserDialog`
<!-- enum FileChooserError -->
These identify the various errors that can occur while calling
`FileChooser` functions.
<!-- enum FileChooserError::variant Nonexistent -->
Indicates that a file does not exist.
<!-- enum FileChooserError::variant BadFilename -->
Indicates a malformed filename.
<!-- enum FileChooserError::variant AlreadyExists -->
Indicates a duplicate path (e.g. when
 adding a bookmark).
<!-- enum FileChooserError::variant IncompleteHostname -->
Indicates an incomplete hostname (e.g. "http://foo" without a slash after that).
<!-- struct FileChooserNative -->
`FileChooserNative` is an abstraction of a dialog box suitable
for use with “File/Open” or “File/Save as” commands. By default, this
just uses a `FileChooserDialog` to implement the actual dialog.
However, on certain platforms, such as Windows and macOS, the native platform
file chooser is used instead. When the application is running in a
sandboxed environment without direct filesystem access (such as Flatpak),
`FileChooserNative` may call the proper APIs (portals) to let the user
choose a file and make it available to the application.

While the API of `FileChooserNative` closely mirrors `FileChooserDialog`, the main
difference is that there is no access to any `Window` or `Widget` for the dialog.
This is required, as there may not be one in the case of a platform native dialog.
Showing, hiding and running the dialog is handled by the `NativeDialog` functions.

## Typical usage ## {`gtkfilechoosernative`-typical-usage}

In the simplest of cases, you can the following code to use
`FileChooserDialog` to select a file for opening:


```text
GtkFileChooserNative *native;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

native = gtk_file_chooser_native_new ("Open File",
                                      parent_window,
                                      action,
                                      "_Open",
                                      "_Cancel");

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

g_object_unref (native);
```

To use a dialog for saving, you can use this:


```text
GtkFileChooserNative *native;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

native = gtk_file_chooser_native_new ("Save File",
                                      parent_window,
                                      action,
                                      "_Save",
                                      "_Cancel");
chooser = GTK_FILE_CHOOSER (native);

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

if (user_edited_a_new_document)
  gtk_file_chooser_set_current_name (chooser,
                                     _("Untitled document"));
else
  gtk_file_chooser_set_filename (chooser,
                                 existing_filename);

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

g_object_unref (native);
```

For more information on how to best set up a file dialog, see `FileChooserDialog`.

## Response Codes ## {`gtkfilechooserdialognative`-responses}

`FileChooserNative` inherits from `NativeDialog`, which means it
will return `ResponseType::Accept` if the user accepted, and
`ResponseType::Cancel` if he pressed cancel. It can also return
`ResponseType::DeleteEvent` if the window was unexpectedly closed.

## Differences from `FileChooserDialog` ## {`gtkfilechooserdialognative`-differences}

There are a few things in the `FileChooser` API that are not
possible to use with `FileChooserNative`, as such use would
prohibit the use of a native dialog.

There is no support for the signals that are emitted when the user
navigates in the dialog, including:
* `FileChooser::current-folder-changed`
* `FileChooser::selection-changed`
* `FileChooser::file-activated`
* `FileChooser::confirm-overwrite`

You can also not use the methods that directly control user navigation:
* `FileChooser::unselect_filename`
* `FileChooser::select_all`
* `FileChooser::unselect_all`

If you need any of the above you will have to use `FileChooserDialog` directly.

No operations that change the the dialog work while the dialog is
visible. Set all the properties that are required before showing the dialog.

## Win32 details ## {`gtkfilechooserdialognative`-win32}

On windows the IFileDialog implementation (added in Windows Vista) is
used. It supports many of the features that `FileChooserDialog`
does, but there are some things it does not handle:

* Extra widgets added with `FileChooser::set_extra_widget`.

* Use of custom previews by connecting to `FileChooser::update-preview`.

* Any `FileFilter` added using a mimetype or custom filter.

If any of these features are used the regular `FileChooserDialog`
will be used in place of the native one.

## Portal details ## {`gtkfilechooserdialognative`-portal}

When the org.freedesktop.portal.FileChooser portal is available on the
session bus, it is used to bring up an out-of-process file chooser. Depending
on the kind of session the application is running in, this may or may not
be a GTK+ file chooser. In this situation, the following things are not
supported and will be silently ignored:

* Extra widgets added with `FileChooser::set_extra_widget`.

* Use of custom previews by connecting to `FileChooser::update-preview`.

* Any `FileFilter` added with a custom filter.

## macOS details ## {`gtkfilechooserdialognative`-macos}

On macOS the NSSavePanel and NSOpenPanel classes are used to provide native
file chooser dialogs. Some features provided by `FileChooserDialog` are
not supported:

* Extra widgets added with `FileChooser::set_extra_widget`, unless the
 widget is an instance of `Label`, in which case the label text will be used
 to set the NSSavePanel message instance property.

* Use of custom previews by connecting to `FileChooser::update-preview`.

* Any `FileFilter` added with a custom filter.

* Shortcut folders.

Feature: `v3_20`

# Implements

[`FileChooserNativeExt`](trait.FileChooserNativeExt.html), [`NativeDialogExt`](trait.NativeDialogExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`FileChooserExt`](trait.FileChooserExt.html)
<!-- trait FileChooserNativeExt -->
Trait containing all `FileChooserNative` methods.

Feature: `v3_20`

# Implementors

[`FileChooserNative`](struct.FileChooserNative.html)
<!-- impl FileChooserNative::fn new -->
Creates a new `FileChooserNative`.

Feature: `v3_20`

## `title`
Title of the native, or `None`
## `parent`
Transient parent of the native, or `None`
## `action`
Open or save mode for the dialog
## `accept_label`
text to go in the accept button, or `None` for the default
## `cancel_label`
text to go in the cancel button, or `None` for the default

# Returns

a new `FileChooserNative`
<!-- trait FileChooserNativeExt::fn get_accept_label -->
Retrieves the custom label text for the accept button.

Feature: `v3_20`


# Returns

The custom label, or `None` for the default. This string
is owned by GTK+ and should not be modified or freed
<!-- trait FileChooserNativeExt::fn get_cancel_label -->
Retrieves the custom label text for the cancel button.

Feature: `v3_20`


# Returns

The custom label, or `None` for the default. This string
is owned by GTK+ and should not be modified or freed
<!-- trait FileChooserNativeExt::fn set_accept_label -->
Sets the custom label text for the accept button.

If characters in `label` are preceded by an underscore, they are underlined.
If you need a literal underscore character in a label, use “__” (two
underscores). The first underlined character represents a keyboard
accelerator called a mnemonic.
Pressing Alt and that key activates the button.

Feature: `v3_20`

## `accept_label`
custom label or `None` for the default
<!-- trait FileChooserNativeExt::fn set_cancel_label -->
Sets the custom label text for the cancel button.

If characters in `label` are preceded by an underscore, they are underlined.
If you need a literal underscore character in a label, use “__” (two
underscores). The first underlined character represents a keyboard
accelerator called a mnemonic.
Pressing Alt and that key activates the button.

Feature: `v3_20`

## `cancel_label`
custom label or `None` for the default
<!-- trait FileChooserNativeExt::fn get_property_accept_label -->
The text used for the label on the accept button in the dialog, or
`None` to use the default text.
<!-- trait FileChooserNativeExt::fn set_property_accept_label -->
The text used for the label on the accept button in the dialog, or
`None` to use the default text.
<!-- trait FileChooserNativeExt::fn get_property_cancel_label -->
The text used for the label on the cancel button in the dialog, or
`None` to use the default text.
<!-- trait FileChooserNativeExt::fn set_property_cancel_label -->
The text used for the label on the cancel button in the dialog, or
`None` to use the default text.
<!-- struct FileChooserWidget -->
`FileChooserWidget` is a widget for choosing files.
It exposes the `FileChooser` interface, and you should
use the methods of this interface to interact with the
widget.

# CSS nodes

`FileChooserWidget` has a single CSS node with name filechooser.

# Implements

[`FileChooserWidgetExt`](trait.FileChooserWidgetExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`FileChooserExt`](trait.FileChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FileChooserWidgetExt -->
Trait containing all `FileChooserWidget` methods.

# Implementors

[`FileChooserWidget`](struct.FileChooserWidget.html)
<!-- impl FileChooserWidget::fn new -->
Creates a new `FileChooserWidget`. This is a file chooser widget that can
be embedded in custom windows, and it is the same widget that is used by
`FileChooserDialog`.
## `action`
Open or save mode for the widget

# Returns

a new `FileChooserWidget`
<!-- trait FileChooserWidgetExt::fn connect_desktop_folder -->
The ::desktop-folder signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser show the user's Desktop
folder in the file list.

The default binding for this signal is `Alt + D`.
<!-- trait FileChooserWidgetExt::fn connect_down_folder -->
The ::down-folder signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser go to a child of the current folder
in the file hierarchy. The subfolder that will be used is displayed in the
path bar widget of the file chooser. For example, if the path bar is showing
"/foo/bar/baz", with bar currently displayed, then this will cause the file
chooser to switch to the "baz" subfolder.

The default binding for this signal is `Alt + Down`.
<!-- trait FileChooserWidgetExt::fn connect_home_folder -->
The ::home-folder signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser show the user's home
folder in the file list.

The default binding for this signal is `Alt + Home`.
<!-- trait FileChooserWidgetExt::fn connect_location_popup -->
The ::location-popup signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser show a "Location" prompt which
the user can use to manually type the name of the file he wishes to select.

The default bindings for this signal are `Control + L` with a `path` string
of "" (the empty string). It is also bound to `/` with a `path` string of
"`/`" (a slash): this lets you type `/` and immediately type a path name.
On Unix systems, this is bound to `~` (tilde) with a `path` string of "~"
itself for access to home directories.
## `path`
a string that gets put in the text entry for the file name
<!-- trait FileChooserWidgetExt::fn connect_location_popup_on_paste -->
The ::location-popup-on-paste signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser show a "Location" prompt when the user
pastes into a `FileChooserWidget`.

The default binding for this signal is `Control + V`.
<!-- trait FileChooserWidgetExt::fn connect_location_toggle_popup -->
The ::location-toggle-popup signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to toggle the visibility of a "Location" prompt which the user
can use to manually type the name of the file he wishes to select.

The default binding for this signal is `Control + L`.
<!-- trait FileChooserWidgetExt::fn connect_places_shortcut -->
The ::places-shortcut signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to move the focus to the places sidebar.

The default binding for this signal is `Alt + P`.
<!-- trait FileChooserWidgetExt::fn connect_quick_bookmark -->
The ::quick-bookmark signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser switch to the bookmark specified
in the `bookmark_index` parameter. For example, if you have three bookmarks,
you can pass 0, 1, 2 to this signal to switch to each of them, respectively.

The default binding for this signal is `Alt + 1`, `Alt + 2`,
etc. until `Alt + 0`. Note that in the default binding, that
`Alt + 1` is actually defined to switch to the bookmark at index
0, and so on successively; `Alt + 0` is defined to switch to the
bookmark at index 10.
## `bookmark_index`
the number of the bookmark to switch to
<!-- trait FileChooserWidgetExt::fn connect_recent_shortcut -->
The ::recent-shortcut signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser show the Recent location.

The default binding for this signal is `Alt + R`.
<!-- trait FileChooserWidgetExt::fn connect_search_shortcut -->
The ::search-shortcut signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser show the search entry.

The default binding for this signal is `Alt + S`.
<!-- trait FileChooserWidgetExt::fn connect_show_hidden -->
The ::show-hidden signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser display hidden files.

The default binding for this signal is `Control + H`.
<!-- trait FileChooserWidgetExt::fn connect_up_folder -->
The ::up-folder signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

This is used to make the file chooser go to the parent of the current folder
in the file hierarchy.

The default binding for this signal is `Alt + Up`.
<!-- struct FileFilter -->
A `FileFilter` can be used to restrict the files being shown in a
`FileChooser`. Files can be filtered based on their name (with
`FileFilter::add_pattern`), on their mime type (with
`FileFilter::add_mime_type`), or by a custom filter function
(with `FileFilter::add_custom`).

Filtering by mime types handles aliasing and subclassing of mime
types; e.g. a filter for text/plain also matches a file with mime
type application/rtf, since application/rtf is a subclass of
text/plain. Note that `FileFilter` allows wildcards for the
subtype of a mime type, so you can e.g. filter for image/\*.

Normally, filters are used by adding them to a `FileChooser`,
see `FileChooser::add_filter`, but it is also possible
to manually use a filter on a file with `FileFilter::filter`.

# `FileFilter` as `Buildable`

The `FileFilter` implementation of the `Buildable` interface
supports adding rules using the `<mime-types>`, `<patterns>` and
`<applications>` elements and listing the rules within. Specifying
a `<mime-type>` or `<pattern>` has the same effect as as calling
`FileFilter::add_mime_type` or `FileFilter::add_pattern`.

An example of a UI definition fragment specifying `FileFilter`
rules:

```text
<object class="GtkFileFilter">
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/ *</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
    <pattern>*.png</pattern>
  </patterns>
</object>
```

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl FileFilter::fn new -->
Creates a new `FileFilter` with no rules added to it.
Such a filter doesn’t accept any files, so is not
particularly useful until you add rules with
`FileFilter::add_mime_type`, `FileFilter::add_pattern`,
or `FileFilter::add_custom`. To create a filter
that accepts any file, use:

```C
GtkFileFilter *filter = gtk_file_filter_new ();
gtk_file_filter_add_pattern (filter, "*");
```

# Returns

a new `FileFilter`
<!-- impl FileFilter::fn new_from_gvariant -->
Deserialize a file filter from an a{sv} variant in
the format produced by `FileFilter::to_gvariant`.

Feature: `v3_22`

## `variant`
an a{sv} `glib::Variant`

# Returns

a new `FileFilter` object
<!-- impl FileFilter::fn add_custom -->
Adds rule to a filter that allows files based on a custom callback
function. The bitfield `needed` which is passed in provides information
about what sorts of information that the filter function needs;
this allows GTK+ to avoid retrieving expensive information when
it isn’t needed by the filter.
## `needed`
bitfield of flags indicating the information that the custom
 filter function needs.
## `func`
callback function; if the function returns `true`, then
 the file will be displayed.
## `data`
data to pass to `func`
## `notify`
function to call to free `data` when it is no longer needed.
<!-- impl FileFilter::fn add_mime_type -->
Adds a rule allowing a given mime type to `self`.
## `mime_type`
name of a MIME type
<!-- impl FileFilter::fn add_pattern -->
Adds a rule allowing a shell style glob to a filter.
## `pattern`
a shell style glob
<!-- impl FileFilter::fn add_pixbuf_formats -->
Adds a rule allowing image files in the formats supported
by `gdk_pixbuf::Pixbuf`.
<!-- impl FileFilter::fn filter -->
Tests whether a file should be displayed according to `self`.
The `FileFilterInfo` `filter_info` should include
the fields returned from `FileFilter::get_needed`.

This function will not typically be used by applications; it
is intended principally for use in the implementation of
`FileChooser`.
## `filter_info`
a `FileFilterInfo` containing information
 about a file.

# Returns

`true` if the file should be displayed
<!-- impl FileFilter::fn get_name -->
Gets the human-readable name for the filter. See `FileFilter::set_name`.

# Returns

The human-readable name of the filter,
 or `None`. This value is owned by GTK+ and must not
 be modified or freed.
<!-- impl FileFilter::fn get_needed -->
Gets the fields that need to be filled in for the `FileFilterInfo`
passed to `FileFilter::filter`

This function will not typically be used by applications; it
is intended principally for use in the implementation of
`FileChooser`.

# Returns

bitfield of flags indicating needed fields when
 calling `FileFilter::filter`
<!-- impl FileFilter::fn set_name -->
Sets the human-readable name of the filter; this is the string
that will be displayed in the file selector user interface if
there is a selectable list of filters.
## `name`
the human-readable-name for the filter, or `None`
 to remove any existing name.
<!-- impl FileFilter::fn to_gvariant -->
Serialize a file filter to an a{sv} variant.

Feature: `v3_22`


# Returns

a new, floating, `glib::Variant`
<!-- struct FileFilterFlags -->
These flags indicate what parts of a `FileFilterInfo` struct
are filled or need to be filled.
<!-- struct FileFilterFlags::const FILENAME -->
the filename of the file being tested
<!-- struct FileFilterFlags::const URI -->
the URI for the file being tested
<!-- struct FileFilterFlags::const DISPLAY_NAME -->
the string that will be used to
 display the file in the file chooser
<!-- struct FileFilterFlags::const MIME_TYPE -->
the mime type of the file
<!-- struct Fixed -->
The `Fixed` widget is a container which can place child widgets
at fixed positions and with fixed sizes, given in pixels. `Fixed`
performs no automatic layout management.

For most applications, you should not use this container! It keeps
you from having to learn about the other GTK+ containers, but it
results in broken applications. With `Fixed`, the following
things will result in truncated text, overlapping widgets, and
other display bugs:

- Themes, which may change widget sizes.

- Fonts other than the one you used to write the app will of course
 change the size of widgets containing text; keep in mind that
 users may use a larger font because of difficulty reading the
 default, or they may be using a different OS that provides different fonts.

- Translation of text into other languages changes its size. Also,
 display of non-English text will use a different font in many
 cases.

In addition, `Fixed` does not pay attention to text direction and thus may
produce unwanted results if your app is run under right-to-left languages
such as Hebrew or Arabic. That is: normally GTK+ will order containers
appropriately for the text direction, e.g. to put labels to the right of the
thing they label when using an RTL language, but it can’t do that with
`Fixed`. So if you need to reorder widgets depending on the text direction,
you would need to manually detect it and adjust child positions accordingly.

Finally, fixed positioning makes it kind of annoying to add/remove
GUI elements, since you have to reposition all the other
elements. This is a long-term maintenance problem for your
application.

If you know none of these things are an issue for your application,
and prefer the simplicity of `Fixed`, by all means use the
widget. But you should be aware of the tradeoffs.

See also `Layout`, which shares the ability to perform fixed positioning
of child widgets and additionally adds custom drawing and scrollability.

# Implements

[`FixedExt`](trait.FixedExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`FixedExtManual`](prelude/trait.FixedExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FixedExt -->
Trait containing all `Fixed` methods.

# Implementors

[`Fixed`](struct.Fixed.html)
<!-- impl Fixed::fn new -->
Creates a new `Fixed`.

# Returns

a new `Fixed`.
<!-- trait FixedExt::fn move -->
Moves a child of a `Fixed` container to the given position.
## `widget`
the child widget.
## `x`
the horizontal position to move the widget to.
## `y`
the vertical position to move the widget to.
<!-- trait FixedExt::fn put -->
Adds a widget to a `Fixed` container at the given position.
## `widget`
the widget to add.
## `x`
the horizontal position to place the widget at.
## `y`
the vertical position to place the widget at.
<!-- struct FlowBox -->
A `FlowBox` positions child widgets in sequence according to its
orientation.

For instance, with the horizontal orientation, the widgets will be
arranged from left to right, starting a new row under the previous
row when necessary. Reducing the width in this case will require more
rows, so a larger height will be requested.

Likewise, with the vertical orientation, the widgets will be arranged
from top to bottom, starting a new column to the right when necessary.
Reducing the height will require more columns, so a larger width will
be requested.

The size request of a `FlowBox` alone may not be what you expect; if you
need to be able to shrink it along both axes and dynamically reflow its
children, you may have to wrap it in a `ScrolledWindow` to enable that.

The children of a `FlowBox` can be dynamically sorted and filtered.

Although a `FlowBox` must have only `FlowBoxChild` children,
you can add any kind of widget to it via `ContainerExt::add`, and
a `FlowBoxChild` widget will automatically be inserted between
the box and the widget.

Also see `ListBox`.

`FlowBox` was added in GTK+ 3.12.

# CSS nodes


```plain
flowbox
├── flowboxchild
│   ╰── <child>
├── flowboxchild
│   ╰── <child>
┊
╰── [rubberband]
```

`FlowBox` uses a single CSS node with name flowbox. `FlowBoxChild`
uses a single CSS node with name flowboxchild.
For rubberband selection, a subnode with name rubberband is used.

# Implements

[`FlowBoxExt`](trait.FlowBoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`FlowBoxExtManual`](prelude/trait.FlowBoxExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FlowBoxExt -->
Trait containing all `FlowBox` methods.

# Implementors

[`FlowBox`](struct.FlowBox.html)
<!-- impl FlowBox::fn new -->
Creates a `FlowBox`.

# Returns

a new `FlowBox` container
<!-- trait FlowBoxExt::fn bind_model -->
Binds `model` to `self`.

If `self` was already bound to a model, that previous binding is
destroyed.

The contents of `self` are cleared and then filled with widgets that
represent items from `model`. `self` is updated whenever `model` changes.
If `model` is `None`, `self` is left empty.

It is undefined to add or remove widgets directly (for example, with
`FlowBoxExt::insert` or `ContainerExt::add`) while `self` is bound to a
model.

Note that using a model is incompatible with the filtering and sorting
functionality in `FlowBox`. When using a model, filtering and sorting
should be implemented by the model.

Feature: `v3_18`

## `model`
the `gio::ListModel` to be bound to `self`
## `create_widget_func`
a function that creates widgets for items
## `user_data`
user data passed to `create_widget_func`
## `user_data_free_func`
function for freeing `user_data`
<!-- trait FlowBoxExt::fn get_activate_on_single_click -->
Returns whether children activate on single clicks.

# Returns

`true` if children are activated on single click,
 `false` otherwise
<!-- trait FlowBoxExt::fn get_child_at_index -->
Gets the nth child in the `self`.
## `idx`
the position of the child

# Returns

the child widget, which will
 always be a `FlowBoxChild` or `None` in case no child widget
 with the given index exists.
<!-- trait FlowBoxExt::fn get_child_at_pos -->
Gets the child in the (`x`, `y`) position.

Feature: `v3_22_6`

## `x`
the x coordinate of the child
## `y`
the y coordinate of the child

# Returns

the child widget, which will
 always be a `FlowBoxChild` or `None` in case no child widget
 exists for the given x and y coordinates.
<!-- trait FlowBoxExt::fn get_column_spacing -->
Gets the horizontal spacing.

# Returns

the horizontal spacing
<!-- trait FlowBoxExt::fn get_homogeneous -->
Returns whether the box is homogeneous (all children are the
same size). See `BoxExt::set_homogeneous`.

# Returns

`true` if the box is homogeneous.
<!-- trait FlowBoxExt::fn get_max_children_per_line -->
Gets the maximum number of children per line.

# Returns

the maximum number of children per line
<!-- trait FlowBoxExt::fn get_min_children_per_line -->
Gets the minimum number of children per line.

# Returns

the minimum number of children per line
<!-- trait FlowBoxExt::fn get_row_spacing -->
Gets the vertical spacing.

# Returns

the vertical spacing
<!-- trait FlowBoxExt::fn get_selected_children -->
Creates a list of all selected children.

# Returns


 A `glib::List` containing the `Widget` for each selected child.
 Free with `glib::List::free` when done.
<!-- trait FlowBoxExt::fn get_selection_mode -->
Gets the selection mode of `self`.

# Returns

the `SelectionMode`
<!-- trait FlowBoxExt::fn insert -->
Inserts the `widget` into `self` at `position`.

If a sort function is set, the widget will actually be inserted
at the calculated position and this function has the same effect
as `ContainerExt::add`.

If `position` is -1, or larger than the total number of children
in the `self`, then the `widget` will be appended to the end.
## `widget`
the `Widget` to add
## `position`
the position to insert `child` in
<!-- trait FlowBoxExt::fn invalidate_filter -->
Updates the filtering for all children.

Call this function when the result of the filter
function on the `self` is changed due ot an external
factor. For instance, this would be used if the
filter function just looked for a specific search
term, and the entry with the string has changed.
<!-- trait FlowBoxExt::fn invalidate_sort -->
Updates the sorting for all children.

Call this when the result of the sort function on
`self` is changed due to an external factor.
<!-- trait FlowBoxExt::fn select_all -->
Select all children of `self`, if the selection
mode allows it.
<!-- trait FlowBoxExt::fn select_child -->
Selects a single child of `self`, if the selection
mode allows it.
## `child`
a child of `self`
<!-- trait FlowBoxExt::fn selected_foreach -->
Calls a function for each selected child.

Note that the selection cannot be modified from within
this function.
## `func`
the function to call for each selected child
## `data`
user data to pass to the function
<!-- trait FlowBoxExt::fn set_activate_on_single_click -->
If `single` is `true`, children will be activated when you click
on them, otherwise you need to double-click.
## `single`
`true` to emit child-activated on a single click
<!-- trait FlowBoxExt::fn set_column_spacing -->
Sets the horizontal space to add between children.
See the `FlowBox:column-spacing` property.
## `spacing`
the spacing to use
<!-- trait FlowBoxExt::fn set_filter_func -->
By setting a filter function on the `self` one can decide dynamically
which of the children to show. For instance, to implement a search
function that only shows the children matching the search terms.

The `filter_func` will be called for each child after the call, and
it will continue to be called each time a child changes (via
`FlowBoxChildExt::changed`) or when `FlowBoxExt::invalidate_filter`
is called.

Note that using a filter function is incompatible with using a model
(see `FlowBoxExt::bind_model`).
## `filter_func`
callback that
 lets you filter which children to show
## `user_data`
user data passed to `filter_func`
## `destroy`
destroy notifier for `user_data`
<!-- trait FlowBoxExt::fn set_hadjustment -->
Hooks up an adjustment to focus handling in `self`.
The adjustment is also used for autoscrolling during
rubberband selection. See `ScrolledWindowExt::get_hadjustment`
for a typical way of obtaining the adjustment, and
`FlowBoxExt::set_vadjustment`for setting the vertical
adjustment.

The adjustments have to be in pixel units and in the same
coordinate system as the allocation for immediate children
of the box.
## `adjustment`
an adjustment which should be adjusted
 when the focus is moved among the descendents of `container`
<!-- trait FlowBoxExt::fn set_homogeneous -->
Sets the `FlowBox:homogeneous` property of `self`, controlling
whether or not all children of `self` are given equal space
in the box.
## `homogeneous`
`true` to create equal allotments,
 `false` for variable allotments
<!-- trait FlowBoxExt::fn set_max_children_per_line -->
Sets the maximum number of children to request and
allocate space for in `self`’s orientation.

Setting the maximum number of children per line
limits the overall natural size request to be no more
than `n_children` children long in the given orientation.
## `n_children`
the maximum number of children per line
<!-- trait FlowBoxExt::fn set_min_children_per_line -->
Sets the minimum number of children to line up
in `self`’s orientation before flowing.
## `n_children`
the minimum number of children per line
<!-- trait FlowBoxExt::fn set_row_spacing -->
Sets the vertical space to add between children.
See the `FlowBox:row-spacing` property.
## `spacing`
the spacing to use
<!-- trait FlowBoxExt::fn set_selection_mode -->
Sets how selection works in `self`.
See `SelectionMode` for details.
## `mode`
the new selection mode
<!-- trait FlowBoxExt::fn set_sort_func -->
By setting a sort function on the `self`, one can dynamically
reorder the children of the box, based on the contents of
the children.

The `sort_func` will be called for each child after the call,
and will continue to be called each time a child changes (via
`FlowBoxChildExt::changed`) and when `FlowBoxExt::invalidate_sort`
is called.

Note that using a sort function is incompatible with using a model
(see `FlowBoxExt::bind_model`).
## `sort_func`
the sort function
## `user_data`
user data passed to `sort_func`
## `destroy`
destroy notifier for `user_data`
<!-- trait FlowBoxExt::fn set_vadjustment -->
Hooks up an adjustment to focus handling in `self`.
The adjustment is also used for autoscrolling during
rubberband selection. See `ScrolledWindowExt::get_vadjustment`
for a typical way of obtaining the adjustment, and
`FlowBoxExt::set_hadjustment`for setting the horizontal
adjustment.

The adjustments have to be in pixel units and in the same
coordinate system as the allocation for immediate children
of the box.
## `adjustment`
an adjustment which should be adjusted
 when the focus is moved among the descendents of `container`
<!-- trait FlowBoxExt::fn unselect_all -->
Unselect all children of `self`, if the selection
mode allows it.
<!-- trait FlowBoxExt::fn unselect_child -->
Unselects a single child of `self`, if the selection
mode allows it.
## `child`
a child of `self`
<!-- trait FlowBoxExt::fn connect_activate_cursor_child -->
The ::activate-cursor-child signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user activates the `box_`.
<!-- trait FlowBoxExt::fn connect_child_activated -->
The ::child-activated signal is emitted when a child has been
activated by the user.
## `child`
the child that is activated
<!-- trait FlowBoxExt::fn connect_move_cursor -->
The ::move-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a cursor movement.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically.

The default bindings for this signal come in two variants,
the variant with the Shift modifier extends the selection,
the variant without the Shift modifer does not.
There are too many key combinations to list them all here.
- Arrow keys move by individual children
- Home/End keys move to the ends of the box
- PageUp/PageDown keys move vertically by pages
## `step`
the granularity fo the move, as a `MovementStep`
## `count`
the number of `step` units to move

# Returns

`true` to stop other handlers from being invoked for the event.
`false` to propagate the event further.
<!-- trait FlowBoxExt::fn connect_select_all -->
The ::select-all signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to select all children of the box, if
the selection mode permits it.

The default bindings for this signal is Ctrl-a.
<!-- trait FlowBoxExt::fn connect_selected_children_changed -->
The ::selected-children-changed signal is emitted when the
set of selected children changes.

Use `FlowBoxExt::selected_foreach` or
`FlowBoxExt::get_selected_children` to obtain the
selected children.
<!-- trait FlowBoxExt::fn connect_toggle_cursor_child -->
The ::toggle-cursor-child signal is a
[keybinding signal][`BindingSignal`]
which toggles the selection of the child that has the focus.

The default binding for this signal is Ctrl-Space.
<!-- trait FlowBoxExt::fn connect_unselect_all -->
The ::unselect-all signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to unselect all children of the box, if
the selection mode permits it.

The default bindings for this signal is Ctrl-Shift-a.
<!-- trait FlowBoxExt::fn get_property_activate_on_single_click -->
Determines whether children can be activated with a single
click, or require a double-click.
<!-- trait FlowBoxExt::fn set_property_activate_on_single_click -->
Determines whether children can be activated with a single
click, or require a double-click.
<!-- trait FlowBoxExt::fn get_property_column_spacing -->
The amount of horizontal space between two children.
<!-- trait FlowBoxExt::fn set_property_column_spacing -->
The amount of horizontal space between two children.
<!-- trait FlowBoxExt::fn get_property_homogeneous -->
Determines whether all children should be allocated the
same size.
<!-- trait FlowBoxExt::fn set_property_homogeneous -->
Determines whether all children should be allocated the
same size.
<!-- trait FlowBoxExt::fn get_property_max_children_per_line -->
The maximum amount of children to request space for consecutively
in the given orientation.
<!-- trait FlowBoxExt::fn set_property_max_children_per_line -->
The maximum amount of children to request space for consecutively
in the given orientation.
<!-- trait FlowBoxExt::fn get_property_min_children_per_line -->
The minimum number of children to allocate consecutively
in the given orientation.

Setting the minimum children per line ensures
that a reasonably small height will be requested
for the overall minimum width of the box.
<!-- trait FlowBoxExt::fn set_property_min_children_per_line -->
The minimum number of children to allocate consecutively
in the given orientation.

Setting the minimum children per line ensures
that a reasonably small height will be requested
for the overall minimum width of the box.
<!-- trait FlowBoxExt::fn get_property_row_spacing -->
The amount of vertical space between two children.
<!-- trait FlowBoxExt::fn set_property_row_spacing -->
The amount of vertical space between two children.
<!-- trait FlowBoxExt::fn get_property_selection_mode -->
The selection mode used by the flow box.
<!-- trait FlowBoxExt::fn set_property_selection_mode -->
The selection mode used by the flow box.
<!-- struct FlowBoxChild -->


# Implements

[`FlowBoxChildExt`](trait.FlowBoxChildExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FlowBoxChildExt -->
Trait containing all `FlowBoxChild` methods.

# Implementors

[`FlowBoxChild`](struct.FlowBoxChild.html)
<!-- impl FlowBoxChild::fn new -->
Creates a new `FlowBoxChild`, to be used as a child
of a `FlowBox`.

# Returns

a new `FlowBoxChild`
<!-- trait FlowBoxChildExt::fn changed -->
Marks `self` as changed, causing any state that depends on this
to be updated. This affects sorting and filtering.

Note that calls to this method must be in sync with the data
used for the sorting and filtering functions. For instance, if
the list is mirroring some external data set, and *two* children
changed in the external data set when you call
`FlowBoxChildExt::changed` on the first child, the sort function
must only read the new data for the first of the two changed
children, otherwise the resorting of the children will be wrong.

This generally means that if you don’t fully control the data
model, you have to duplicate the data that affects the sorting
and filtering functions into the widgets themselves. Another
alternative is to call `FlowBoxExt::invalidate_sort` on any
model change, but that is more expensive.
<!-- trait FlowBoxChildExt::fn get_index -->
Gets the current index of the `self` in its `FlowBox` container.

# Returns

the index of the `self`, or -1 if the `self` is not
 in a flow box.
<!-- trait FlowBoxChildExt::fn is_selected -->
Returns whether the `self` is currently selected in its
`FlowBox` container.

# Returns

`true` if `self` is selected
<!-- trait FlowBoxChildExt::fn connect_activate -->
The ::activate signal is emitted when the user activates
a child widget in a `FlowBox`, either by clicking or
double-clicking, or by using the Space or Enter key.

While this signal is used as a
[keybinding signal][`BindingSignal`],
it can be used by applications for their own purposes.
<!-- struct FontButton -->
The `FontButton` is a button which displays the currently selected
font an allows to open a font chooser dialog to change the font.
It is suitable widget for selecting a font in a preference dialog.

# CSS nodes

`FontButton` has a single CSS node with name button and style class .font.

# Implements

[`FontButtonExt`](trait.FontButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`FontChooserExt`](trait.FontChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FontButtonExt -->
Trait containing all `FontButton` methods.

# Implementors

[`FontButton`](struct.FontButton.html)
<!-- impl FontButton::fn new -->
Creates a new font picker widget.

# Returns

a new font picker widget.
<!-- impl FontButton::fn new_with_font -->
Creates a new font picker widget.
## `fontname`
Name of font to display in font chooser dialog

# Returns

a new font picker widget.
<!-- trait FontButtonExt::fn get_font_name -->
Retrieves the name of the currently selected font. This name includes
style and size information as well. If you want to render something
with the font, use this string with `pango::FontDescription::from_string` .
If you’re interested in peeking certain values (family name,
style, size, weight) just query these properties from the
`pango::FontDescription` object.

# Deprecated since 3.22

Use `FontChooser::get_font` instead

# Returns

an internal copy of the font name which must not be freed.
<!-- trait FontButtonExt::fn get_show_size -->
Returns whether the font size will be shown in the label.

# Returns

whether the font size will be shown in the label.
<!-- trait FontButtonExt::fn get_show_style -->
Returns whether the name of the font style will be shown in the label.

# Returns

whether the font style will be shown in the label.
<!-- trait FontButtonExt::fn get_title -->
Retrieves the title of the font chooser dialog.

# Returns

an internal copy of the title string which must not be freed.
<!-- trait FontButtonExt::fn get_use_font -->
Returns whether the selected font is used in the label.

# Returns

whether the selected font is used in the label.
<!-- trait FontButtonExt::fn get_use_size -->
Returns whether the selected size is used in the label.

# Returns

whether the selected size is used in the label.
<!-- trait FontButtonExt::fn set_font_name -->
Sets or updates the currently-displayed font in font picker dialog.

# Deprecated since 3.22

Use `FontChooser::set_font` instead
## `fontname`
Name of font to display in font chooser dialog

# Returns

`true`
<!-- trait FontButtonExt::fn set_show_size -->
If `show_size` is `true`, the font size will be displayed along with the name of the selected font.
## `show_size`
`true` if font size should be displayed in dialog.
<!-- trait FontButtonExt::fn set_show_style -->
If `show_style` is `true`, the font style will be displayed along with name of the selected font.
## `show_style`
`true` if font style should be displayed in label.
<!-- trait FontButtonExt::fn set_title -->
Sets the title for the font chooser dialog.
## `title`
a string containing the font chooser dialog title
<!-- trait FontButtonExt::fn set_use_font -->
If `use_font` is `true`, the font name will be written using the selected font.
## `use_font`
If `true`, font name will be written using font chosen.
<!-- trait FontButtonExt::fn set_use_size -->
If `use_size` is `true`, the font name will be written using the selected size.
## `use_size`
If `true`, font name will be written using the selected size.
<!-- trait FontButtonExt::fn connect_font_set -->
The ::font-set signal is emitted when the user selects a font.
When handling this signal, use `FontChooser::get_font`
to find out which font was just selected.

Note that this signal is only emitted when the user
changes the font. If you need to react to programmatic font changes
as well, use the notify::font signal.
<!-- trait FontButtonExt::fn get_property_font_name -->
The name of the currently selected font.

# Deprecated since 3.22

Use the `FontChooser::font` property instead
<!-- trait FontButtonExt::fn set_property_font_name -->
The name of the currently selected font.

# Deprecated since 3.22

Use the `FontChooser::font` property instead
<!-- trait FontButtonExt::fn get_property_show_size -->
If this property is set to `true`, the selected font size will be shown
in the label. For a more WYSIWYG way to show the selected size, see the
::use-size property.
<!-- trait FontButtonExt::fn set_property_show_size -->
If this property is set to `true`, the selected font size will be shown
in the label. For a more WYSIWYG way to show the selected size, see the
::use-size property.
<!-- trait FontButtonExt::fn get_property_show_style -->
If this property is set to `true`, the name of the selected font style
will be shown in the label. For a more WYSIWYG way to show the selected
style, see the ::use-font property.
<!-- trait FontButtonExt::fn set_property_show_style -->
If this property is set to `true`, the name of the selected font style
will be shown in the label. For a more WYSIWYG way to show the selected
style, see the ::use-font property.
<!-- trait FontButtonExt::fn get_property_title -->
The title of the font chooser dialog.
<!-- trait FontButtonExt::fn set_property_title -->
The title of the font chooser dialog.
<!-- trait FontButtonExt::fn get_property_use_font -->
If this property is set to `true`, the label will be drawn
in the selected font.
<!-- trait FontButtonExt::fn set_property_use_font -->
If this property is set to `true`, the label will be drawn
in the selected font.
<!-- trait FontButtonExt::fn get_property_use_size -->
If this property is set to `true`, the label will be drawn
with the selected font size.
<!-- trait FontButtonExt::fn set_property_use_size -->
If this property is set to `true`, the label will be drawn
with the selected font size.
<!-- struct FontChooser -->
`FontChooser` is an interface that can be implemented by widgets
displaying the list of fonts. In GTK+, the main objects
that implement this interface are `FontChooserWidget`,
`FontChooserDialog` and `FontButton`. The `FontChooser` interface
has been introducted in GTK+ 3.2.

# Implements

[`FontChooserExt`](trait.FontChooserExt.html)
<!-- trait FontChooserExt -->
Trait containing all `FontChooser` methods.

# Implementors

[`FontButton`](struct.FontButton.html), [`FontChooserDialog`](struct.FontChooserDialog.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`FontChooser`](struct.FontChooser.html)
<!-- trait FontChooserExt::fn get_font -->
Gets the currently-selected font name.

Note that this can be a different string than what you set with
`FontChooser::set_font`, as the font chooser widget may
normalize font names and thus return a string with a different
structure. For example, “Helvetica Italic Bold 12” could be
normalized to “Helvetica Bold Italic 12”.

Use `pango::FontDescription::equal` if you want to compare two
font descriptions.

# Returns

A string with the name
 of the current font, or `None` if no font is selected. You must
 free this string with `g_free`.
<!-- trait FontChooserExt::fn get_font_desc -->
Gets the currently-selected font.

Note that this can be a different string than what you set with
`FontChooser::set_font`, as the font chooser widget may
normalize font names and thus return a string with a different
structure. For example, “Helvetica Italic Bold 12” could be
normalized to “Helvetica Bold Italic 12”.

Use `pango::FontDescription::equal` if you want to compare two
font descriptions.

# Returns

A `pango::FontDescription` for the
 current font, or `None` if no font is selected.
<!-- trait FontChooserExt::fn get_font_face -->
Gets the `pango::FontFace` representing the selected font group
details (i.e. family, slant, weight, width, etc).

If the selected font is not installed, returns `None`.

# Returns

A `pango::FontFace` representing the
 selected font group details, or `None`. The returned object is owned by
 `self` and must not be modified or freed.
<!-- trait FontChooserExt::fn get_font_family -->
Gets the `pango::FontFamily` representing the selected font family.
Font families are a collection of font faces.

If the selected font is not installed, returns `None`.

# Returns

A `pango::FontFamily` representing the
 selected font family, or `None`. The returned object is owned by `self`
 and must not be modified or freed.
<!-- trait FontChooserExt::fn get_font_features -->
Gets the currently-selected font features.

Feature: `v3_24`


# Returns

the currently selected font features
<!-- trait FontChooserExt::fn get_font_map -->
Gets the custom font map of this font chooser widget,
or `None` if it does not have one.

Feature: `v3_18`


# Returns

a `pango::FontMap`, or `None`
<!-- trait FontChooserExt::fn get_font_size -->
The selected font size.

# Returns

A n integer representing the selected font size,
 or -1 if no font size is selected.
<!-- trait FontChooserExt::fn get_language -->
Gets the language that is used for font features.

Feature: `v3_24`


# Returns

the currently selected language
<!-- trait FontChooserExt::fn get_level -->
Returns the current level of granularity for selecting fonts.

Feature: `v3_24`


# Returns

the current granularity level
<!-- trait FontChooserExt::fn get_preview_text -->
Gets the text displayed in the preview area.

# Returns

the text displayed in the
 preview area
<!-- trait FontChooserExt::fn get_show_preview_entry -->
Returns whether the preview entry is shown or not.

# Returns

`true` if the preview entry is shown
 or `false` if it is hidden.
<!-- trait FontChooserExt::fn set_filter_func -->
Adds a filter function that decides which fonts to display
in the font chooser.
## `filter`
a ``GtkFontFilterFunc``, or `None`
## `user_data`
data to pass to `filter`
## `destroy`
function to call to free `data` when it is no longer needed
<!-- trait FontChooserExt::fn set_font -->
Sets the currently-selected font.
## `fontname`
a font name like “Helvetica 12” or “Times Bold 18”
<!-- trait FontChooserExt::fn set_font_desc -->
Sets the currently-selected font from `font_desc`.
## `font_desc`
a `pango::FontDescription`
<!-- trait FontChooserExt::fn set_font_map -->
Sets a custom font map to use for this font chooser widget.
A custom font map can be used to present application-specific
fonts instead of or in addition to the normal system fonts.


```C
FcConfig *config;
PangoFontMap *fontmap;

config = FcInitLoadConfigAndFonts ();
FcConfigAppFontAddFile (config, my_app_font_file);

fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT);
pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config);

gtk_font_chooser_set_font_map (font_chooser, fontmap);
```

Note that other GTK+ widgets will only be able to use the application-specific
font if it is present in the font map they use:


```text
context = gtk_widget_get_pango_context (label);
pango_context_set_font_map (context, fontmap);
```

Feature: `v3_18`

## `fontmap`
a `pango::FontMap`
<!-- trait FontChooserExt::fn set_language -->
Sets the language to use for font features.

Feature: `v3_24`

## `language`
a language
<!-- trait FontChooserExt::fn set_level -->
Sets the desired level of granularity for selecting fonts.

Feature: `v3_24`

## `level`
the desired level of granularity
<!-- trait FontChooserExt::fn set_preview_text -->
Sets the text displayed in the preview area.
The `text` is used to show how the selected font looks.
## `text`
the text to display in the preview area
<!-- trait FontChooserExt::fn set_show_preview_entry -->
Shows or hides the editable preview entry.
## `show_preview_entry`
whether to show the editable preview entry or not
<!-- trait FontChooserExt::fn connect_font_activated -->
Emitted when a font is activated.
This usually happens when the user double clicks an item,
or an item is selected and the user presses one of the keys
Space, Shift+Space, Return or Enter.
## `fontname`
the font name
<!-- trait FontChooserExt::fn get_property_font -->
The font description as a string, e.g. "Sans Italic 12".
<!-- trait FontChooserExt::fn set_property_font -->
The font description as a string, e.g. "Sans Italic 12".
<!-- trait FontChooserExt::fn get_property_font_desc -->
The font description as a `pango::FontDescription`.
<!-- trait FontChooserExt::fn set_property_font_desc -->
The font description as a `pango::FontDescription`.
<!-- trait FontChooserExt::fn get_property_font_features -->
The selected font features, in a format that is compatible with
CSS and with Pango attributes.

Feature: `v3_22_30`

<!-- trait FontChooserExt::fn get_property_language -->
The language for which the `FontChooser:font-features` were
selected, in a format that is compatible with CSS and with Pango
attributes.

Feature: `v3_22_30`

<!-- trait FontChooserExt::fn set_property_language -->
The language for which the `FontChooser:font-features` were
selected, in a format that is compatible with CSS and with Pango
attributes.

Feature: `v3_22_30`

<!-- trait FontChooserExt::fn get_property_level -->
The level of granularity to offer for selecting fonts.

Feature: `v3_22_30`

<!-- trait FontChooserExt::fn set_property_level -->
The level of granularity to offer for selecting fonts.

Feature: `v3_22_30`

<!-- trait FontChooserExt::fn get_property_preview_text -->
The string with which to preview the font.
<!-- trait FontChooserExt::fn set_property_preview_text -->
The string with which to preview the font.
<!-- trait FontChooserExt::fn get_property_show_preview_entry -->
Whether to show an entry to change the preview text.
<!-- trait FontChooserExt::fn set_property_show_preview_entry -->
Whether to show an entry to change the preview text.
<!-- struct FontChooserDialog -->
The `FontChooserDialog` widget is a dialog for selecting a font.
It implements the `FontChooser` interface.

# `FontChooserDialog` as `Buildable`

The `FontChooserDialog` implementation of the `Buildable`
interface exposes the buttons with the names “select_button”
and “cancel_button”.

# Implements

[`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`FontChooserExt`](trait.FontChooserExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl FontChooserDialog::fn new -->
Creates a new `FontChooserDialog`.
## `title`
Title of the dialog, or `None`
## `parent`
Transient parent of the dialog, or `None`

# Returns

a new `FontChooserDialog`
<!-- struct FontChooserLevel -->
This enumeration specifies the granularity of font selection
that is desired in a font chooser.

This enumeration may be extended in the future; applications should
ignore unknown values.
<!-- struct FontChooserLevel::const FAMILY -->
Allow selecting a font family
<!-- struct FontChooserLevel::const STYLE -->
Allow selecting a specific font face
<!-- struct FontChooserLevel::const SIZE -->
Allow selecting a specific font size
<!-- struct FontChooserLevel::const FEATURES -->
Allow selecting specific OpenType font features

Feature: `v3_24`

<!-- struct FontChooserWidget -->
The `FontChooserWidget` widget lists the available fonts,
styles and sizes, allowing the user to select a font. It is
used in the `FontChooserDialog` widget to provide a
dialog box for selecting fonts.

To set the font which is initially selected, use
`FontChooser::set_font` or `FontChooser::set_font_desc`.

To get the selected font use `FontChooser::get_font` or
`FontChooser::get_font_desc`.

To change the text which is shown in the preview area, use
`FontChooser::set_preview_text`.

# CSS nodes

`FontChooserWidget` has a single CSS node with name fontchooser.

# Implements

[`FontChooserWidgetExt`](trait.FontChooserWidgetExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`FontChooserExt`](trait.FontChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FontChooserWidgetExt -->
Trait containing all `FontChooserWidget` methods.

# Implementors

[`FontChooserWidget`](struct.FontChooserWidget.html)
<!-- impl FontChooserWidget::fn new -->
Creates a new `FontChooserWidget`.

# Returns

a new `FontChooserWidget`
<!-- trait FontChooserWidgetExt::fn get_property_tweak_action -->
A toggle action that can be used to switch to the tweak page
of the font chooser widget, which lets the user tweak the
OpenType features and variation axes of the selected font.

The action will be enabled or disabled depending on whether
the selected font has any features or axes.
<!-- struct Frame -->
The frame widget is a bin that surrounds its child with a decorative
frame and an optional label. If present, the label is drawn in a gap
in the top side of the frame. The position of the label can be
controlled with `FrameExt::set_label_align`.

# `Frame` as `Buildable`

The `Frame` implementation of the `Buildable` interface supports
placing a child in the label position by specifying “label” as the
“type” attribute of a `<child>` element. A normal content child can
be specified without specifying a `<child>` type attribute.

An example of a UI definition fragment with `Frame`:

```plain
frame
├── border[.flat]
├── <label widget>
╰── <child>
```

`Frame` has a main CSS node named “frame” and a subnode named “border”. The
“border” node is used to draw the visible border. You can set the appearance
of the border using CSS properties like “border-style” on the “border” node.

The border node can be given the style class “.flat”, which is used by themes
to disable drawing of the border. To do this from code, call
`FrameExt::set_shadow_type` with `ShadowType::None` to add the “.flat” class or
any other shadow type to remove it.

# Implements

[`FrameExt`](trait.FrameExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait FrameExt -->
Trait containing all `Frame` methods.

# Implementors

[`AspectFrame`](struct.AspectFrame.html), [`Frame`](struct.Frame.html)
<!-- impl Frame::fn new -->
Creates a new `Frame`, with optional label `label`.
If `label` is `None`, the label is omitted.
## `label`
the text to use as the label of the frame

# Returns

a new `Frame` widget
<!-- trait FrameExt::fn get_label -->
If the frame’s label widget is a `Label`, returns the
text in the label widget. (The frame will have a `Label`
for the label widget if a non-`None` argument was passed
to `Frame::new`.)

# Returns

the text in the label, or `None` if there
 was no label widget or the lable widget was not
 a `Label`. This string is owned by GTK+ and
 must not be modified or freed.
<!-- trait FrameExt::fn get_label_align -->
Retrieves the X and Y alignment of the frame’s label. See
`FrameExt::set_label_align`.
## `xalign`
location to store X alignment of
 frame’s label, or `None`
## `yalign`
location to store X alignment of
 frame’s label, or `None`
<!-- trait FrameExt::fn get_label_widget -->
Retrieves the label widget for the frame. See
`FrameExt::set_label_widget`.

# Returns

the label widget, or `None` if
there is none.
<!-- trait FrameExt::fn get_shadow_type -->
Retrieves the shadow type of the frame. See
`FrameExt::set_shadow_type`.

# Returns

the current shadow type of the frame.
<!-- trait FrameExt::fn set_label -->
Removes the current `Frame:label-widget`. If `label` is not `None`, creates a
new `Label` with that text and adds it as the `Frame:label-widget`.
## `label`
the text to use as the label of the frame
<!-- trait FrameExt::fn set_label_align -->
Sets the alignment of the frame widget’s label. The
default values for a newly created frame are 0.0 and 0.5.
## `xalign`
The position of the label along the top edge
 of the widget. A value of 0.0 represents left alignment;
 1.0 represents right alignment.
## `yalign`
The y alignment of the label. A value of 0.0 aligns under
 the frame; 1.0 aligns above the frame. If the values are exactly
 0.0 or 1.0 the gap in the frame won’t be painted because the label
 will be completely above or below the frame.
<!-- trait FrameExt::fn set_label_widget -->
Sets the `Frame:label-widget` for the frame. This is the widget that
will appear embedded in the top edge of the frame as a title.
## `label_widget`
the new label widget
<!-- trait FrameExt::fn set_shadow_type -->
Sets the `Frame:shadow-type` for `self`, i.e. whether it is drawn without
(`ShadowType::None`) or with (other values) a visible border. Values other than
`ShadowType::None` are treated identically by `Frame`. The chosen type is
applied by removing or adding the .flat class to the CSS node named border.
## `type_`
the new `ShadowType`
<!-- struct GLArea -->
`GLArea` is a widget that allows drawing with OpenGL.

`GLArea` sets up its own `gdk::GLContext` for the window it creates, and
creates a custom GL framebuffer that the widget will do GL rendering onto.
It also ensures that this framebuffer is the default GL rendering target
when rendering.

In order to draw, you have to connect to the `GLArea::render` signal,
or subclass `GLArea` and override the `GLAreaClass.render`() virtual
function.

The `GLArea` widget ensures that the `gdk::GLContext` is associated with
the widget's drawing area, and it is kept updated when the size and
position of the drawing area changes.

## Drawing with `GLArea` ##

The simplest way to draw using OpenGL commands in a `GLArea` is to
create a widget instance and connect to the `GLArea::render` signal:


```C
  // create a GtkGLArea instance
  GtkWidget *gl_area = gtk_gl_area_new ();

  // connect to the "render" signal
  g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL);
```

The `render()` function will be called when the `GLArea` is ready
for you to draw its content:


```C
  static gboolean
  render (GtkGLArea *area, GdkGLContext *context)
  {
    // inside this function it's safe to use GL; the given
    // #GdkGLContext has been made current to the drawable
    // surface used by the #GtkGLArea and the viewport has
    // already been set to be the size of the allocation

    // we can start by clearing the buffer
    glClearColor (0, 0, 0, 0);
    glClear (GL_COLOR_BUFFER_BIT);

    // draw your object
    draw_an_object ();

    // we completed our drawing; the draw commands will be
    // flushed at the end of the signal emission chain, and
    // the buffers will be drawn on the window
    return TRUE;
  }
```

If you need to initialize OpenGL state, e.g. buffer objects or
shaders, you should use the `Widget::realize` signal; you
can use the `Widget::unrealize` signal to clean up. Since the
`gdk::GLContext` creation and initialization may fail, you will
need to check for errors, using `GLAreaExt::get_error`. An example
of how to safely initialize the GL state is:


```C
  static void
  on_realize (GtkGLarea *area)
  {
    // We need to make the context current if we want to
    // call GL API
    gtk_gl_area_make_current (area);

    // If there were errors during the initialization or
    // when trying to make the context current, this
    // function will return a #GError for you to catch
    if (gtk_gl_area_get_error (area) != NULL)
      return;

    // You can also use gtk_gl_area_set_error() in order
    // to show eventual initialization errors on the
    // GtkGLArea widget itself
    GError *internal_error = NULL;
    init_buffer_objects (&error);
    if (error != NULL)
      {
        gtk_gl_area_set_error (area, error);
        g_error_free (error);
        return;
      }

    init_shaders (&error);
    if (error != NULL)
      {
        gtk_gl_area_set_error (area, error);
        g_error_free (error);
        return;
      }
  }
```

If you need to change the options for creating the `gdk::GLContext`
you should use the `GLArea::create-context` signal.

Feature: `v3_16`

# Implements

[`GLAreaExt`](trait.GLAreaExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait GLAreaExt -->
Trait containing all `GLArea` methods.

Feature: `v3_16`

# Implementors

[`GLArea`](struct.GLArea.html)
<!-- impl GLArea::fn new -->
Creates a new `GLArea` widget.

Feature: `v3_16`


# Returns

a new `GLArea`
<!-- trait GLAreaExt::fn attach_buffers -->
Ensures that the `self` framebuffer object is made the current draw
and read target, and that all the required buffers for the `self`
are created and bound to the frambuffer.

This function is automatically called before emitting the
`GLArea::render` signal, and doesn't normally need to be called
by application code.

Feature: `v3_16`

<!-- trait GLAreaExt::fn get_auto_render -->
Returns whether the area is in auto render mode or not.

Feature: `v3_16`


# Returns

`true` if the `self` is auto rendering, `false` otherwise
<!-- trait GLAreaExt::fn get_context -->
Retrieves the `gdk::GLContext` used by `self`.

Feature: `v3_16`


# Returns

the `gdk::GLContext`
<!-- trait GLAreaExt::fn get_error -->
Gets the current error set on the `self`.

Feature: `v3_16`


# Returns

the `glib::Error` or `None`
<!-- trait GLAreaExt::fn get_has_alpha -->
Returns whether the area has an alpha component.

Feature: `v3_16`


# Returns

`true` if the `self` has an alpha component, `false` otherwise
<!-- trait GLAreaExt::fn get_has_depth_buffer -->
Returns whether the area has a depth buffer.

Feature: `v3_16`


# Returns

`true` if the `self` has a depth buffer, `false` otherwise
<!-- trait GLAreaExt::fn get_has_stencil_buffer -->
Returns whether the area has a stencil buffer.

Feature: `v3_16`


# Returns

`true` if the `self` has a stencil buffer, `false` otherwise
<!-- trait GLAreaExt::fn get_required_version -->
Retrieves the required version of OpenGL set
using `GLAreaExt::set_required_version`.

Feature: `v3_16`

## `major`
return location for the required major version
## `minor`
return location for the required minor version
<!-- trait GLAreaExt::fn get_use_es -->
Retrieves the value set by `GLAreaExt::set_use_es`.

Feature: `v3_22`


# Returns

`true` if the `GLArea` should create an OpenGL ES context
 and `false` otherwise
<!-- trait GLAreaExt::fn make_current -->
Ensures that the `gdk::GLContext` used by `self` is associated with
the `GLArea`.

This function is automatically called before emitting the
`GLArea::render` signal, and doesn't normally need to be called
by application code.

Feature: `v3_16`

<!-- trait GLAreaExt::fn queue_render -->
Marks the currently rendered data (if any) as invalid, and queues
a redraw of the widget, ensuring that the `GLArea::render` signal
is emitted during the draw.

This is only needed when the `GLAreaExt::set_auto_render` has
been called with a `false` value. The default behaviour is to
emit `GLArea::render` on each draw.

Feature: `v3_16`

<!-- trait GLAreaExt::fn set_auto_render -->
If `auto_render` is `true` the `GLArea::render` signal will be
emitted every time the widget draws. This is the default and is
useful if drawing the widget is faster.

If `auto_render` is `false` the data from previous rendering is kept
around and will be used for drawing the widget the next time,
unless the window is resized. In order to force a rendering
`GLAreaExt::queue_render` must be called. This mode is useful when
the scene changes seldomly, but takes a long time to redraw.

Feature: `v3_16`

## `auto_render`
a boolean
<!-- trait GLAreaExt::fn set_error -->
Sets an error on the area which will be shown instead of the
GL rendering. This is useful in the `GLArea::create-context`
signal if GL context creation fails.

Feature: `v3_16`

## `error`
a new `glib::Error`, or `None` to unset the error
<!-- trait GLAreaExt::fn set_has_alpha -->
If `has_alpha` is `true` the buffer allocated by the widget will have
an alpha channel component, and when rendering to the window the
result will be composited over whatever is below the widget.

If `has_alpha` is `false` there will be no alpha channel, and the
buffer will fully replace anything below the widget.

Feature: `v3_16`

## `has_alpha`
`true` to add an alpha component
<!-- trait GLAreaExt::fn set_has_depth_buffer -->
If `has_depth_buffer` is `true` the widget will allocate and
enable a depth buffer for the target framebuffer. Otherwise
there will be none.

Feature: `v3_16`

## `has_depth_buffer`
`true` to add a depth buffer
<!-- trait GLAreaExt::fn set_has_stencil_buffer -->
If `has_stencil_buffer` is `true` the widget will allocate and
enable a stencil buffer for the target framebuffer. Otherwise
there will be none.

Feature: `v3_16`

## `has_stencil_buffer`
`true` to add a stencil buffer
<!-- trait GLAreaExt::fn set_required_version -->
Sets the required version of OpenGL to be used when creating the context
for the widget.

This function must be called before the area has been realized.

Feature: `v3_16`

## `major`
the major version
## `minor`
the minor version
<!-- trait GLAreaExt::fn set_use_es -->
Sets whether the `self` should create an OpenGL or an OpenGL ES context.

You should check the capabilities of the `gdk::GLContext` before drawing
with either API.

Feature: `v3_22`

## `use_es`
whether to use OpenGL or OpenGL ES
<!-- trait GLAreaExt::fn connect_create_context -->
The ::create-context signal is emitted when the widget is being
realized, and allows you to override how the GL context is
created. This is useful when you want to reuse an existing GL
context, or if you want to try creating different kinds of GL
options.

If context creation fails then the signal handler can use
`GLAreaExt::set_error` to register a more detailed error
of how the construction failed.

Feature: `v3_16`


# Returns

a newly created `gdk::GLContext`;
 the `GLArea` widget will take ownership of the returned value.
<!-- trait GLAreaExt::fn connect_render -->
The ::render signal is emitted every time the contents
of the `GLArea` should be redrawn.

The `context` is bound to the `area` prior to emitting this function,
and the buffers are painted to the window once the emission terminates.

Feature: `v3_16`

## `context`
the `gdk::GLContext` used by `area`

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait GLAreaExt::fn connect_resize -->
The ::resize signal is emitted once when the widget is realized, and
then each time the widget is changed while realized. This is useful
in order to keep GL state up to date with the widget size, like for
instance camera properties which may depend on the width/height ratio.

The GL context for the area is guaranteed to be current when this signal
is emitted.

The default handler sets up the GL viewport.

Feature: `v3_16`

## `width`
the width of the viewport
## `height`
the height of the viewport
<!-- trait GLAreaExt::fn get_property_auto_render -->
If set to `true` the `GLArea::render` signal will be emitted every time
the widget draws. This is the default and is useful if drawing the widget
is faster.

If set to `false` the data from previous rendering is kept around and will
be used for drawing the widget the next time, unless the window is resized.
In order to force a rendering `GLAreaExt::queue_render` must be called.
This mode is useful when the scene changes seldomly, but takes a long time
to redraw.

Feature: `v3_16`

<!-- trait GLAreaExt::fn set_property_auto_render -->
If set to `true` the `GLArea::render` signal will be emitted every time
the widget draws. This is the default and is useful if drawing the widget
is faster.

If set to `false` the data from previous rendering is kept around and will
be used for drawing the widget the next time, unless the window is resized.
In order to force a rendering `GLAreaExt::queue_render` must be called.
This mode is useful when the scene changes seldomly, but takes a long time
to redraw.

Feature: `v3_16`

<!-- trait GLAreaExt::fn get_property_context -->
The `gdk::GLContext` used by the `GLArea` widget.

The `GLArea` widget is responsible for creating the `gdk::GLContext`
instance. If you need to render with other kinds of buffers (stencil,
depth, etc), use render buffers.

Feature: `v3_16`

<!-- trait GLAreaExt::fn get_property_has_alpha -->
If set to `true` the buffer allocated by the widget will have an alpha channel
component, and when rendering to the window the result will be composited over
whatever is below the widget.

If set to `false` there will be no alpha channel, and the buffer will fully
replace anything below the widget.

Feature: `v3_16`

<!-- trait GLAreaExt::fn set_property_has_alpha -->
If set to `true` the buffer allocated by the widget will have an alpha channel
component, and when rendering to the window the result will be composited over
whatever is below the widget.

If set to `false` there will be no alpha channel, and the buffer will fully
replace anything below the widget.

Feature: `v3_16`

<!-- trait GLAreaExt::fn get_property_has_depth_buffer -->
If set to `true` the widget will allocate and enable a depth buffer for the
target framebuffer.

Feature: `v3_16`

<!-- trait GLAreaExt::fn set_property_has_depth_buffer -->
If set to `true` the widget will allocate and enable a depth buffer for the
target framebuffer.

Feature: `v3_16`

<!-- trait GLAreaExt::fn get_property_has_stencil_buffer -->
If set to `true` the widget will allocate and enable a stencil buffer for the
target framebuffer.

Feature: `v3_16`

<!-- trait GLAreaExt::fn set_property_has_stencil_buffer -->
If set to `true` the widget will allocate and enable a stencil buffer for the
target framebuffer.

Feature: `v3_16`

<!-- trait GLAreaExt::fn get_property_use_es -->
If set to `true` the widget will try to create a `gdk::GLContext` using
OpenGL ES instead of OpenGL.

See also: `gdk::GLContext::set_use_es`

Feature: `v3_22`

<!-- trait GLAreaExt::fn set_property_use_es -->
If set to `true` the widget will try to create a `gdk::GLContext` using
OpenGL ES instead of OpenGL.

See also: `gdk::GLContext::set_use_es`

Feature: `v3_22`

<!-- struct Gesture -->
`Gesture` is the base object for gesture recognition, although this
object is quite generalized to serve as a base for multi-touch gestures,
it is suitable to implement single-touch and pointer-based gestures (using
the special `None` `gdk::EventSequence` value for these).

The number of touches that a `Gesture` need to be recognized is controlled
by the `Gesture:n-points` property, if a gesture is keeping track of less
or more than that number of sequences, it won't check wether the gesture
is recognized.

As soon as the gesture has the expected number of touches, the gesture will
run the `Gesture::check` signal regularly on input events until the gesture
is recognized, the criteria to consider a gesture as "recognized" is left to
`Gesture` subclasses.

A recognized gesture will then emit the following signals:
- `Gesture::begin` when the gesture is recognized.
- A number of `Gesture::update`, whenever an input event is processed.
- `Gesture::end` when the gesture is no longer recognized.

## Event propagation

In order to receive events, a gesture needs to either set a propagation phase
through `EventControllerExt::set_propagation_phase`, or feed those manually
through `EventControllerExt::handle_event`.

In the capture phase, events are propagated from the toplevel down to the
target widget, and gestures that are attached to containers above the widget
get a chance to interact with the event before it reaches the target.

After the capture phase, GTK+ emits the traditional `Widget::button-press-event`,
`Widget::button-release-event`, `Widget::touch-event`, etc signals. Gestures
with the `PropagationPhase::Target` phase are fed events from the default `Widget::event`
handlers.

In the bubble phase, events are propagated up from the target widget to the
toplevel, and gestures that are attached to containers above the widget get
a chance to interact with events that have not been handled yet.

## States of a sequence # {`touch`-sequence-states}

Whenever input interaction happens, a single event may trigger a cascade of
``GtkGestures``, both across the parents of the widget receiving the event and
in parallel within an individual widget. It is a responsibility of the
widgets using those gestures to set the state of touch sequences accordingly
in order to enable cooperation of gestures around the ``GdkEventSequences``
triggering those.

Within a widget, gestures can be grouped through `GestureExt::group`,
grouped gestures synchronize the state of sequences, so calling
`GestureExt::set_sequence_state` on one will effectively propagate
the state throughout the group.

By default, all sequences start out in the `EventSequenceState::None` state,
sequences in this state trigger the gesture event handler, but event
propagation will continue unstopped by gestures.

If a sequence enters into the `EventSequenceState::Denied` state, the gesture
group will effectively ignore the sequence, letting events go unstopped
through the gesture, but the "slot" will still remain occupied while
the touch is active.

If a sequence enters in the `EventSequenceState::Claimed` state, the gesture
group will grab all interaction on the sequence, by:
- Setting the same sequence to `EventSequenceState::Denied` on every other gesture
 group within the widget, and every gesture on parent widgets in the propagation
 chain.
- calling `Gesture::cancel` on every gesture in widgets underneath in the
 propagation chain.
- Stopping event propagation after the gesture group handles the event.

Note: if a sequence is set early to `EventSequenceState::Claimed` on
`gdk::EventType::TouchBegin`/`gdk::EventType::ButtonPress` (so those events are captured before
reaching the event widget, this implies `PropagationPhase::Capture`), one similar
event will emulated if the sequence changes to `EventSequenceState::Denied`.
This way event coherence is preserved before event propagation is unstopped
again.

Sequence states can't be changed freely, see `GestureExt::set_sequence_state`
to know about the possible lifetimes of a `gdk::EventSequence`.

## Touchpad gestures

On the platforms that support it, `Gesture` will handle transparently
touchpad gesture events. The only precautions users of `Gesture` should do
to enable this support are:
- Enabling `gdk::EventMask::TouchpadGestureMask` on their ``GdkWindows``
- If the gesture has `PropagationPhase::None`, ensuring events of type
 `gdk::EventType::TouchpadSwipe` and `gdk::EventType::TouchpadPinch` are handled by the `Gesture`

# Implements

[`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait GestureExt -->
Trait containing all `Gesture` methods.

# Implementors

[`GestureRotate`](struct.GestureRotate.html), [`GestureSingle`](struct.GestureSingle.html), [`GestureZoom`](struct.GestureZoom.html), [`Gesture`](struct.Gesture.html)
<!-- trait GestureExt::fn get_bounding_box -->
If there are touch sequences being currently handled by `self`,
this function returns `true` and fills in `rect` with the bounding
box containing all active touches. Otherwise, `false` will be
returned.

Note: This function will yield unexpected results on touchpad
gestures. Since there is no correlation between physical and
pixel distances, these will look as if constrained in an
infinitely small area, `rect` width and height will thus be 0
regardless of the number of touchpoints.
## `rect`
bounding box containing all active touches.

# Returns

`true` if there are active touches, `false` otherwise
<!-- trait GestureExt::fn get_bounding_box_center -->
If there are touch sequences being currently handled by `self`,
this function returns `true` and fills in `x` and `y` with the center
of the bounding box containing all active touches. Otherwise, `false`
will be returned.
## `x`
X coordinate for the bounding box center
## `y`
Y coordinate for the bounding box center

# Returns

`false` if no active touches are present, `true` otherwise
<!-- trait GestureExt::fn get_device -->
Returns the master `gdk::Device` that is currently operating
on `self`, or `None` if the gesture is not being interacted.

# Returns

a `gdk::Device`, or `None`
<!-- trait GestureExt::fn get_group -->
Returns all gestures in the group of `self`

# Returns

The list
 of ``GtkGestures``, free with `glib::List::free`
<!-- trait GestureExt::fn get_last_event -->
Returns the last event that was processed for `sequence`.

Note that the returned pointer is only valid as long as the `sequence`
is still interpreted by the `self`. If in doubt, you should make
a copy of the event.
## `sequence`
a `gdk::EventSequence`

# Returns

The last event from `sequence`
<!-- trait GestureExt::fn get_last_updated_sequence -->
Returns the `gdk::EventSequence` that was last updated on `self`.

# Returns

The last updated sequence
<!-- trait GestureExt::fn get_point -->
If `sequence` is currently being interpreted by `self`, this
function returns `true` and fills in `x` and `y` with the last coordinates
stored for that event sequence. The coordinates are always relative to the
widget allocation.
## `sequence`
a `gdk::EventSequence`, or `None` for pointer events
## `x`
return location for X axis of the sequence coordinates
## `y`
return location for Y axis of the sequence coordinates

# Returns

`true` if `sequence` is currently interpreted
<!-- trait GestureExt::fn get_sequence_state -->
Returns the `sequence` state, as seen by `self`.
## `sequence`
a `gdk::EventSequence`

# Returns

The sequence state in `self`
<!-- trait GestureExt::fn get_sequences -->
Returns the list of ``GdkEventSequences`` currently being interpreted
by `self`.

# Returns

A list
 of ``GdkEventSequences``, the list elements are owned by GTK+
 and must not be freed or modified, the list itself must be deleted
 through `glib::List::free`
<!-- trait GestureExt::fn get_window -->
Returns the user-defined window that receives the events
handled by `self`. See `GestureExt::set_window` for more
information.

# Returns

the user defined window, or `None` if none
<!-- trait GestureExt::fn group -->
Adds `gesture` to the same group than `self`. Gestures
are by default isolated in their own groups.

When gestures are grouped, the state of ``GdkEventSequences``
is kept in sync for all of those, so calling `GestureExt::set_sequence_state`,
on one will transfer the same value to the others.

Groups also perform an "implicit grabbing" of sequences, if a
`gdk::EventSequence` state is set to `EventSequenceState::Claimed` on one group,
every other gesture group attached to the same `Widget` will switch the
state for that sequence to `EventSequenceState::Denied`.
## `gesture`
a `Gesture`
<!-- trait GestureExt::fn handles_sequence -->
Returns `true` if `self` is currently handling events corresponding to
`sequence`.
## `sequence`
a `gdk::EventSequence` or `None`

# Returns

`true` if `self` is handling `sequence`, `false` otherwise
<!-- trait GestureExt::fn is_active -->
Returns `true` if the gesture is currently active.
A gesture is active meanwhile there are touch sequences
interacting with it.

# Returns

`true` if gesture is active
<!-- trait GestureExt::fn is_grouped_with -->
Returns `true` if both gestures pertain to the same group.
## `other`
another `Gesture`

# Returns

whether the gestures are grouped
<!-- trait GestureExt::fn is_recognized -->
Returns `true` if the gesture is currently recognized.
A gesture is recognized if there are as many interacting
touch sequences as required by `self`, and `Gesture::check`
returned `true` for the sequences being currently interpreted.

# Returns

`true` if gesture is recognized
<!-- trait GestureExt::fn set_sequence_state -->
Sets the state of `sequence` in `self`. Sequences start
in state `EventSequenceState::None`, and whenever they change
state, they can never go back to that state. Likewise,
sequences in state `EventSequenceState::Denied` cannot turn
back to a not denied state. With these rules, the lifetime
of an event sequence is constrained to the next four:

* None
* None → Denied
* None → Claimed
* None → Claimed → Denied

Note: Due to event handling ordering, it may be unsafe to
set the state on another gesture within a `Gesture::begin`
signal handler, as the callback might be executed before
the other gesture knows about the sequence. A safe way to
perform this could be:


```text
static void
first_gesture_begin_cb (GtkGesture       *first_gesture,
                        GdkEventSequence *sequence,
                        gpointer          user_data)
{
  gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_CLAIMED);
  gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
}

static void
second_gesture_begin_cb (GtkGesture       *second_gesture,
                         GdkEventSequence *sequence,
                         gpointer          user_data)
{
  if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED)
    gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
}
```

If both gestures are in the same group, just set the state on
the gesture emitting the event, the sequence will be already
be initialized to the group's global state when the second
gesture processes the event.
## `sequence`
a `gdk::EventSequence`
## `state`
the sequence state

# Returns

`true` if `sequence` is handled by `self`,
 and the state is changed successfully
<!-- trait GestureExt::fn set_state -->
Sets the state of all sequences that `self` is currently
interacting with. See `GestureExt::set_sequence_state`
for more details on sequence states.
## `state`
the sequence state

# Returns

`true` if the state of at least one sequence
 was changed successfully
<!-- trait GestureExt::fn set_window -->
Sets a specific window to receive events about, so `self`
will effectively handle only events targeting `window`, or
a child of it. `window` must pertain to `EventControllerExt::get_widget`.
## `window`
a `gdk::Window`, or `None`
<!-- trait GestureExt::fn ungroup -->
Separates `self` into an isolated group.
<!-- trait GestureExt::fn connect_begin -->
This signal is emitted when the gesture is recognized. This means the
number of touch sequences matches `Gesture:n-points`, and the `Gesture::check`
handler(s) returned `true`.

Note: These conditions may also happen when an extra touch (eg. a third touch
on a 2-touches gesture) is lifted, in that situation `sequence` won't pertain
to the current set of active touches, so don't rely on this being true.
## `sequence`
the `gdk::EventSequence` that made the gesture to be recognized
<!-- trait GestureExt::fn connect_cancel -->
This signal is emitted whenever a sequence is cancelled. This usually
happens on active touches when `EventControllerExt::reset` is called
on `gesture` (manually, due to grabs...), or the individual `sequence`
was claimed by parent widgets' controllers (see `GestureExt::set_sequence_state`).

`gesture` must forget everything about `sequence` as a reaction to this signal.
## `sequence`
the `gdk::EventSequence` that was cancelled
<!-- trait GestureExt::fn connect_end -->
This signal is emitted when `gesture` either stopped recognizing the event
sequences as something to be handled (the `Gesture::check` handler returned
`false`), or the number of touch sequences became higher or lower than
`Gesture:n-points`.

Note: `sequence` might not pertain to the group of sequences that were
previously triggering recognition on `gesture` (ie. a just pressed touch
sequence that exceeds `Gesture:n-points`). This situation may be detected
by checking through `GestureExt::handles_sequence`.
## `sequence`
the `gdk::EventSequence` that made gesture recognition to finish
<!-- trait GestureExt::fn connect_sequence_state_changed -->
This signal is emitted whenever a sequence state changes. See
`GestureExt::set_sequence_state` to know more about the expectable
sequence lifetimes.
## `sequence`
the `gdk::EventSequence` that was cancelled
## `state`
the new sequence state
<!-- trait GestureExt::fn connect_update -->
This signal is emitted whenever an event is handled while the gesture is
recognized. `sequence` is guaranteed to pertain to the set of active touches.
## `sequence`
the `gdk::EventSequence` that was updated
<!-- trait GestureExt::fn get_property_n_points -->
The number of touch points that trigger recognition on this gesture,
<!-- trait GestureExt::fn set_property_n_points -->
The number of touch points that trigger recognition on this gesture,
<!-- trait GestureExt::fn get_property_window -->
If non-`None`, the gesture will only listen for events that happen on
this `gdk::Window`, or a child of it.
<!-- trait GestureExt::fn set_property_window -->
If non-`None`, the gesture will only listen for events that happen on
this `gdk::Window`, or a child of it.
<!-- struct GestureDrag -->
`GestureDrag` is a `Gesture` implementation that recognizes drag
operations. The drag operation itself can be tracked throught the
`GestureDrag::drag-begin`, `GestureDrag::drag-update` and
`GestureDrag::drag-end` signals, or the relevant coordinates be
extracted through `GestureDragExt::get_offset` and
`GestureDragExt::get_start_point`.

# Implements

[`GestureDragExt`](trait.GestureDragExt.html), [`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait GestureDragExt -->
Trait containing all `GestureDrag` methods.

# Implementors

[`GestureDrag`](struct.GestureDrag.html), [`GesturePan`](struct.GesturePan.html)
<!-- impl GestureDrag::fn new -->
Returns a newly created `Gesture` that recognizes drags.
## `widget`
a `Widget`

# Returns

a newly created `GestureDrag`
<!-- trait GestureDragExt::fn get_offset -->
If the `self` is active, this function returns `true` and
fills in `x` and `y` with the coordinates of the current point,
as an offset to the starting drag point.
## `x`
X offset for the current point
## `y`
Y offset for the current point

# Returns

`true` if the gesture is active
<!-- trait GestureDragExt::fn get_start_point -->
If the `self` is active, this function returns `true`
and fills in `x` and `y` with the drag start coordinates,
in window-relative coordinates.
## `x`
X coordinate for the drag start point
## `y`
Y coordinate for the drag start point

# Returns

`true` if the gesture is active
<!-- trait GestureDragExt::fn connect_drag_begin -->
This signal is emitted whenever dragging starts.
## `start_x`
X coordinate, relative to the widget allocation
## `start_y`
Y coordinate, relative to the widget allocation
<!-- trait GestureDragExt::fn connect_drag_end -->
This signal is emitted whenever the dragging is finished.
## `offset_x`
X offset, relative to the start point
## `offset_y`
Y offset, relative to the start point
<!-- trait GestureDragExt::fn connect_drag_update -->
This signal is emitted whenever the dragging point moves.
## `offset_x`
X offset, relative to the start point
## `offset_y`
Y offset, relative to the start point
<!-- struct GestureLongPress -->
`GestureLongPress` is a `Gesture` implementation able to recognize
long presses, triggering the `GestureLongPress::pressed` after the
timeout is exceeded.

If the touchpoint is lifted before the timeout passes, or if it drifts
too far of the initial press point, the `GestureLongPress::cancelled`
signal will be emitted.

# Implements

[`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl GestureLongPress::fn new -->
Returns a newly created `Gesture` that recognizes long presses.
## `widget`
a `Widget`

# Returns

a newly created `GestureLongPress`
<!-- impl GestureLongPress::fn connect_cancelled -->
This signal is emitted whenever a press moved too far, or was released
before `GestureLongPress::pressed` happened.
<!-- impl GestureLongPress::fn connect_pressed -->
This signal is emitted whenever a press goes unmoved/unreleased longer than
what the GTK+ defaults tell.
## `x`
the X coordinate where the press happened, relative to the widget allocation
## `y`
the Y coordinate where the press happened, relative to the widget allocation
<!-- struct GestureMultiPress -->
`GestureMultiPress` is a `Gesture` implementation able to recognize
multiple clicks on a nearby zone, which can be listened for through the
`GestureMultiPress::pressed` signal. Whenever time or distance between
clicks exceed the GTK+ defaults, `GestureMultiPress::stopped` is emitted,
and the click counter is reset.

Callers may also restrict the area that is considered valid for a >1
touch/button press through `GestureMultiPress::set_area`, so any
click happening outside that area is considered to be a first click of
its own.

# Implements

[`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl GestureMultiPress::fn new -->
Returns a newly created `Gesture` that recognizes single and multiple
presses.
## `widget`
a `Widget`

# Returns

a newly created `GestureMultiPress`
<!-- impl GestureMultiPress::fn get_area -->
If an area was set through `GestureMultiPress::set_area`,
this function will return `true` and fill in `rect` with the
press area. See `GestureMultiPress::set_area` for more
details on what the press area represents.
## `rect`
return location for the press area

# Returns

`true` if `rect` was filled with the press area
<!-- impl GestureMultiPress::fn set_area -->
If `rect` is non-`None`, the press area will be checked to be
confined within the rectangle, otherwise the button count
will be reset so the press is seen as being the first one.
If `rect` is `None`, the area will be reset to an unrestricted
state.

Note: The rectangle is only used to determine whether any
non-first click falls within the expected area. This is not
akin to an input shape.
## `rect`
rectangle to receive coordinates on
<!-- impl GestureMultiPress::fn connect_pressed -->
This signal is emitted whenever a button or touch press happens.
## `n_press`
how many touch/button presses happened with this one
## `x`
The X coordinate, in widget allocation coordinates
## `y`
The Y coordinate, in widget allocation coordinates
<!-- impl GestureMultiPress::fn connect_released -->
This signal is emitted when a button or touch is released. `n_press`
will report the number of press that is paired to this event, note
that `GestureMultiPress::stopped` may have been emitted between the
press and its release, `n_press` will only start over at the next press.
## `n_press`
number of press that is paired with this release
## `x`
The X coordinate, in widget allocation coordinates
## `y`
The Y coordinate, in widget allocation coordinates
<!-- impl GestureMultiPress::fn connect_stopped -->
This signal is emitted whenever any time/distance threshold has
been exceeded.
<!-- struct GesturePan -->
`GesturePan` is a `Gesture` implementation able to recognize
pan gestures, those are drags that are locked to happen along one
axis. The axis that a `GesturePan` handles is defined at
construct time, and can be changed through
`GesturePan::set_orientation`.

When the gesture starts to be recognized, `GesturePan` will
attempt to determine as early as possible whether the sequence
is moving in the expected direction, and denying the sequence if
this does not happen.

Once a panning gesture along the expected axis is recognized,
the `GesturePan::pan` signal will be emitted as input events
are received, containing the offset in the given axis.

# Implements

[`GestureDragExt`](trait.GestureDragExt.html), [`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl GesturePan::fn new -->
Returns a newly created `Gesture` that recognizes pan gestures.
## `widget`
a `Widget`
## `orientation`
expected orientation

# Returns

a newly created `GesturePan`
<!-- impl GesturePan::fn get_orientation -->
Returns the orientation of the pan gestures that this `self` expects.

# Returns

the expected orientation for pan gestures
<!-- impl GesturePan::fn set_orientation -->
Sets the orientation to be expected on pan gestures.
## `orientation`
expected orientation
<!-- impl GesturePan::fn connect_pan -->
This signal is emitted once a panning gesture along the
expected axis is detected.
## `direction`
current direction of the pan gesture
## `offset`
Offset along the gesture orientation
<!-- impl GesturePan::fn get_property_orientation -->
The expected orientation of pan gestures.
<!-- impl GesturePan::fn set_property_orientation -->
The expected orientation of pan gestures.
<!-- struct GestureRotate -->
`GestureRotate` is a `Gesture` implementation able to recognize
2-finger rotations, whenever the angle between both handled sequences
changes, the `GestureRotate::angle-changed` signal is emitted.

# Implements

[`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl GestureRotate::fn new -->
Returns a newly created `Gesture` that recognizes 2-touch
rotation gestures.
## `widget`
a `Widget`

# Returns

a newly created `GestureRotate`
<!-- impl GestureRotate::fn get_angle_delta -->
If `self` is active, this function returns the angle difference
in radians since the gesture was first recognized. If `self` is
not active, 0 is returned.

# Returns

the angle delta in radians
<!-- impl GestureRotate::fn connect_angle_changed -->
This signal is emitted when the angle between both tracked points
changes.
## `angle`
Current angle in radians
## `angle_delta`
Difference with the starting angle, in radians
<!-- struct GestureSingle -->
`GestureSingle` is a subclass of `Gesture`, optimized (although
not restricted) for dealing with mouse and single-touch gestures. Under
interaction, these gestures stick to the first interacting sequence, which
is accessible through `GestureSingleExt::get_current_sequence` while the
gesture is being interacted with.

By default gestures react to both `GDK_BUTTON_PRIMARY` and touch
events, `GestureSingleExt::set_touch_only` can be used to change the
touch behavior. Callers may also specify a different mouse button number
to interact with through `GestureSingleExt::set_button`, or react to any
mouse button by setting 0. While the gesture is active, the button being
currently pressed can be known through `GestureSingleExt::get_current_button`.

# Implements

[`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait GestureSingleExt -->
Trait containing all `GestureSingle` methods.

# Implementors

[`GestureDrag`](struct.GestureDrag.html), [`GestureLongPress`](struct.GestureLongPress.html), [`GestureMultiPress`](struct.GestureMultiPress.html), [`GestureSingle`](struct.GestureSingle.html), [`GestureStylus`](struct.GestureStylus.html), [`GestureSwipe`](struct.GestureSwipe.html)
<!-- trait GestureSingleExt::fn get_button -->
Returns the button number `self` listens for, or 0 if `self`
reacts to any button press.

# Returns

The button number, or 0 for any button
<!-- trait GestureSingleExt::fn get_current_button -->
Returns the button number currently interacting with `self`, or 0 if there
is none.

# Returns

The current button number
<!-- trait GestureSingleExt::fn get_current_sequence -->
Returns the event sequence currently interacting with `self`.
This is only meaningful if `GestureExt::is_active` returns `true`.

# Returns

the current sequence
<!-- trait GestureSingleExt::fn get_exclusive -->
Gets whether a gesture is exclusive. For more information, see
`GestureSingleExt::set_exclusive`.

# Returns

Whether the gesture is exclusive
<!-- trait GestureSingleExt::fn get_touch_only -->
Returns `true` if the gesture is only triggered by touch events.

# Returns

`true` if the gesture only handles touch events
<!-- trait GestureSingleExt::fn set_button -->
Sets the button number `self` listens to. If non-0, every
button press from a different button number will be ignored.
Touch events implicitly match with button 1.
## `button`
button number to listen to, or 0 for any button
<!-- trait GestureSingleExt::fn set_exclusive -->
Sets whether `self` is exclusive. An exclusive gesture will
only handle pointer and "pointer emulated" touch events, so at
any given time, there is only one sequence able to interact with
those.
## `exclusive`
`true` to make `self` exclusive
<!-- trait GestureSingleExt::fn set_touch_only -->
If `touch_only` is `true`, `self` will only handle events of type
`gdk::EventType::TouchBegin`, `gdk::EventType::TouchUpdate` or `gdk::EventType::TouchEnd`. If `false`,
mouse events will be handled too.
## `touch_only`
whether `self` handles only touch events
<!-- trait GestureSingleExt::fn get_property_button -->
Mouse button number to listen to, or 0 to listen for any button.
<!-- trait GestureSingleExt::fn set_property_button -->
Mouse button number to listen to, or 0 to listen for any button.
<!-- trait GestureSingleExt::fn get_property_exclusive -->
Whether the gesture is exclusive. Exclusive gestures only listen to pointer
and pointer emulated events.
<!-- trait GestureSingleExt::fn set_property_exclusive -->
Whether the gesture is exclusive. Exclusive gestures only listen to pointer
and pointer emulated events.
<!-- trait GestureSingleExt::fn get_property_touch_only -->
Whether the gesture handles only touch events.
<!-- trait GestureSingleExt::fn set_property_touch_only -->
Whether the gesture handles only touch events.
<!-- struct GestureStylus -->
`GestureStylus` is a `Gesture` implementation specific to stylus
input. The provided signals just provide the basic information

Feature: `v3_24`

# Implements

[`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`GestureStylusExtManual`](prelude/trait.GestureStylusExtManual.html)
<!-- impl GestureStylus::fn new -->
Creates a new `GestureStylus`.

Feature: `v3_24`

## `widget`
a `Widget`

# Returns

a newly created stylus gesture
<!-- impl GestureStylus::fn get_axes -->
Returns the current values for the requested `axes`. This function
must be called from either the `GestureStylus:down`,
`GestureStylus:motion`, `GestureStylus:up` or `GestureStylus:proximity`
signals.

Feature: `v3_24`

## `axes`
array of requested axes, terminated with `gdk::AxisUse::Ignore`
## `values`
return location for the axis values

# Returns

`true` if there is a current value for the axes
<!-- impl GestureStylus::fn get_axis -->
Returns the current value for the requested `axis`. This function
must be called from either the `GestureStylus:down`,
`GestureStylus:motion`, `GestureStylus:up` or `GestureStylus:proximity`
signals.

Feature: `v3_24`

## `axis`
requested device axis
## `value`
return location for the axis value

# Returns

`true` if there is a current value for the axis
<!-- impl GestureStylus::fn get_device_tool -->
Returns the `gdk::DeviceTool` currently driving input through this gesture.
This function must be called from either the `GestureStylus::down`,
`GestureStylus::motion`, `GestureStylus::up` or `GestureStylus::proximity`
signal handlers.

Feature: `v3_24`


# Returns

The current stylus tool
<!-- struct GestureSwipe -->
`GestureSwipe` is a `Gesture` implementation able to recognize
swipes, after a press/move/.../move/release sequence happens, the
`GestureSwipe::swipe` signal will be emitted, providing the velocity
and directionality of the sequence at the time it was lifted.

If the velocity is desired in intermediate points,
`GestureSwipe::get_velocity` can be called on eg. a
`Gesture::update` handler.

All velocities are reported in pixels/sec units.

# Implements

[`GestureSingleExt`](trait.GestureSingleExt.html), [`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl GestureSwipe::fn new -->
Returns a newly created `Gesture` that recognizes swipes.
## `widget`
a `Widget`

# Returns

a newly created `GestureSwipe`
<!-- impl GestureSwipe::fn get_velocity -->
If the gesture is recognized, this function returns `true` and fill in
`velocity_x` and `velocity_y` with the recorded velocity, as per the
last event(s) processed.
## `velocity_x`
return value for the velocity in the X axis, in pixels/sec
## `velocity_y`
return value for the velocity in the Y axis, in pixels/sec

# Returns

whether velocity could be calculated
<!-- impl GestureSwipe::fn connect_swipe -->
This signal is emitted when the recognized gesture is finished, velocity
and direction are a product of previously recorded events.
## `velocity_x`
velocity in the X axis, in pixels/sec
## `velocity_y`
velocity in the Y axis, in pixels/sec
<!-- struct GestureZoom -->
`GestureZoom` is a `Gesture` implementation able to recognize
pinch/zoom gestures, whenever the distance between both tracked
sequences changes, the `GestureZoom::scale-changed` signal is
emitted to report the scale factor.

# Implements

[`GestureExt`](trait.GestureExt.html), [`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl GestureZoom::fn new -->
Returns a newly created `Gesture` that recognizes zoom
in/out gestures (usually known as pinch/zoom).
## `widget`
a `Widget`

# Returns

a newly created `GestureZoom`
<!-- impl GestureZoom::fn get_scale_delta -->
If `self` is active, this function returns the zooming difference
since the gesture was recognized (hence the starting point is
considered 1:1). If `self` is not active, 1 is returned.

# Returns

the scale delta
<!-- impl GestureZoom::fn connect_scale_changed -->
This signal is emitted whenever the distance between both tracked
sequences changes.
## `scale`
Scale delta, taking the initial state as 1:1
<!-- struct Grid -->
`Grid` is a container which arranges its child widgets in
rows and columns, with arbitrary positions and horizontal/vertical spans.

Children are added using `GridExt::attach`. They can span multiple
rows or columns. It is also possible to add a child next to an
existing child, using `GridExt::attach_next_to`. The behaviour of
`Grid` when several children occupy the same grid cell is undefined.

`Grid` can be used like a `Box` by just using `ContainerExt::add`,
which will place children next to each other in the direction determined
by the `Orientable:orientation` property. However, if all you want is a
single row or column, then `Box` is the preferred widget.

# CSS nodes

`Grid` uses a single CSS node with name grid.

# Implements

[`GridExt`](trait.GridExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait GridExt -->
Trait containing all `Grid` methods.

# Implementors

[`Grid`](struct.Grid.html)
<!-- impl Grid::fn new -->
Creates a new grid widget.

# Returns

the new `Grid`
<!-- trait GridExt::fn attach -->
Adds a widget to the grid.

The position of `child` is determined by `left` and `top`. The
number of “cells” that `child` will occupy is determined by
`width` and `height`.
## `child`
the widget to add
## `left`
the column number to attach the left side of `child` to
## `top`
the row number to attach the top side of `child` to
## `width`
the number of columns that `child` will span
## `height`
the number of rows that `child` will span
<!-- trait GridExt::fn attach_next_to -->
Adds a widget to the grid.

The widget is placed next to `sibling`, on the side determined by
`side`. When `sibling` is `None`, the widget is placed in row (for
left or right placement) or column 0 (for top or bottom placement),
at the end indicated by `side`.

Attaching widgets labeled [1], [2], [3] with `sibling` == `None` and
`side` == `PositionType::Left` yields a layout of [3][2][1].
## `child`
the widget to add
## `sibling`
the child of `self` that `child` will be placed
 next to, or `None` to place `child` at the beginning or end
## `side`
the side of `sibling` that `child` is positioned next to
## `width`
the number of columns that `child` will span
## `height`
the number of rows that `child` will span
<!-- trait GridExt::fn get_baseline_row -->
Returns which row defines the global baseline of `self`.

# Returns

the row index defining the global baseline
<!-- trait GridExt::fn get_child_at -->
Gets the child of `self` whose area covers the grid
cell whose upper left corner is at `left`, `top`.
## `left`
the left edge of the cell
## `top`
the top edge of the cell

# Returns

the child at the given position, or `None`
<!-- trait GridExt::fn get_column_homogeneous -->
Returns whether all columns of `self` have the same width.

# Returns

whether all columns of `self` have the same width.
<!-- trait GridExt::fn get_column_spacing -->
Returns the amount of space between the columns of `self`.

# Returns

the column spacing of `self`
<!-- trait GridExt::fn get_row_baseline_position -->
Returns the baseline position of `row` as set
by `GridExt::set_row_baseline_position` or the default value
`BaselinePosition::Center`.
## `row`
a row index

# Returns

the baseline position of `row`
<!-- trait GridExt::fn get_row_homogeneous -->
Returns whether all rows of `self` have the same height.

# Returns

whether all rows of `self` have the same height.
<!-- trait GridExt::fn get_row_spacing -->
Returns the amount of space between the rows of `self`.

# Returns

the row spacing of `self`
<!-- trait GridExt::fn insert_column -->
Inserts a column at the specified position.

Children which are attached at or to the right of this position
are moved one column to the right. Children which span across this
position are grown to span the new column.
## `position`
the position to insert the column at
<!-- trait GridExt::fn insert_next_to -->
Inserts a row or column at the specified position.

The new row or column is placed next to `sibling`, on the side
determined by `side`. If `side` is `PositionType::Top` or `PositionType::Bottom`,
a row is inserted. If `side` is `PositionType::Left` of `PositionType::Right`,
a column is inserted.
## `sibling`
the child of `self` that the new row or column will be
 placed next to
## `side`
the side of `sibling` that `child` is positioned next to
<!-- trait GridExt::fn insert_row -->
Inserts a row at the specified position.

Children which are attached at or below this position
are moved one row down. Children which span across this
position are grown to span the new row.
## `position`
the position to insert the row at
<!-- trait GridExt::fn remove_column -->
Removes a column from the grid.

Children that are placed in this column are removed,
spanning children that overlap this column have their
width reduced by one, and children after the column
are moved to the left.
## `position`
the position of the column to remove
<!-- trait GridExt::fn remove_row -->
Removes a row from the grid.

Children that are placed in this row are removed,
spanning children that overlap this row have their
height reduced by one, and children below the row
are moved up.
## `position`
the position of the row to remove
<!-- trait GridExt::fn set_baseline_row -->
Sets which row defines the global baseline for the entire grid.
Each row in the grid can have its own local baseline, but only
one of those is global, meaning it will be the baseline in the
parent of the `self`.
## `row`
the row index
<!-- trait GridExt::fn set_column_homogeneous -->
Sets whether all columns of `self` will have the same width.
## `homogeneous`
`true` to make columns homogeneous
<!-- trait GridExt::fn set_column_spacing -->
Sets the amount of space between columns of `self`.
## `spacing`
the amount of space to insert between columns
<!-- trait GridExt::fn set_row_baseline_position -->
Sets how the baseline should be positioned on `row` of the
grid, in case that row is assigned more space than is requested.
## `row`
a row index
## `pos`
a `BaselinePosition`
<!-- trait GridExt::fn set_row_homogeneous -->
Sets whether all rows of `self` will have the same height.
## `homogeneous`
`true` to make rows homogeneous
<!-- trait GridExt::fn set_row_spacing -->
Sets the amount of space between rows of `self`.
## `spacing`
the amount of space to insert between rows
<!-- struct HeaderBar -->
`HeaderBar` is similar to a horizontal `Box`. It allows children to
be placed at the start or the end. In addition, it allows a title and
subtitle to be displayed. The title will be centered with respect to
the width of the box, even if the children at either side take up
different amounts of space. The height of the titlebar will be
set to provide sufficient space for the subtitle, even if none is
currently set. If a subtitle is not needed, the space reservation
can be turned off with `HeaderBarExt::set_has_subtitle`.

`HeaderBar` can add typical window frame controls, such as minimize,
maximize and close buttons, or the window icon.

For these reasons, `HeaderBar` is the natural choice for use as the custom
titlebar widget of a `Window` (see `GtkWindowExt::set_titlebar`), as it gives
features typical of titlebars while allowing the addition of child widgets.

# Implements

[`HeaderBarExt`](trait.HeaderBarExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait HeaderBarExt -->
Trait containing all `HeaderBar` methods.

# Implementors

[`HeaderBar`](struct.HeaderBar.html)
<!-- impl HeaderBar::fn new -->
Creates a new `HeaderBar` widget.

# Returns

a new `HeaderBar`
<!-- trait HeaderBarExt::fn get_custom_title -->
Retrieves the custom title widget of the header. See
`HeaderBarExt::set_custom_title`.

# Returns

the custom title widget
 of the header, or `None` if none has been set explicitly.
<!-- trait HeaderBarExt::fn get_decoration_layout -->
Gets the decoration layout set with
`HeaderBarExt::set_decoration_layout`.

# Returns

the decoration layout
<!-- trait HeaderBarExt::fn get_has_subtitle -->
Retrieves whether the header bar reserves space for
a subtitle, regardless if one is currently set or not.

# Returns

`true` if the header bar reserves space
 for a subtitle
<!-- trait HeaderBarExt::fn get_show_close_button -->
Returns whether this header bar shows the standard window
decorations.

# Returns

`true` if the decorations are shown
<!-- trait HeaderBarExt::fn get_subtitle -->
Retrieves the subtitle of the header. See `HeaderBarExt::set_subtitle`.

# Returns

the subtitle of the header, or `None` if none has
 been set explicitly. The returned string is owned by the widget
 and must not be modified or freed.
<!-- trait HeaderBarExt::fn get_title -->
Retrieves the title of the header. See `HeaderBarExt::set_title`.

# Returns

the title of the header, or `None` if none has
 been set explicitly. The returned string is owned by the widget
 and must not be modified or freed.
<!-- trait HeaderBarExt::fn pack_end -->
Adds `child` to `self`, packed with reference to the
end of the `self`.
## `child`
the `Widget` to be added to `self`
<!-- trait HeaderBarExt::fn pack_start -->
Adds `child` to `self`, packed with reference to the
start of the `self`.
## `child`
the `Widget` to be added to `self`
<!-- trait HeaderBarExt::fn set_custom_title -->
Sets a custom title for the `HeaderBar`.

The title should help a user identify the current view. This
supersedes any title set by `HeaderBarExt::set_title` or
`HeaderBarExt::set_subtitle`. To achieve the same style as
the builtin title and subtitle, use the “title” and “subtitle”
style classes.

You should set the custom title to `None`, for the header title
label to be visible again.
## `title_widget`
a custom widget to use for a title
<!-- trait HeaderBarExt::fn set_decoration_layout -->
Sets the decoration layout for this header bar, overriding
the `Settings:gtk-decoration-layout` setting.

There can be valid reasons for overriding the setting, such
as a header bar design that does not allow for buttons to take
room on the right, or only offers room for a single close button.
Split header bars are another example for overriding the
setting.

The format of the string is button names, separated by commas.
A colon separates the buttons that should appear on the left
from those on the right. Recognized button names are minimize,
maximize, close, icon (the window icon) and menu (a menu button
for the fallback app menu).

For example, “menu:minimize,maximize,close” specifies a menu
on the left, and minimize, maximize and close buttons on the right.
## `layout`
a decoration layout, or `None` to
 unset the layout
<!-- trait HeaderBarExt::fn set_has_subtitle -->
Sets whether the header bar should reserve space
for a subtitle, even if none is currently set.
## `setting`
`true` to reserve space for a subtitle
<!-- trait HeaderBarExt::fn set_show_close_button -->
Sets whether this header bar shows the standard window decorations,
including close, maximize, and minimize.
## `setting`
`true` to show standard window decorations
<!-- trait HeaderBarExt::fn set_subtitle -->
Sets the subtitle of the `HeaderBar`. The title should give a user
an additional detail to help him identify the current view.

Note that `HeaderBar` by default reserves room for the subtitle,
even if none is currently set. If this is not desired, set the
`HeaderBar:has-subtitle` property to `false`.
## `subtitle`
a subtitle, or `None`
<!-- trait HeaderBarExt::fn set_title -->
Sets the title of the `HeaderBar`. The title should help a user
identify the current view. A good title should not include the
application name.
## `title`
a title, or `None`
<!-- trait HeaderBarExt::fn get_property_decoration_layout -->
The decoration layout for buttons. If this property is
not set, the `Settings:gtk-decoration-layout` setting
is used.

See `HeaderBarExt::set_decoration_layout` for information
about the format of this string.
<!-- trait HeaderBarExt::fn set_property_decoration_layout -->
The decoration layout for buttons. If this property is
not set, the `Settings:gtk-decoration-layout` setting
is used.

See `HeaderBarExt::set_decoration_layout` for information
about the format of this string.
<!-- trait HeaderBarExt::fn get_property_decoration_layout_set -->
Set to `true` if `HeaderBar:decoration-layout` is set.
<!-- trait HeaderBarExt::fn set_property_decoration_layout_set -->
Set to `true` if `HeaderBar:decoration-layout` is set.
<!-- trait HeaderBarExt::fn get_property_has_subtitle -->
If `true`, reserve space for a subtitle, even if none
is currently set.
<!-- trait HeaderBarExt::fn set_property_has_subtitle -->
If `true`, reserve space for a subtitle, even if none
is currently set.
<!-- trait HeaderBarExt::fn get_property_show_close_button -->
Whether to show window decorations.

Which buttons are actually shown and where is determined
by the `HeaderBar:decoration-layout` property, and by
the state of the window (e.g. a close button will not be
shown if the window can't be closed).
<!-- trait HeaderBarExt::fn set_property_show_close_button -->
Whether to show window decorations.

Which buttons are actually shown and where is determined
by the `HeaderBar:decoration-layout` property, and by
the state of the window (e.g. a close button will not be
shown if the window can't be closed).
<!-- struct IMContext -->
`IMContext` defines the interface for GTK+ input methods. An input method
is used by GTK+ text input widgets like `Entry` to map from key events to
Unicode character strings.

The default input method can be set programmatically via the
`Settings:gtk-im-module` `Settings` property. Alternatively, you may set
the GTK_IM_MODULE environment variable as documented in
[Running GTK+ Applications][gtk-running].

The `Entry` `Entry:im-module` and `TextView` `TextView:im-module`
properties may also be used to set input methods for specific widget
instances. For instance, a certain entry widget might be expected to contain
certain characters which would be easier to input with a certain input
method.

An input method may consume multiple key events in sequence and finally
output the composed result. This is called preediting, and an input method
may provide feedback about this process by displaying the intermediate
composition states as preedit text. For instance, the default GTK+ input
method implements the input of arbitrary Unicode code points by holding down
the Control and Shift keys and then typing “U” followed by the hexadecimal
digits of the code point. When releasing the Control and Shift keys,
preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for
example results in the € sign.

Additional input methods can be made available for use by GTK+ widgets as
loadable modules. An input method module is a small shared library which
implements a subclass of `IMContext` or `IMContextSimple` and exports
these four functions:


```C
void im_module_init(GTypeModule *module);
```
This function should register the `glib::Type` of the `IMContext` subclass which
implements the input method by means of `gobject::TypeModule::register_type`. Note
that `g_type_register_static` cannot be used as the type needs to be
registered dynamically.


```C
void im_module_exit(void);
```
Here goes any cleanup code your input method might require on module unload.


```C
void im_module_list(const GtkIMContextInfo ***contexts, int *n_contexts)
{
  *contexts = info_list;
  *n_contexts = G_N_ELEMENTS (info_list);
}
```
This function returns the list of input methods provided by the module. The
example implementation above shows a common solution and simply returns a
pointer to statically defined array of `IMContextInfo` items for each
provided input method.


```C
GtkIMContext * im_module_create(const gchar *context_id);
```
This function should return a pointer to a newly created instance of the
`IMContext` subclass identified by `context_id`. The context ID is the same
as specified in the `IMContextInfo` array returned by `im_module_list`.

After a new loadable input method module has been installed on the system,
the configuration file `gtk.immodules` needs to be
regenerated by [gtk-query-immodules-3.0][gtk-query-immodules-3.0],
in order for the new input method to become available to GTK+ applications.

# Implements

[`IMContextExt`](trait.IMContextExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait IMContextExt -->
Trait containing all `IMContext` methods.

# Implementors

[`IMContextSimple`](struct.IMContextSimple.html), [`IMContext`](struct.IMContext.html), [`IMMulticontext`](struct.IMMulticontext.html)
<!-- trait IMContextExt::fn delete_surrounding -->
Asks the widget that the input context is attached to to delete
characters around the cursor position by emitting the
`IMContext`::delete_surrounding signal. Note that `offset` and `n_chars`
are in characters not in bytes which differs from the usage other
places in `IMContext`.

In order to use this function, you should first call
`IMContextExt::get_surrounding` to get the current context, and
call this function immediately afterwards to make sure that you
know what you are deleting. You should also account for the fact
that even if the signal was handled, the input context might not
have deleted all the characters that were requested to be deleted.

This function is used by an input method that wants to make
subsitutions in the existing text in response to new input. It is
not useful for applications.
## `offset`
offset from cursor position in chars;
 a negative value means start before the cursor.
## `n_chars`
number of characters to delete.

# Returns

`true` if the signal was handled.
<!-- trait IMContextExt::fn filter_keypress -->
Allow an input method to internally handle key press and release
events. If this function returns `true`, then no further processing
should be done for this key event.
## `event`
the key event

# Returns

`true` if the input method handled the key event.
<!-- trait IMContextExt::fn focus_in -->
Notify the input method that the widget to which this
input context corresponds has gained focus. The input method
may, for example, change the displayed feedback to reflect
this change.
<!-- trait IMContextExt::fn focus_out -->
Notify the input method that the widget to which this
input context corresponds has lost focus. The input method
may, for example, change the displayed feedback or reset the contexts
state to reflect this change.
<!-- trait IMContextExt::fn get_preedit_string -->
Retrieve the current preedit string for the input context,
and a list of attributes to apply to the string.
This string should be displayed inserted at the insertion
point.
## `str`
location to store the retrieved
 string. The string retrieved must be freed with `g_free`.
## `attrs`
location to store the retrieved
 attribute list. When you are done with this list, you
 must unreference it with `pango::AttrList::unref`.
## `cursor_pos`
location to store position of cursor (in characters)
 within the preedit string.
<!-- trait IMContextExt::fn get_surrounding -->
Retrieves context around the insertion point. Input methods
typically want context in order to constrain input text based on
existing text; this is important for languages such as Thai where
only some sequences of characters are allowed.

This function is implemented by emitting the
`IMContext`::retrieve_surrounding signal on the input method; in
response to this signal, a widget should provide as much context as
is available, up to an entire paragraph, by calling
`IMContextExt::set_surrounding`. Note that there is no obligation
for a widget to respond to the ::retrieve_surrounding signal, so input
methods must be prepared to function without context.
## `text`
location to store a UTF-8 encoded
 string of text holding context around the insertion point.
 If the function returns `true`, then you must free the result
 stored in this location with `g_free`.
## `cursor_index`
location to store byte index of the insertion
 cursor within `text`.

# Returns

`true` if surrounding text was provided; in this case
 you must free the result stored in *text.
<!-- trait IMContextExt::fn reset -->
Notify the input method that a change such as a change in cursor
position has been made. This will typically cause the input
method to clear the preedit state.
<!-- trait IMContextExt::fn set_client_window -->
Set the client window for the input context; this is the
`gdk::Window` in which the input appears. This window is
used in order to correctly position status windows, and may
also be used for purposes internal to the input method.
## `window`
the client window. This may be `None` to indicate
 that the previous client window no longer exists.
<!-- trait IMContextExt::fn set_cursor_location -->
Notify the input method that a change in cursor
position has been made. The location is relative to the client
window.
## `area`
new location
<!-- trait IMContextExt::fn set_surrounding -->
Sets surrounding context around the insertion point and preedit
string. This function is expected to be called in response to the
`IMContext`::retrieve_surrounding signal, and will likely have no
effect if called at other times.
## `text`
text surrounding the insertion point, as UTF-8.
 the preedit string should not be included within
 `text`.
## `len`
the length of `text`, or -1 if `text` is nul-terminated
## `cursor_index`
the byte index of the insertion cursor within `text`.
<!-- trait IMContextExt::fn set_use_preedit -->
Sets whether the IM context should use the preedit string
to display feedback. If `use_preedit` is FALSE (default
is TRUE), then the IM context may use some other method to display
feedback, such as displaying it in a child of the root window.
## `use_preedit`
whether the IM context should use the preedit string.
<!-- trait IMContextExt::fn connect_commit -->
The ::commit signal is emitted when a complete input sequence
has been entered by the user. This can be a single character
immediately after a key press or the final result of preediting.
## `str`
the completed character(s) entered by the user
<!-- trait IMContextExt::fn connect_delete_surrounding -->
The ::delete-surrounding signal is emitted when the input method
needs to delete all or part of the context surrounding the cursor.
## `offset`
the character offset from the cursor position of the text
 to be deleted. A negative value indicates a position before
 the cursor.
## `n_chars`
the number of characters to be deleted

# Returns

`true` if the signal was handled.
<!-- trait IMContextExt::fn connect_preedit_changed -->
The ::preedit-changed signal is emitted whenever the preedit sequence
currently being entered has changed. It is also emitted at the end of
a preedit sequence, in which case
`IMContextExt::get_preedit_string` returns the empty string.
<!-- trait IMContextExt::fn connect_preedit_end -->
The ::preedit-end signal is emitted when a preediting sequence
has been completed or canceled.
<!-- trait IMContextExt::fn connect_preedit_start -->
The ::preedit-start signal is emitted when a new preediting sequence
starts.
<!-- trait IMContextExt::fn connect_retrieve_surrounding -->
The ::retrieve-surrounding signal is emitted when the input method
requires the context surrounding the cursor. The callback should set
the input method surrounding context by calling the
`IMContextExt::set_surrounding` method.

# Returns

`true` if the signal was handled.
<!-- struct IMContextSimple -->
`IMContextSimple` is a simple input method context supporting table-based
input methods. It has a built-in table of compose sequences that is derived
from the X11 Compose files.

`IMContextSimple` reads additional compose sequences from the first of the
following files that is found: ~/.config/gtk-3.0/Compose, ~/.XCompose,
/usr/share/X11/locale/$locale/Compose (for locales that have a nontrivial
Compose file). The syntax of these files is described in the Compose(5)
manual page.

`IMContextSimple` also supports numeric entry of Unicode characters
by typing Ctrl-Shift-u, followed by a hexadecimal Unicode codepoint.
For example, Ctrl-Shift-u 1 2 3 Enter yields U+0123 LATIN SMALL LETTER
G WITH CEDILLA, i.e. ģ.

# Implements

[`IMContextExt`](trait.IMContextExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IMContextSimpleExtManual`](prelude/trait.IMContextSimpleExtManual.html)
<!-- impl IMContextSimple::fn new -->
Creates a new `IMContextSimple`.

# Returns

a new `IMContextSimple`.
<!-- impl IMContextSimple::fn add_table -->
Adds an additional table to search to the input context.
Each row of the table consists of `max_seq_len` key symbols
followed by two `guint16` interpreted as the high and low
words of a `gunicode` value. Tables are searched starting
from the last added.

The table must be sorted in dictionary order on the
numeric value of the key symbol fields. (Values beyond
the length of the sequence should be zero.)
## `data`
the table
## `max_seq_len`
Maximum length of a sequence in the table
 (cannot be greater than `GTK_MAX_COMPOSE_LEN`)
## `n_seqs`
number of sequences in the table
<!-- struct IMMulticontext -->


# Implements

[`IMMulticontextExt`](trait.IMMulticontextExt.html), [`IMContextExt`](trait.IMContextExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait IMMulticontextExt -->
Trait containing all `IMMulticontext` methods.

# Implementors

[`IMMulticontext`](struct.IMMulticontext.html)
<!-- impl IMMulticontext::fn new -->
Creates a new `IMMulticontext`.

# Returns

a new `IMMulticontext`.
<!-- trait IMMulticontextExt::fn get_context_id -->
Gets the id of the currently active slave of the `self`.

# Returns

the id of the currently active slave
<!-- trait IMMulticontextExt::fn set_context_id -->
Sets the context id for `self`.

This causes the currently active slave of `self` to be
replaced by the slave corresponding to the new context id.
## `context_id`
the id to use
<!-- struct IconInfo -->
Contains information found when looking up an icon in
an icon theme.

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl IconInfo::fn new_for_pixbuf -->
Creates a `IconInfo` for a `gdk_pixbuf::Pixbuf`.
## `icon_theme`
a `IconTheme`
## `pixbuf`
the pixbuf to wrap in a `IconInfo`

# Returns

a `IconInfo`
<!-- impl IconInfo::fn get_base_scale -->
Gets the base scale for the icon. The base scale is a scale
for the icon that was specified by the icon theme creator.
For instance an icon drawn for a high-dpi screen with window
scale 2 for a base size of 32 will be 64 pixels tall and have
a base scale of 2.

# Returns

the base scale
<!-- impl IconInfo::fn get_base_size -->
Gets the base size for the icon. The base size
is a size for the icon that was specified by
the icon theme creator. This may be different
than the actual size of image; an example of
this is small emblem icons that can be attached
to a larger icon. These icons will be given
the same base size as the larger icons to which
they are attached.

Note that for scaled icons the base size does
not include the base scale.

# Returns

the base size, or 0, if no base
 size is known for the icon.
<!-- impl IconInfo::fn get_filename -->
Gets the filename for the icon. If the `IconLookupFlags::UseBuiltin`
flag was passed to `IconThemeExt::lookup_icon`, there may be no
filename if a builtin icon is returned; in this case, you should
use `IconInfo::get_builtin_pixbuf`.

# Returns

the filename for the icon, or `None`
 if `IconInfo::get_builtin_pixbuf` should be used instead.
 The return value is owned by GTK+ and should not be modified
 or freed.
<!-- impl IconInfo::fn is_symbolic -->
Checks if the icon is symbolic or not. This currently uses only
the file name and not the file contents for determining this.
This behaviour may change in the future.

# Returns

`true` if the icon is symbolic, `false` otherwise
<!-- impl IconInfo::fn load_icon -->
Renders an icon previously looked up in an icon theme using
`IconThemeExt::lookup_icon`; the size will be based on the size
passed to `IconThemeExt::lookup_icon`. Note that the resulting
pixbuf may not be exactly this size; an icon theme may have icons
that differ slightly from their nominal sizes, and in addition GTK+
will avoid scaling icons that it considers sufficiently close to the
requested size or for which the source image would have to be scaled
up too far. (This maintains sharpness.). This behaviour can be changed
by passing the `IconLookupFlags::ForceSize` flag when obtaining
the `IconInfo`. If this flag has been specified, the pixbuf
returned by this function will be scaled to the exact size.

# Returns

the rendered icon; this may be a newly
 created icon or a new reference to an internal icon, so you must
 not modify the icon. Use `gobject::ObjectExt::unref` to release your reference
 to the icon.
<!-- impl IconInfo::fn load_icon_async -->
Asynchronously load, render and scale an icon previously looked up
from the icon theme using `IconThemeExt::lookup_icon`.

For more details, see `IconInfo::load_icon` which is the synchronous
version of this call.
## `cancellable`
optional `gio::Cancellable` object, `None` to ignore
## `callback`
a `GAsyncReadyCallback` to call when the
 request is satisfied
## `user_data`
the data to pass to callback function
<!-- impl IconInfo::fn load_icon_finish -->
Finishes an async icon load, see `IconInfo::load_icon_async`.
## `res`
a `gio::AsyncResult`

# Returns

the rendered icon; this may be a newly
 created icon or a new reference to an internal icon, so you must
 not modify the icon. Use `gobject::ObjectExt::unref` to release your reference
 to the icon.
<!-- impl IconInfo::fn load_surface -->
Renders an icon previously looked up in an icon theme using
`IconThemeExt::lookup_icon`; the size will be based on the size
passed to `IconThemeExt::lookup_icon`. Note that the resulting
surface may not be exactly this size; an icon theme may have icons
that differ slightly from their nominal sizes, and in addition GTK+
will avoid scaling icons that it considers sufficiently close to the
requested size or for which the source image would have to be scaled
up too far. (This maintains sharpness.). This behaviour can be changed
by passing the `IconLookupFlags::ForceSize` flag when obtaining
the `IconInfo`. If this flag has been specified, the pixbuf
returned by this function will be scaled to the exact size.
## `for_window`
`gdk::Window` to optimize drawing for, or `None`

# Returns

the rendered icon; this may be a newly
 created icon or a new reference to an internal icon, so you must
 not modify the icon. Use `cairo_surface_destroy` to release your
 reference to the icon.
<!-- impl IconInfo::fn load_symbolic -->
Loads an icon, modifying it to match the system colours for the foreground,
success, warning and error colors provided. If the icon is not a symbolic
one, the function will return the result from `IconInfo::load_icon`.

This allows loading symbolic icons that will match the system theme.

Unless you are implementing a widget, you will want to use
`gio::ThemedIcon::new_with_default_fallbacks` to load the icon.

As implementation details, the icon loaded needs to be of SVG type,
contain the “symbolic” term as the last component of the icon name,
and use the “fg”, “success”, “warning” and “error” CSS styles in the
SVG file itself.

See the [Symbolic Icons Specification](http://www.freedesktop.org/wiki/SymbolicIcons)
for more information about symbolic icons.
## `fg`
a `gdk::RGBA` representing the foreground color of the icon
## `success_color`
a `gdk::RGBA` representing the warning color
 of the icon or `None` to use the default color
## `warning_color`
a `gdk::RGBA` representing the warning color
 of the icon or `None` to use the default color
## `error_color`
a `gdk::RGBA` representing the error color
 of the icon or `None` to use the default color (allow-none)
## `was_symbolic`
a `gboolean`, returns whether the
 loaded icon was a symbolic one and whether the `fg` color was
 applied to it.

# Returns

a `gdk_pixbuf::Pixbuf` representing the loaded icon
<!-- impl IconInfo::fn load_symbolic_async -->
Asynchronously load, render and scale a symbolic icon previously looked up
from the icon theme using `IconThemeExt::lookup_icon`.

For more details, see `IconInfo::load_symbolic` which is the synchronous
version of this call.
## `fg`
a `gdk::RGBA` representing the foreground color of the icon
## `success_color`
a `gdk::RGBA` representing the warning color
 of the icon or `None` to use the default color
## `warning_color`
a `gdk::RGBA` representing the warning color
 of the icon or `None` to use the default color
## `error_color`
a `gdk::RGBA` representing the error color
 of the icon or `None` to use the default color (allow-none)
## `cancellable`
optional `gio::Cancellable` object,
 `None` to ignore
## `callback`
a `GAsyncReadyCallback` to call when the
 request is satisfied
## `user_data`
the data to pass to callback function
<!-- impl IconInfo::fn load_symbolic_finish -->
Finishes an async icon load, see `IconInfo::load_symbolic_async`.
## `res`
a `gio::AsyncResult`
## `was_symbolic`
a `gboolean`, returns whether the
 loaded icon was a symbolic one and whether the `fg` color was
 applied to it.

# Returns

the rendered icon; this may be a newly
 created icon or a new reference to an internal icon, so you must
 not modify the icon. Use `gobject::ObjectExt::unref` to release your reference
 to the icon.
<!-- impl IconInfo::fn load_symbolic_for_context -->
Loads an icon, modifying it to match the system colors for the foreground,
success, warning and error colors provided. If the icon is not a symbolic
one, the function will return the result from `IconInfo::load_icon`.
This function uses the regular foreground color and the symbolic colors
with the names “success_color”, “warning_color” and “error_color” from
the context.

This allows loading symbolic icons that will match the system theme.

See `IconInfo::load_symbolic` for more details.
## `context`
a `StyleContext`
## `was_symbolic`
a `gboolean`, returns whether the
 loaded icon was a symbolic one and whether the `fg` color was
 applied to it.

# Returns

a `gdk_pixbuf::Pixbuf` representing the loaded icon
<!-- impl IconInfo::fn load_symbolic_for_context_async -->
Asynchronously load, render and scale a symbolic icon previously
looked up from the icon theme using `IconThemeExt::lookup_icon`.

For more details, see `IconInfo::load_symbolic_for_context`
which is the synchronous version of this call.
## `context`
a `StyleContext`
## `cancellable`
optional `gio::Cancellable` object,
 `None` to ignore
## `callback`
a `GAsyncReadyCallback` to call when the
 request is satisfied
## `user_data`
the data to pass to callback function
<!-- impl IconInfo::fn load_symbolic_for_context_finish -->
Finishes an async icon load, see `IconInfo::load_symbolic_for_context_async`.
## `res`
a `gio::AsyncResult`
## `was_symbolic`
a `gboolean`, returns whether the
 loaded icon was a symbolic one and whether the `fg` color was
 applied to it.

# Returns

the rendered icon; this may be a newly
 created icon or a new reference to an internal icon, so you must
 not modify the icon. Use `gobject::ObjectExt::unref` to release your reference
 to the icon.
<!-- struct IconLookupFlags -->
Used to specify options for `IconThemeExt::lookup_icon`
<!-- struct IconLookupFlags::const NO_SVG -->
Never get SVG icons, even if gdk-pixbuf
 supports them. Cannot be used together with `IconLookupFlags::ForceSvg`.
<!-- struct IconLookupFlags::const FORCE_SVG -->
Get SVG icons, even if gdk-pixbuf
 doesn’t support them.
 Cannot be used together with `IconLookupFlags::NoSvg`.
<!-- struct IconLookupFlags::const USE_BUILTIN -->
When passed to
 `IconThemeExt::lookup_icon` includes builtin icons
 as well as files. For a builtin icon, `IconInfo::get_filename`
 is `None` and you need to call `IconInfo::get_builtin_pixbuf`.
<!-- struct IconLookupFlags::const GENERIC_FALLBACK -->
Try to shorten icon name at '-'
 characters before looking at inherited themes. This flag is only
 supported in functions that take a single icon name. For more general
 fallback, see `IconTheme::choose_icon`. Since 2.12.
<!-- struct IconLookupFlags::const FORCE_SIZE -->
Always get the icon scaled to the
 requested size. Since 2.14.
<!-- struct IconLookupFlags::const FORCE_REGULAR -->
Try to always load regular icons, even
 when symbolic icon names are given. Since 3.14.
<!-- struct IconLookupFlags::const FORCE_SYMBOLIC -->
Try to always load symbolic icons, even
 when regular icon names are given. Since 3.14.
<!-- struct IconLookupFlags::const DIR_LTR -->
Try to load a variant of the icon for left-to-right
 text direction. Since 3.14.
<!-- struct IconLookupFlags::const DIR_RTL -->
Try to load a variant of the icon for right-to-left
 text direction. Since 3.14.
<!-- enum IconSize -->
Built-in stock icon sizes.
<!-- enum IconSize::variant Invalid -->
Invalid size.
<!-- enum IconSize::variant Menu -->
Size appropriate for menus (16px).
<!-- enum IconSize::variant SmallToolbar -->
Size appropriate for small toolbars (16px).
<!-- enum IconSize::variant LargeToolbar -->
Size appropriate for large toolbars (24px)
<!-- enum IconSize::variant Button -->
Size appropriate for buttons (16px)
<!-- enum IconSize::variant Dnd -->
Size appropriate for drag and drop (32px)
<!-- enum IconSize::variant Dialog -->
Size appropriate for dialogs (48px)
<!-- struct IconTheme -->
`IconTheme` provides a facility for looking up icons by name
and size. The main reason for using a name rather than simply
providing a filename is to allow different icons to be used
depending on what “icon theme” is selected
by the user. The operation of icon themes on Linux and Unix
follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec)
There is a fallback icon theme, named `hicolor`, where applications
should install their icons, but additional icon themes can be installed
as operating system vendors and users choose.

Named icons are similar to the deprecated [Stock Items][gtkstock],
and the distinction between the two may be a bit confusing.
A few things to keep in mind:

- Stock images usually are used in conjunction with
 [Stock Items][gtkstock], such as `GTK_STOCK_OK` or
 `GTK_STOCK_OPEN`. Named icons are easier to set up and therefore
 are more useful for new icons that an application wants to
 add, such as application icons or window icons.

- Stock images can only be loaded at the symbolic sizes defined
 by the `IconSize` enumeration, or by custom sizes defined
 by `IconSize::register`, while named icons are more flexible
 and any pixel size can be specified.

- Because stock images are closely tied to stock items, and thus
 to actions in the user interface, stock images may come in
 multiple variants for different widget states or writing
 directions.

A good rule of thumb is that if there is a stock image for what
you want to use, use it, otherwise use a named icon. It turns
out that internally stock images are generally defined in
terms of one or more named icons. (An example of the
more than one case is icons that depend on writing direction;
`GTK_STOCK_GO_FORWARD` uses the two themed icons
“gtk-stock-go-forward-ltr” and “gtk-stock-go-forward-rtl”.)

In many cases, named themes are used indirectly, via `Image`
or stock items, rather than directly, but looking up icons
directly is also simple. The `IconTheme` object acts
as a database of all the icons in the current theme. You
can create new `IconTheme` objects, but it’s much more
efficient to use the standard icon theme for the `gdk::Screen`
so that the icon information is shared with other people
looking up icons.

```C
GError *error = NULL;
GtkIconTheme *icon_theme;
GdkPixbuf *pixbuf;

icon_theme = gtk_icon_theme_get_default ();
pixbuf = gtk_icon_theme_load_icon (icon_theme,
                                   "my-icon-name", // icon name
                                   48, // icon size
                                   0,  // flags
                                   &error);
if (!pixbuf)
  {
    g_warning ("Couldn’t load icon: %s", error->message);
    g_error_free (error);
  }
else
  {
    // Use the pixbuf
    g_object_unref (pixbuf);
  }
```

# Implements

[`IconThemeExt`](trait.IconThemeExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait IconThemeExt -->
Trait containing all `IconTheme` methods.

# Implementors

[`IconTheme`](struct.IconTheme.html)
<!-- impl IconTheme::fn new -->
Creates a new icon theme object. Icon theme objects are used
to lookup up an icon by name in a particular icon theme.
Usually, you’ll want to use `IconTheme::get_default`
or `IconTheme::get_for_screen` rather than creating
a new icon theme object for scratch.

# Returns

the newly created `IconTheme` object.
<!-- impl IconTheme::fn get_default -->
Gets the icon theme for the default screen. See
`IconTheme::get_for_screen`.

# Returns

A unique `IconTheme` associated with
 the default screen. This icon theme is associated with
 the screen and can be used as long as the screen
 is open. Do not ref or unref it.
<!-- impl IconTheme::fn get_for_screen -->
Gets the icon theme object associated with `screen`; if this
function has not previously been called for the given
screen, a new icon theme object will be created and
associated with the screen. Icon theme objects are
fairly expensive to create, so using this function
is usually a better choice than calling than `IconTheme::new`
and setting the screen yourself; by using this function
a single icon theme object will be shared between users.
## `screen`
a `gdk::Screen`

# Returns

A unique `IconTheme` associated with
 the given screen. This icon theme is associated with
 the screen and can be used as long as the screen
 is open. Do not ref or unref it.
<!-- trait IconThemeExt::fn add_resource_path -->
Adds a resource path that will be looked at when looking
for icons, similar to search paths.

This function should be used to make application-specific icons
available as part of the icon theme.

The resources are considered as part of the hicolor icon theme
and must be located in subdirectories that are defined in the
hicolor icon theme, such as `@path/16x16/actions/run.png`.
Icons that are directly placed in the resource path instead
of a subdirectory are also considered as ultimate fallback.
## `path`
a resource path
<!-- trait IconThemeExt::fn append_search_path -->
Appends a directory to the search path.
See `IconTheme::set_search_path`.
## `path`
directory name to append to the icon path
<!-- trait IconThemeExt::fn choose_icon -->
Looks up a named icon and returns a `IconInfo` containing
information such as the filename of the icon. The icon
can then be rendered into a pixbuf using
`IconInfo::load_icon`. (`IconThemeExt::load_icon`
combines these two steps if all you need is the pixbuf.)

If `icon_names` contains more than one name, this function
tries them all in the given order before falling back to
inherited icon themes.
## `icon_names`
`None`-terminated array of
 icon names to lookup
## `size`
desired icon size
## `flags`
flags modifying the behavior of the icon lookup

# Returns

a `IconInfo` object
containing information about the icon, or `None` if the icon wasn’t
found.
<!-- trait IconThemeExt::fn choose_icon_for_scale -->
Looks up a named icon for a particular window scale and returns
a `IconInfo` containing information such as the filename of the
icon. The icon can then be rendered into a pixbuf using
`IconInfo::load_icon`. (`IconThemeExt::load_icon`
combines these two steps if all you need is the pixbuf.)

If `icon_names` contains more than one name, this function
tries them all in the given order before falling back to
inherited icon themes.
## `icon_names`
`None`-terminated
 array of icon names to lookup
## `size`
desired icon size
## `scale`
desired scale
## `flags`
flags modifying the behavior of the icon lookup

# Returns

a `IconInfo` object
 containing information about the icon, or `None` if the
 icon wasn’t found.
<!-- trait IconThemeExt::fn get_example_icon_name -->
Gets the name of an icon that is representative of the
current theme (for instance, to use when presenting
a list of themes to the user.)

# Returns

the name of an example icon or `None`.
 Free with `g_free`.
<!-- trait IconThemeExt::fn get_icon_sizes -->
Returns an array of integers describing the sizes at which
the icon is available without scaling. A size of -1 means
that the icon is available in a scalable format. The array
is zero-terminated.
## `icon_name`
the name of an icon

# Returns

An newly
allocated array describing the sizes at which the icon is
available. The array should be freed with `g_free` when it is no
longer needed.
<!-- trait IconThemeExt::fn get_search_path -->
Gets the current search path. See `IconTheme::set_search_path`.
## `path`

 location to store a list of icon theme path directories or `None`.
 The stored value should be freed with `g_strfreev`.
## `n_elements`
location to store number of elements in `path`, or `None`
<!-- trait IconThemeExt::fn has_icon -->
Checks whether an icon theme includes an icon
for a particular name.
## `icon_name`
the name of an icon

# Returns

`true` if `self` includes an
 icon for `icon_name`.
<!-- trait IconThemeExt::fn list_contexts -->
Gets the list of contexts available within the current
hierarchy of icon themes.
See `IconThemeExt::list_icons` for details about contexts.

# Returns

a `glib::List` list
 holding the names of all the contexts in the theme. You must first
 free each element in the list with `g_free`, then free the list
 itself with `glib::List::free`.
<!-- trait IconThemeExt::fn list_icons -->
Lists the icons in the current icon theme. Only a subset
of the icons can be listed by providing a context string.
The set of values for the context string is system dependent,
but will typically include such values as “Applications” and
“MimeTypes”. Contexts are explained in the
[Icon Theme Specification](http://www.freedesktop.org/wiki/Specifications/icon-theme-spec).
The standard contexts are listed in the
[Icon Naming Specification](http://www.freedesktop.org/wiki/Specifications/icon-naming-spec).
Also see `IconThemeExt::list_contexts`.
## `context`
a string identifying a particular type of
 icon, or `None` to list all icons.

# Returns

a `glib::List` list
 holding the names of all the icons in the theme. You must
 first free each element in the list with `g_free`, then
 free the list itself with `glib::List::free`.
<!-- trait IconThemeExt::fn load_icon -->
Looks up an icon in an icon theme, scales it to the given size
and renders it into a pixbuf. This is a convenience function;
if more details about the icon are needed, use
`IconThemeExt::lookup_icon` followed by `IconInfo::load_icon`.

Note that you probably want to listen for icon theme changes and
update the icon. This is usually done by connecting to the
`Widget`::style-set signal. If for some reason you do not want to
update the icon when the icon theme changes, you should consider
using `gdk_pixbuf::Pixbuf::copy` to make a private copy of the pixbuf
returned by this function. Otherwise GTK+ may need to keep the old
icon theme loaded, which would be a waste of memory.
## `icon_name`
the name of the icon to lookup
## `size`
the desired icon size. The resulting icon may not be
 exactly this size; see `IconInfo::load_icon`.
## `flags`
flags modifying the behavior of the icon lookup

# Returns

the rendered icon; this may be
 a newly created icon or a new reference to an internal icon, so
 you must not modify the icon. Use `gobject::ObjectExt::unref` to release
 your reference to the icon. `None` if the icon isn’t found.
<!-- trait IconThemeExt::fn load_icon_for_scale -->
Looks up an icon in an icon theme for a particular window scale,
scales it to the given size and renders it into a pixbuf. This is a
convenience function; if more details about the icon are needed,
use `IconThemeExt::lookup_icon` followed by
`IconInfo::load_icon`.

Note that you probably want to listen for icon theme changes and
update the icon. This is usually done by connecting to the
`Widget`::style-set signal. If for some reason you do not want to
update the icon when the icon theme changes, you should consider
using `gdk_pixbuf::Pixbuf::copy` to make a private copy of the pixbuf
returned by this function. Otherwise GTK+ may need to keep the old
icon theme loaded, which would be a waste of memory.
## `icon_name`
the name of the icon to lookup
## `size`
the desired icon size. The resulting icon may not be
 exactly this size; see `IconInfo::load_icon`.
## `scale`
desired scale
## `flags`
flags modifying the behavior of the icon lookup

# Returns

the rendered icon; this may be
 a newly created icon or a new reference to an internal icon, so
 you must not modify the icon. Use `gobject::ObjectExt::unref` to release
 your reference to the icon. `None` if the icon isn’t found.
<!-- trait IconThemeExt::fn load_surface -->
Looks up an icon in an icon theme for a particular window scale,
scales it to the given size and renders it into a cairo surface. This is a
convenience function; if more details about the icon are needed,
use `IconThemeExt::lookup_icon` followed by
`IconInfo::load_surface`.

Note that you probably want to listen for icon theme changes and
update the icon. This is usually done by connecting to the
`Widget`::style-set signal.
## `icon_name`
the name of the icon to lookup
## `size`
the desired icon size. The resulting icon may not be
 exactly this size; see `IconInfo::load_icon`.
## `scale`
desired scale
## `for_window`
`gdk::Window` to optimize drawing for, or `None`
## `flags`
flags modifying the behavior of the icon lookup

# Returns

the rendered icon; this may be
 a newly created icon or a new reference to an internal icon, so
 you must not modify the icon. Use `cairo_surface_destroy` to
 release your reference to the icon. `None` if the icon isn’t
 found.
<!-- trait IconThemeExt::fn lookup_by_gicon -->
Looks up an icon and returns a `IconInfo` containing information
such as the filename of the icon. The icon can then be rendered
into a pixbuf using `IconInfo::load_icon`.

When rendering on displays with high pixel densities you should not
use a `size` multiplied by the scaling factor returned by functions
like `gdk::WindowExt::get_scale_factor`. Instead, you should use
`IconThemeExt::lookup_by_gicon_for_scale`, as the assets loaded
for a given scaling factor may be different.
## `icon`
the `gio::Icon` to look up
## `size`
desired icon size
## `flags`
flags modifying the behavior of the icon lookup

# Returns

a `IconInfo` containing
 information about the icon, or `None` if the icon wasn’t
 found. Unref with `gobject::ObjectExt::unref`
<!-- trait IconThemeExt::fn lookup_by_gicon_for_scale -->
Looks up an icon and returns a `IconInfo` containing information
such as the filename of the icon. The icon can then be rendered into
a pixbuf using `IconInfo::load_icon`.
## `icon`
the `gio::Icon` to look up
## `size`
desired icon size
## `scale`
the desired scale
## `flags`
flags modifying the behavior of the icon lookup

# Returns

a `IconInfo` containing
 information about the icon, or `None` if the icon wasn’t
 found. Unref with `gobject::ObjectExt::unref`
<!-- trait IconThemeExt::fn lookup_icon -->
Looks up a named icon and returns a `IconInfo` containing
information such as the filename of the icon. The icon
can then be rendered into a pixbuf using
`IconInfo::load_icon`. (`IconThemeExt::load_icon`
combines these two steps if all you need is the pixbuf.)

When rendering on displays with high pixel densities you should not
use a `size` multiplied by the scaling factor returned by functions
like `gdk::WindowExt::get_scale_factor`. Instead, you should use
`IconThemeExt::lookup_icon_for_scale`, as the assets loaded
for a given scaling factor may be different.
## `icon_name`
the name of the icon to lookup
## `size`
desired icon size
## `flags`
flags modifying the behavior of the icon lookup

# Returns

a `IconInfo` object
 containing information about the icon, or `None` if the
 icon wasn’t found.
<!-- trait IconThemeExt::fn lookup_icon_for_scale -->
Looks up a named icon for a particular window scale and returns a
`IconInfo` containing information such as the filename of the
icon. The icon can then be rendered into a pixbuf using
`IconInfo::load_icon`. (`IconThemeExt::load_icon` combines
these two steps if all you need is the pixbuf.)
## `icon_name`
the name of the icon to lookup
## `size`
desired icon size
## `scale`
the desired scale
## `flags`
flags modifying the behavior of the icon lookup

# Returns

a `IconInfo` object
 containing information about the icon, or `None` if the
 icon wasn’t found.
<!-- trait IconThemeExt::fn prepend_search_path -->
Prepends a directory to the search path.
See `IconTheme::set_search_path`.
## `path`
directory name to prepend to the icon path
<!-- trait IconThemeExt::fn rescan_if_needed -->
Checks to see if the icon theme has changed; if it has, any
currently cached information is discarded and will be reloaded
next time `self` is accessed.

# Returns

`true` if the icon theme has changed and needed
 to be reloaded.
<!-- trait IconThemeExt::fn set_custom_theme -->
Sets the name of the icon theme that the `IconTheme` object uses
overriding system configuration. This function cannot be called
on the icon theme objects returned from `IconTheme::get_default`
and `IconTheme::get_for_screen`.
## `theme_name`
name of icon theme to use instead of
 configured theme, or `None` to unset a previously set custom theme
<!-- trait IconThemeExt::fn set_screen -->
Sets the screen for an icon theme; the screen is used
to track the user’s currently configured icon theme,
which might be different for different screens.
## `screen`
a `gdk::Screen`
<!-- trait IconThemeExt::fn set_search_path -->
Sets the search path for the icon theme object. When looking
for an icon theme, GTK+ will search for a subdirectory of
one or more of the directories in `path` with the same name
as the icon theme containing an index.theme file. (Themes from
multiple of the path elements are combined to allow themes to be
extended by adding icons in the user’s home directory.)

In addition if an icon found isn’t found either in the current
icon theme or the default icon theme, and an image file with
the right name is found directly in one of the elements of
`path`, then that image will be used for the icon name.
(This is legacy feature, and new icons should be put
into the fallback icon theme, which is called hicolor,
rather than directly on the icon path.)
## `path`
array of
 directories that are searched for icon themes
## `n_elements`
number of elements in `path`.
<!-- trait IconThemeExt::fn connect_changed -->
Emitted when the current icon theme is switched or GTK+ detects
that a change has occurred in the contents of the current
icon theme.
<!-- enum IconThemeError -->
Error codes for `IconTheme` operations.
<!-- enum IconThemeError::variant NotFound -->
The icon specified does not exist in the theme
<!-- enum IconThemeError::variant Failed -->
An unspecified error occurred.
<!-- struct IconView -->
`IconView` provides an alternative view on a `TreeModel`.
It displays the model as a grid of icons with labels. Like
`TreeView`, it allows to select one or multiple items
(depending on the selection mode, see `IconViewExt::set_selection_mode`).
In addition to selection with the arrow keys, `IconView` supports
rubberband selection, which is controlled by dragging the pointer.

Note that if the tree model is backed by an actual tree store (as
opposed to a flat list where the mapping to icons is obvious),
`IconView` will only display the first level of the tree and
ignore the tree’s branches.

# CSS nodes


```plain
iconview.view
╰── [rubberband]
```

`IconView` has a single CSS node with name iconview and style class .view.
For rubberband selection, a subnode with name rubberband is used.

# Implements

[`IconViewExt`](trait.IconViewExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`ScrollableExt`](trait.ScrollableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait IconViewExt -->
Trait containing all `IconView` methods.

# Implementors

[`IconView`](struct.IconView.html)
<!-- impl IconView::fn new -->
Creates a new `IconView` widget

# Returns

A newly created `IconView` widget
<!-- impl IconView::fn new_with_area -->
Creates a new `IconView` widget using the
specified `area` to layout cells inside the icons.
## `area`
the `CellArea` to use to layout cells

# Returns

A newly created `IconView` widget
<!-- impl IconView::fn new_with_model -->
Creates a new `IconView` widget with the model `model`.
## `model`
The model.

# Returns

A newly created `IconView` widget.
<!-- trait IconViewExt::fn convert_widget_to_bin_window_coords -->
Converts widget coordinates to coordinates for the bin_window,
as expected by e.g. `IconViewExt::get_path_at_pos`.
## `wx`
X coordinate relative to the widget
## `wy`
Y coordinate relative to the widget
## `bx`
return location for bin_window X coordinate
## `by`
return location for bin_window Y coordinate
<!-- trait IconViewExt::fn create_drag_icon -->
Creates a `cairo::Surface` representation of the item at `path`.
This image is used for a drag icon.
## `path`
a `TreePath` in `self`

# Returns

a newly-allocated surface of the drag icon.
<!-- trait IconViewExt::fn enable_model_drag_dest -->
Turns `self` into a drop destination for automatic DND. Calling this
method sets `IconView:reorderable` to `false`.
## `targets`
the table of targets that the drag will
 support
## `n_targets`
the number of items in `targets`
## `actions`
the bitmask of possible actions for a drag to this
 widget
<!-- trait IconViewExt::fn enable_model_drag_source -->
Turns `self` into a drag source for automatic DND. Calling this
method sets `IconView:reorderable` to `false`.
## `start_button_mask`
Mask of allowed buttons to start drag
## `targets`
the table of targets that the drag will
 support
## `n_targets`
the number of items in `targets`
## `actions`
the bitmask of possible actions for a drag from this
 widget
<!-- trait IconViewExt::fn get_activate_on_single_click -->
Gets the setting set by `IconViewExt::set_activate_on_single_click`.

# Returns

`true` if item-activated will be emitted on a single click
<!-- trait IconViewExt::fn get_cell_rect -->
Fills the bounding rectangle in widget coordinates for the cell specified by
`path` and `cell`. If `cell` is `None` the main cell area is used.

This function is only valid if `self` is realized.
## `path`
a `TreePath`
## `cell`
a `CellRenderer` or `None`
## `rect`
rectangle to fill with cell rect

# Returns

`false` if there is no such item, `true` otherwise
<!-- trait IconViewExt::fn get_column_spacing -->
Returns the value of the ::column-spacing property.

# Returns

the space between columns
<!-- trait IconViewExt::fn get_columns -->
Returns the value of the ::columns property.

# Returns

the number of columns, or -1
<!-- trait IconViewExt::fn get_cursor -->
Fills in `path` and `cell` with the current cursor path and cell.
If the cursor isn’t currently set, then *`path` will be `None`.
If no cell currently has focus, then *`cell` will be `None`.

The returned `TreePath` must be freed with `TreePath::free`.
## `path`
Return location for the current
 cursor path, or `None`
## `cell`
Return location the current
 focus cell, or `None`

# Returns

`true` if the cursor is set.
<!-- trait IconViewExt::fn get_dest_item_at_pos -->
Determines the destination item for a given position.
## `drag_x`
the position to determine the destination item for
## `drag_y`
the position to determine the destination item for
## `path`
Return location for the path of the item,
 or `None`.
## `pos`
Return location for the drop position, or `None`

# Returns

whether there is an item at the given position.
<!-- trait IconViewExt::fn get_drag_dest_item -->
Gets information about the item that is highlighted for feedback.
## `path`
Return location for the path of
 the highlighted item, or `None`.
## `pos`
Return location for the drop position, or `None`
<!-- trait IconViewExt::fn get_item_at_pos -->
Finds the path at the point (`x`, `y`), relative to bin_window coordinates.
In contrast to `IconViewExt::get_path_at_pos`, this function also
obtains the cell at the specified position. The returned path should
be freed with `TreePath::free`.
See `IconViewExt::convert_widget_to_bin_window_coords` for converting
widget coordinates to bin_window coordinates.
## `x`
The x position to be identified
## `y`
The y position to be identified
## `path`
Return location for the path, or `None`
## `cell`
Return location for the renderer
 responsible for the cell at (`x`, `y`), or `None`

# Returns

`true` if an item exists at the specified position
<!-- trait IconViewExt::fn get_item_column -->
Gets the column in which the item `path` is currently
displayed. Column numbers start at 0.
## `path`
the `TreePath` of the item

# Returns

The column in which the item is displayed
<!-- trait IconViewExt::fn get_item_orientation -->
Returns the value of the ::item-orientation property which determines
whether the labels are drawn beside the icons instead of below.

# Returns

the relative position of texts and icons
<!-- trait IconViewExt::fn get_item_padding -->
Returns the value of the ::item-padding property.

# Returns

the padding around items
<!-- trait IconViewExt::fn get_item_row -->
Gets the row in which the item `path` is currently
displayed. Row numbers start at 0.
## `path`
the `TreePath` of the item

# Returns

The row in which the item is displayed
<!-- trait IconViewExt::fn get_item_width -->
Returns the value of the ::item-width property.

# Returns

the width of a single item, or -1
<!-- trait IconViewExt::fn get_margin -->
Returns the value of the ::margin property.

# Returns

the space at the borders
<!-- trait IconViewExt::fn get_markup_column -->
Returns the column with markup text for `self`.

# Returns

the markup column, or -1 if it’s unset.
<!-- trait IconViewExt::fn get_model -->
Returns the model the `IconView` is based on. Returns `None` if the
model is unset.

# Returns

A `TreeModel`, or `None` if none is
 currently being used.
<!-- trait IconViewExt::fn get_path_at_pos -->
Finds the path at the point (`x`, `y`), relative to bin_window coordinates.
See `IconViewExt::get_item_at_pos`, if you are also interested in
the cell at the specified position.
See `IconViewExt::convert_widget_to_bin_window_coords` for converting
widget coordinates to bin_window coordinates.
## `x`
The x position to be identified
## `y`
The y position to be identified

# Returns

The `TreePath` corresponding
to the icon or `None` if no icon exists at that position.
<!-- trait IconViewExt::fn get_pixbuf_column -->
Returns the column with pixbufs for `self`.

# Returns

the pixbuf column, or -1 if it’s unset.
<!-- trait IconViewExt::fn get_reorderable -->
Retrieves whether the user can reorder the list via drag-and-drop.
See `IconViewExt::set_reorderable`.

# Returns

`true` if the list can be reordered.
<!-- trait IconViewExt::fn get_row_spacing -->
Returns the value of the ::row-spacing property.

# Returns

the space between rows
<!-- trait IconViewExt::fn get_selected_items -->
Creates a list of paths of all selected items. Additionally, if you are
planning on modifying the model after calling this function, you may
want to convert the returned list into a list of ``GtkTreeRowReferences``.
To do this, you can use `TreeRowReference::new`.

To free the return value, use:

```C
g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free);
```

# Returns

A `glib::List` containing a `TreePath` for each selected row.
<!-- trait IconViewExt::fn get_selection_mode -->
Gets the selection mode of the `self`.

# Returns

the current selection mode
<!-- trait IconViewExt::fn get_spacing -->
Returns the value of the ::spacing property.

# Returns

the space between cells
<!-- trait IconViewExt::fn get_text_column -->
Returns the column with text for `self`.

# Returns

the text column, or -1 if it’s unset.
<!-- trait IconViewExt::fn get_tooltip_column -->
Returns the column of `self`’s model which is being used for
displaying tooltips on `self`’s rows.

# Returns

the index of the tooltip column that is currently being
used, or -1 if this is disabled.
<!-- trait IconViewExt::fn get_tooltip_context -->
This function is supposed to be used in a `Widget::query-tooltip`
signal handler for `IconView`. The `x`, `y` and `keyboard_tip` values
which are received in the signal handler, should be passed to this
function without modification.

The return value indicates whether there is an icon view item at the given
coordinates (`true`) or not (`false`) for mouse tooltips. For keyboard
tooltips the item returned will be the cursor item. When `true`, then any of
`model`, `path` and `iter` which have been provided will be set to point to
that row and the corresponding model. `x` and `y` will always be converted
to be relative to `self`’s bin_window if `keyboard_tooltip` is `false`.
## `x`
the x coordinate (relative to widget coordinates)
## `y`
the y coordinate (relative to widget coordinates)
## `keyboard_tip`
whether this is a keyboard tooltip or not
## `model`
a pointer to receive a
 `TreeModel` or `None`
## `path`
a pointer to receive a `TreePath` or `None`
## `iter`
a pointer to receive a `TreeIter` or `None`

# Returns

whether or not the given tooltip context points to a item
<!-- trait IconViewExt::fn get_visible_range -->
Sets `start_path` and `end_path` to be the first and last visible path.
Note that there may be invisible paths in between.

Both paths should be freed with `TreePath::free` after use.
## `start_path`
Return location for start of region,
 or `None`
## `end_path`
Return location for end of region, or `None`

# Returns

`true`, if valid paths were placed in `start_path` and `end_path`
<!-- trait IconViewExt::fn item_activated -->
Activates the item determined by `path`.
## `path`
The `TreePath` to be activated
<!-- trait IconViewExt::fn path_is_selected -->
Returns `true` if the icon pointed to by `path` is currently
selected. If `path` does not point to a valid location, `false` is returned.
## `path`
A `TreePath` to check selection on.

# Returns

`true` if `path` is selected.
<!-- trait IconViewExt::fn scroll_to_path -->
Moves the alignments of `self` to the position specified by `path`.
`row_align` determines where the row is placed, and `col_align` determines
where `column` is placed. Both are expected to be between 0.0 and 1.0.
0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means
center.

If `use_align` is `false`, then the alignment arguments are ignored, and the
tree does the minimum amount of work to scroll the item onto the screen.
This means that the item will be scrolled to the edge closest to its current
position. If the item is currently visible on the screen, nothing is done.

This function only works if the model is set, and `path` is a valid row on
the model. If the model changes before the `self` is realized, the
centered path will be modified to reflect this change.
## `path`
The path of the item to move to.
## `use_align`
whether to use alignment arguments, or `false`.
## `row_align`
The vertical alignment of the item specified by `path`.
## `col_align`
The horizontal alignment of the item specified by `path`.
<!-- trait IconViewExt::fn select_all -->
Selects all the icons. `self` must has its selection mode set
to `SelectionMode::Multiple`.
<!-- trait IconViewExt::fn select_path -->
Selects the row at `path`.
## `path`
The `TreePath` to be selected.
<!-- trait IconViewExt::fn selected_foreach -->
Calls a function for each selected icon. Note that the model or
selection cannot be modified from within this function.
## `func`
The function to call for each selected icon.
## `data`
User data to pass to the function.
<!-- trait IconViewExt::fn set_activate_on_single_click -->
Causes the `IconView::item-activated` signal to be emitted on
a single click instead of a double click.
## `single`
`true` to emit item-activated on a single click
<!-- trait IconViewExt::fn set_column_spacing -->
Sets the ::column-spacing property which specifies the space
which is inserted between the columns of the icon view.
## `column_spacing`
the column spacing
<!-- trait IconViewExt::fn set_columns -->
Sets the ::columns property which determines in how
many columns the icons are arranged. If `columns` is
-1, the number of columns will be chosen automatically
to fill the available area.
## `columns`
the number of columns
<!-- trait IconViewExt::fn set_cursor -->
Sets the current keyboard focus to be at `path`, and selects it. This is
useful when you want to focus the user’s attention on a particular item.
If `cell` is not `None`, then focus is given to the cell specified by
it. Additionally, if `start_editing` is `true`, then editing should be
started in the specified cell.

This function is often followed by `gtk_widget_grab_focus
(icon_view)` in order to give keyboard focus to the widget.
Please note that editing can only happen when the widget is realized.
## `path`
A `TreePath`
## `cell`
One of the cell renderers of `self`, or `None`
## `start_editing`
`true` if the specified cell should start being edited.
<!-- trait IconViewExt::fn set_drag_dest_item -->
Sets the item that is highlighted for feedback.
## `path`
The path of the item to highlight, or `None`.
## `pos`
Specifies where to drop, relative to the item
<!-- trait IconViewExt::fn set_item_orientation -->
Sets the ::item-orientation property which determines whether the labels
are drawn beside the icons instead of below.
## `orientation`
the relative position of texts and icons
<!-- trait IconViewExt::fn set_item_padding -->
Sets the `IconView:item-padding` property which specifies the padding
around each of the icon view’s items.
## `item_padding`
the item padding
<!-- trait IconViewExt::fn set_item_width -->
Sets the ::item-width property which specifies the width
to use for each item. If it is set to -1, the icon view will
automatically determine a suitable item size.
## `item_width`
the width for each item
<!-- trait IconViewExt::fn set_margin -->
Sets the ::margin property which specifies the space
which is inserted at the top, bottom, left and right
of the icon view.
## `margin`
the margin
<!-- trait IconViewExt::fn set_markup_column -->
Sets the column with markup information for `self` to be
`column`. The markup column must be of type `G_TYPE_STRING`.
If the markup column is set to something, it overrides
the text column set by `IconViewExt::set_text_column`.
## `column`
A column in the currently used model, or -1 to display no text
<!-- trait IconViewExt::fn set_model -->
Sets the model for a `IconView`.
If the `self` already has a model set, it will remove
it before setting the new model. If `model` is `None`, then
it will unset the old model.
## `model`
The model.
<!-- trait IconViewExt::fn set_pixbuf_column -->
Sets the column with pixbufs for `self` to be `column`. The pixbuf
column must be of type `GDK_TYPE_PIXBUF`
## `column`
A column in the currently used model, or -1 to disable
<!-- trait IconViewExt::fn set_reorderable -->
This function is a convenience function to allow you to reorder models that
support the `TreeDragSourceIface` and the `TreeDragDestIface`. Both
`TreeStore` and `ListStore` support these. If `reorderable` is `true`, then
the user can reorder the model by dragging and dropping rows. The
developer can listen to these changes by connecting to the model's
row_inserted and row_deleted signals. The reordering is implemented by setting up
the icon view as a drag source and destination. Therefore, drag and
drop can not be used in a reorderable view for any other purpose.

This function does not give you any degree of control over the order -- any
reordering is allowed. If more control is needed, you should probably
handle drag and drop manually.
## `reorderable`
`true`, if the list of items can be reordered.
<!-- trait IconViewExt::fn set_row_spacing -->
Sets the ::row-spacing property which specifies the space
which is inserted between the rows of the icon view.
## `row_spacing`
the row spacing
<!-- trait IconViewExt::fn set_selection_mode -->
Sets the selection mode of the `self`.
## `mode`
The selection mode
<!-- trait IconViewExt::fn set_spacing -->
Sets the ::spacing property which specifies the space
which is inserted between the cells (i.e. the icon and
the text) of an item.
## `spacing`
the spacing
<!-- trait IconViewExt::fn set_text_column -->
Sets the column with text for `self` to be `column`. The text
column must be of type `G_TYPE_STRING`.
## `column`
A column in the currently used model, or -1 to display no text
<!-- trait IconViewExt::fn set_tooltip_cell -->
Sets the tip area of `tooltip` to the area which `cell` occupies in
the item pointed to by `path`. See also `Tooltip::set_tip_area`.

See also `IconViewExt::set_tooltip_column` for a simpler alternative.
## `tooltip`
a `Tooltip`
## `path`
a `TreePath`
## `cell`
a `CellRenderer` or `None`
<!-- trait IconViewExt::fn set_tooltip_column -->
If you only plan to have simple (text-only) tooltips on full items, you
can use this function to have `IconView` handle these automatically
for you. `column` should be set to the column in `self`’s model
containing the tooltip texts, or -1 to disable this feature.

When enabled, `Widget:has-tooltip` will be set to `true` and
`self` will connect a `Widget::query-tooltip` signal handler.

Note that the signal handler sets the text with `Tooltip::set_markup`,
so &, <, etc have to be escaped in the text.
## `column`
an integer, which is a valid column number for `self`’s model
<!-- trait IconViewExt::fn set_tooltip_item -->
Sets the tip area of `tooltip` to be the area covered by the item at `path`.
See also `IconViewExt::set_tooltip_column` for a simpler alternative.
See also `Tooltip::set_tip_area`.
## `tooltip`
a `Tooltip`
## `path`
a `TreePath`
<!-- trait IconViewExt::fn unselect_all -->
Unselects all the icons.
<!-- trait IconViewExt::fn unselect_path -->
Unselects the row at `path`.
## `path`
The `TreePath` to be unselected.
<!-- trait IconViewExt::fn unset_model_drag_dest -->
Undoes the effect of `IconView::enable_model_drag_dest`. Calling this
method sets `IconView:reorderable` to `false`.
<!-- trait IconViewExt::fn unset_model_drag_source -->
Undoes the effect of `IconView::enable_model_drag_source`. Calling this
method sets `IconView:reorderable` to `false`.
<!-- trait IconViewExt::fn connect_activate_cursor_item -->
A [keybinding signal][`BindingSignal`]
which gets emitted when the user activates the currently
focused item.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control activation
programmatically.

The default bindings for this signal are Space, Return and Enter.
<!-- trait IconViewExt::fn connect_item_activated -->
The ::item-activated signal is emitted when the method
`IconViewExt::item_activated` is called, when the user double
clicks an item with the "activate-on-single-click" property set
to `false`, or when the user single clicks an item when the
"activate-on-single-click" property set to `true`. It is also
emitted when a non-editable item is selected and one of the keys:
Space, Return or Enter is pressed.
## `path`
the `TreePath` for the activated item
<!-- trait IconViewExt::fn connect_move_cursor -->
The ::move-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a cursor movement.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically.

The default bindings for this signal include
- Arrow keys which move by individual steps
- Home/End keys which move to the first/last item
- PageUp/PageDown which move by "pages"
All of these will extend the selection when combined with
the Shift modifier.
## `step`
the granularity of the move, as a `MovementStep`
## `count`
the number of `step` units to move
<!-- trait IconViewExt::fn connect_select_all -->
A [keybinding signal][`BindingSignal`]
which gets emitted when the user selects all items.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control selection
programmatically.

The default binding for this signal is Ctrl-a.
<!-- trait IconViewExt::fn connect_select_cursor_item -->
A [keybinding signal][`BindingSignal`]
which gets emitted when the user selects the item that is currently
focused.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control selection
programmatically.

There is no default binding for this signal.
<!-- trait IconViewExt::fn connect_selection_changed -->
The ::selection-changed signal is emitted when the selection
(i.e. the set of selected items) changes.
<!-- trait IconViewExt::fn connect_toggle_cursor_item -->
A [keybinding signal][`BindingSignal`]
which gets emitted when the user toggles whether the currently
focused item is selected or not. The exact effect of this
depend on the selection mode.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control selection
programmatically.

There is no default binding for this signal is Ctrl-Space.
<!-- trait IconViewExt::fn connect_unselect_all -->
A [keybinding signal][`BindingSignal`]
which gets emitted when the user unselects all items.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control selection
programmatically.

The default binding for this signal is Ctrl-Shift-a.
<!-- trait IconViewExt::fn get_property_activate_on_single_click -->
The activate-on-single-click property specifies whether the "item-activated" signal
will be emitted after a single click.
<!-- trait IconViewExt::fn set_property_activate_on_single_click -->
The activate-on-single-click property specifies whether the "item-activated" signal
will be emitted after a single click.
<!-- trait IconViewExt::fn get_property_cell_area -->
The `CellArea` used to layout cell renderers for this view.

If no area is specified when creating the icon view with `IconView::new_with_area`
a `CellAreaBox` will be used.
<!-- trait IconViewExt::fn set_property_cell_area -->
The `CellArea` used to layout cell renderers for this view.

If no area is specified when creating the icon view with `IconView::new_with_area`
a `CellAreaBox` will be used.
<!-- trait IconViewExt::fn get_property_column_spacing -->
The column-spacing property specifies the space which is inserted between
the columns of the icon view.
<!-- trait IconViewExt::fn set_property_column_spacing -->
The column-spacing property specifies the space which is inserted between
the columns of the icon view.
<!-- trait IconViewExt::fn get_property_columns -->
The columns property contains the number of the columns in which the
items should be displayed. If it is -1, the number of columns will
be chosen automatically to fill the available area.
<!-- trait IconViewExt::fn set_property_columns -->
The columns property contains the number of the columns in which the
items should be displayed. If it is -1, the number of columns will
be chosen automatically to fill the available area.
<!-- trait IconViewExt::fn get_property_item_orientation -->
The item-orientation property specifies how the cells (i.e. the icon and
the text) of the item are positioned relative to each other.
<!-- trait IconViewExt::fn set_property_item_orientation -->
The item-orientation property specifies how the cells (i.e. the icon and
the text) of the item are positioned relative to each other.
<!-- trait IconViewExt::fn get_property_item_padding -->
The item-padding property specifies the padding around each
of the icon view's item.
<!-- trait IconViewExt::fn set_property_item_padding -->
The item-padding property specifies the padding around each
of the icon view's item.
<!-- trait IconViewExt::fn get_property_item_width -->
The item-width property specifies the width to use for each item.
If it is set to -1, the icon view will automatically determine a
suitable item size.
<!-- trait IconViewExt::fn set_property_item_width -->
The item-width property specifies the width to use for each item.
If it is set to -1, the icon view will automatically determine a
suitable item size.
<!-- trait IconViewExt::fn get_property_margin -->
The margin property specifies the space which is inserted
at the edges of the icon view.
<!-- trait IconViewExt::fn set_property_margin -->
The margin property specifies the space which is inserted
at the edges of the icon view.
<!-- trait IconViewExt::fn get_property_markup_column -->
The ::markup-column property contains the number of the model column
containing markup information to be displayed. The markup column must be
of type `G_TYPE_STRING`. If this property and the :text-column property
are both set to column numbers, it overrides the text column.
If both are set to -1, no texts are displayed.
<!-- trait IconViewExt::fn set_property_markup_column -->
The ::markup-column property contains the number of the model column
containing markup information to be displayed. The markup column must be
of type `G_TYPE_STRING`. If this property and the :text-column property
are both set to column numbers, it overrides the text column.
If both are set to -1, no texts are displayed.
<!-- trait IconViewExt::fn get_property_pixbuf_column -->
The ::pixbuf-column property contains the number of the model column
containing the pixbufs which are displayed. The pixbuf column must be
of type `GDK_TYPE_PIXBUF`. Setting this property to -1 turns off the
display of pixbufs.
<!-- trait IconViewExt::fn set_property_pixbuf_column -->
The ::pixbuf-column property contains the number of the model column
containing the pixbufs which are displayed. The pixbuf column must be
of type `GDK_TYPE_PIXBUF`. Setting this property to -1 turns off the
display of pixbufs.
<!-- trait IconViewExt::fn get_property_reorderable -->
The reorderable property specifies if the items can be reordered
by DND.
<!-- trait IconViewExt::fn set_property_reorderable -->
The reorderable property specifies if the items can be reordered
by DND.
<!-- trait IconViewExt::fn get_property_row_spacing -->
The row-spacing property specifies the space which is inserted between
the rows of the icon view.
<!-- trait IconViewExt::fn set_property_row_spacing -->
The row-spacing property specifies the space which is inserted between
the rows of the icon view.
<!-- trait IconViewExt::fn get_property_selection_mode -->
The ::selection-mode property specifies the selection mode of
icon view. If the mode is `SelectionMode::Multiple`, rubberband selection
is enabled, for the other modes, only keyboard selection is possible.
<!-- trait IconViewExt::fn set_property_selection_mode -->
The ::selection-mode property specifies the selection mode of
icon view. If the mode is `SelectionMode::Multiple`, rubberband selection
is enabled, for the other modes, only keyboard selection is possible.
<!-- trait IconViewExt::fn get_property_spacing -->
The spacing property specifies the space which is inserted between
the cells (i.e. the icon and the text) of an item.
<!-- trait IconViewExt::fn set_property_spacing -->
The spacing property specifies the space which is inserted between
the cells (i.e. the icon and the text) of an item.
<!-- trait IconViewExt::fn get_property_text_column -->
The ::text-column property contains the number of the model column
containing the texts which are displayed. The text column must be
of type `G_TYPE_STRING`. If this property and the :markup-column
property are both set to -1, no texts are displayed.
<!-- trait IconViewExt::fn set_property_text_column -->
The ::text-column property contains the number of the model column
containing the texts which are displayed. The text column must be
of type `G_TYPE_STRING`. If this property and the :markup-column
property are both set to -1, no texts are displayed.
<!-- enum IconViewDropPosition -->
An enum for determining where a dropped item goes.
<!-- enum IconViewDropPosition::variant NoDrop -->
no drop possible
<!-- enum IconViewDropPosition::variant DropInto -->
dropped item replaces the item
<!-- enum IconViewDropPosition::variant DropLeft -->
droppped item is inserted to the left
<!-- enum IconViewDropPosition::variant DropRight -->
dropped item is inserted to the right
<!-- enum IconViewDropPosition::variant DropAbove -->
dropped item is inserted above
<!-- enum IconViewDropPosition::variant DropBelow -->
dropped item is inserted below
<!-- struct Image -->
The `Image` widget displays an image. Various kinds of object
can be displayed as an image; most typically, you would load a
`gdk_pixbuf::Pixbuf` ("pixel buffer") from a file, and then display that.
There’s a convenience function to do this, `Image::new_from_file`,
used as follows:

```C
  GtkWidget *image;
  image = gtk_image_new_from_file ("myfile.png");
```
If the file isn’t loaded successfully, the image will contain a
“broken image” icon similar to that used in many web browsers.
If you want to handle errors in loading the file yourself,
for example by displaying an error message, then load the image with
`gdk_pixbuf::Pixbuf::new_from_file`, then create the `Image` with
`Image::new_from_pixbuf`.

The image file may contain an animation, if so the `Image` will
display an animation (`gdk_pixbuf::PixbufAnimation`) instead of a static image.

`Image` is a subclass of `Misc`, which implies that you can
align it (center, left, right) and add padding to it, using
`Misc` methods.

`Image` is a “no window” widget (has no `gdk::Window` of its own),
so by default does not receive events. If you want to receive events
on the image, such as button clicks, place the image inside a
`EventBox`, then connect to the event signals on the event box.

## Handling button press events on a `Image`.


```C
  static gboolean
  button_press_callback (GtkWidget      *event_box,
                         GdkEventButton *event,
                         gpointer        data)
  {
    g_print ("Event box clicked at coordinates %f,%f\n",
             event->x, event->y);

    // Returning TRUE means we handled the event, so the signal
    // emission should be stopped (don’t call any further callbacks
    // that may be connected). Return FALSE to continue invoking callbacks.
    return TRUE;
  }

  static GtkWidget*
  create_image (void)
  {
    GtkWidget *image;
    GtkWidget *event_box;

    image = gtk_image_new_from_file ("myfile.png");

    event_box = gtk_event_box_new ();

    gtk_container_add (GTK_CONTAINER (event_box), image);

    g_signal_connect (G_OBJECT (event_box),
                      "button_press_event",
                      G_CALLBACK (button_press_callback),
                      image);

    return image;
  }
```

When handling events on the event box, keep in mind that coordinates
in the image may be different from event box coordinates due to
the alignment and padding settings on the image (see `Misc`).
The simplest way to solve this is to set the alignment to 0.0
(left/top), and set the padding to zero. Then the origin of
the image will be the same as the origin of the event box.

Sometimes an application will want to avoid depending on external data
files, such as image files. GTK+ comes with a program to avoid this,
called “gdk-pixbuf-csource”. This library
allows you to convert an image into a C variable declaration, which
can then be loaded into a `gdk_pixbuf::Pixbuf` using
`gdk_pixbuf::Pixbuf::new_from_inline`.

# CSS nodes

`Image` has a single CSS node with the name image. The style classes
may appear on image CSS nodes: .icon-dropshadow, .lowres-icon.

# Implements

[`ImageExt`](trait.ImageExt.html), [`MiscExt`](trait.MiscExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ImageExt -->
Trait containing all `Image` methods.

# Implementors

[`Image`](struct.Image.html)
<!-- impl Image::fn new -->
Creates a new empty `Image` widget.

# Returns

a newly created `Image` widget.
<!-- impl Image::fn new_from_animation -->
Creates a `Image` displaying the given animation.
The `Image` does not assume a reference to the
animation; you still need to unref it if you own references.
`Image` will add its own reference rather than adopting yours.

Note that the animation frames are shown using a timeout with
`G_PRIORITY_DEFAULT`. When using animations to indicate busyness,
keep in mind that the animation will only be shown if the main loop
is not busy with something that has a higher priority.
## `animation`
an animation

# Returns

a new `Image` widget
<!-- impl Image::fn new_from_file -->
Creates a new `Image` displaying the file `filename`. If the file
isn’t found or can’t be loaded, the resulting `Image` will
display a “broken image” icon. This function never returns `None`,
it always returns a valid `Image` widget.

If the file contains an animation, the image will contain an
animation.

If you need to detect failures to load the file, use
`gdk_pixbuf::Pixbuf::new_from_file` to load the file yourself, then create
the `Image` from the pixbuf. (Or for animations, use
`gdk_pixbuf::PixbufAnimation::new_from_file`).

The storage type (`ImageExt::get_storage_type`) of the returned
image is not defined, it will be whatever is appropriate for
displaying the file.
## `filename`
a filename

# Returns

a new `Image`
<!-- impl Image::fn new_from_gicon -->
Creates a `Image` displaying an icon from the current icon theme.
If the icon name isn’t known, a “broken image” icon will be
displayed instead. If the current icon theme is changed, the icon
will be updated appropriately.
## `icon`
an icon
## `size`
a stock icon size (`IconSize`)

# Returns

a new `Image` displaying the themed icon
<!-- impl Image::fn new_from_icon_name -->
Creates a `Image` displaying an icon from the current icon theme.
If the icon name isn’t known, a “broken image” icon will be
displayed instead. If the current icon theme is changed, the icon
will be updated appropriately.
## `icon_name`
an icon name or `None`
## `size`
a stock icon size (`IconSize`)

# Returns

a new `Image` displaying the themed icon
<!-- impl Image::fn new_from_pixbuf -->
Creates a new `Image` displaying `pixbuf`.
The `Image` does not assume a reference to the
pixbuf; you still need to unref it if you own references.
`Image` will add its own reference rather than adopting yours.

Note that this function just creates an `Image` from the pixbuf. The
`Image` created will not react to state changes. Should you want that,
you should use `Image::new_from_icon_name`.
## `pixbuf`
a `gdk_pixbuf::Pixbuf`, or `None`

# Returns

a new `Image`
<!-- impl Image::fn new_from_resource -->
Creates a new `Image` displaying the resource file `resource_path`. If the file
isn’t found or can’t be loaded, the resulting `Image` will
display a “broken image” icon. This function never returns `None`,
it always returns a valid `Image` widget.

If the file contains an animation, the image will contain an
animation.

If you need to detect failures to load the file, use
`gdk_pixbuf::Pixbuf::new_from_file` to load the file yourself, then create
the `Image` from the pixbuf. (Or for animations, use
`gdk_pixbuf::PixbufAnimation::new_from_file`).

The storage type (`ImageExt::get_storage_type`) of the returned
image is not defined, it will be whatever is appropriate for
displaying the file.
## `resource_path`
a resource path

# Returns

a new `Image`
<!-- impl Image::fn new_from_surface -->
Creates a new `Image` displaying `surface`.
The `Image` does not assume a reference to the
surface; you still need to unref it if you own references.
`Image` will add its own reference rather than adopting yours.
## `surface`
a `cairo::Surface`, or `None`

# Returns

a new `Image`
<!-- trait ImageExt::fn clear -->
Resets the image to be empty.
<!-- trait ImageExt::fn get_animation -->
Gets the `gdk_pixbuf::PixbufAnimation` being displayed by the `Image`.
The storage type of the image must be `ImageType::Empty` or
`ImageType::Animation` (see `ImageExt::get_storage_type`).
The caller of this function does not own a reference to the
returned animation.

# Returns

the displayed animation, or `None` if
the image is empty
<!-- trait ImageExt::fn get_gicon -->
Gets the `gio::Icon` and size being displayed by the `Image`.
The storage type of the image must be `ImageType::Empty` or
`ImageType::Gicon` (see `ImageExt::get_storage_type`).
The caller of this function does not own a reference to the
returned `gio::Icon`.
## `gicon`
place to store a
 `gio::Icon`, or `None`
## `size`
place to store an icon size
 (`IconSize`), or `None`
<!-- trait ImageExt::fn get_icon_name -->
Gets the icon name and size being displayed by the `Image`.
The storage type of the image must be `ImageType::Empty` or
`ImageType::IconName` (see `ImageExt::get_storage_type`).
The returned string is owned by the `Image` and should not
be freed.
## `icon_name`
place to store an
 icon name, or `None`
## `size`
place to store an icon size
 (`IconSize`), or `None`
<!-- trait ImageExt::fn get_pixbuf -->
Gets the `gdk_pixbuf::Pixbuf` being displayed by the `Image`.
The storage type of the image must be `ImageType::Empty` or
`ImageType::Pixbuf` (see `ImageExt::get_storage_type`).
The caller of this function does not own a reference to the
returned pixbuf.

# Returns

the displayed pixbuf, or `None` if
the image is empty
<!-- trait ImageExt::fn get_pixel_size -->
Gets the pixel size used for named icons.

# Returns

the pixel size used for named icons.
<!-- trait ImageExt::fn get_storage_type -->
Gets the type of representation being used by the `Image`
to store image data. If the `Image` has no image data,
the return value will be `ImageType::Empty`.

# Returns

image representation being used
<!-- trait ImageExt::fn set_from_animation -->
Causes the `Image` to display the given animation (or display
nothing, if you set the animation to `None`).
## `animation`
the `gdk_pixbuf::PixbufAnimation`
<!-- trait ImageExt::fn set_from_file -->
See `Image::new_from_file` for details.
## `filename`
a filename or `None`
<!-- trait ImageExt::fn set_from_gicon -->
See `Image::new_from_gicon` for details.
## `icon`
an icon
## `size`
an icon size (`IconSize`)
<!-- trait ImageExt::fn set_from_icon_name -->
See `Image::new_from_icon_name` for details.
## `icon_name`
an icon name or `None`
## `size`
an icon size (`IconSize`)
<!-- trait ImageExt::fn set_from_pixbuf -->
See `Image::new_from_pixbuf` for details.
## `pixbuf`
a `gdk_pixbuf::Pixbuf` or `None`
<!-- trait ImageExt::fn set_from_resource -->
See `Image::new_from_resource` for details.
## `resource_path`
a resource path or `None`
<!-- trait ImageExt::fn set_from_surface -->
See `Image::new_from_surface` for details.
## `surface`
a cairo_surface_t or `None`
<!-- trait ImageExt::fn set_pixel_size -->
Sets the pixel size to use for named icons. If the pixel size is set
to a value != -1, it is used instead of the icon size set by
`ImageExt::set_from_icon_name`.
## `pixel_size`
the new pixel size
<!-- trait ImageExt::fn get_property_gicon -->
The GIcon displayed in the `Image`. For themed icons,
If the icon theme is changed, the image will be updated
automatically.
<!-- trait ImageExt::fn set_property_gicon -->
The GIcon displayed in the `Image`. For themed icons,
If the icon theme is changed, the image will be updated
automatically.
<!-- trait ImageExt::fn get_property_icon_name -->
The name of the icon in the icon theme. If the icon theme is
changed, the image will be updated automatically.
<!-- trait ImageExt::fn set_property_icon_name -->
The name of the icon in the icon theme. If the icon theme is
changed, the image will be updated automatically.
<!-- trait ImageExt::fn get_property_pixel_size -->
The "pixel-size" property can be used to specify a fixed size
overriding the `Image:icon-size` property for images of type
`ImageType::IconName`.
<!-- trait ImageExt::fn set_property_pixel_size -->
The "pixel-size" property can be used to specify a fixed size
overriding the `Image:icon-size` property for images of type
`ImageType::IconName`.
<!-- trait ImageExt::fn get_property_resource -->
A path to a resource file to display.
<!-- trait ImageExt::fn set_property_resource -->
A path to a resource file to display.
<!-- trait ImageExt::fn get_property_use_fallback -->
Whether the icon displayed in the `Image` will use
standard icon names fallback. The value of this property
is only relevant for images of type `ImageType::IconName`
and `ImageType::Gicon`.
<!-- trait ImageExt::fn set_property_use_fallback -->
Whether the icon displayed in the `Image` will use
standard icon names fallback. The value of this property
is only relevant for images of type `ImageType::IconName`
and `ImageType::Gicon`.
<!-- enum ImageType -->
Describes the image data representation used by a `Image`. If you
want to get the image from the widget, you can only get the
currently-stored representation. e.g. if the
`ImageExt::get_storage_type` returns `ImageType::Pixbuf`, then you can
call `ImageExt::get_pixbuf` but not `Image::get_stock`. For empty
images, you can request any storage type (call any of the "get"
functions), but they will all return `None` values.
<!-- enum ImageType::variant Empty -->
there is no image displayed by the widget
<!-- enum ImageType::variant Pixbuf -->
the widget contains a `gdk_pixbuf::Pixbuf`
<!-- enum ImageType::variant Stock -->
the widget contains a [stock item name][gtkstock]
<!-- enum ImageType::variant IconSet -->
the widget contains a `IconSet`
<!-- enum ImageType::variant Animation -->
the widget contains a `gdk_pixbuf::PixbufAnimation`
<!-- enum ImageType::variant IconName -->
the widget contains a named icon.
 This image type was added in GTK+ 2.6
<!-- enum ImageType::variant Gicon -->
the widget contains a `gio::Icon`.
 This image type was added in GTK+ 2.14
<!-- enum ImageType::variant Surface -->
the widget contains a `cairo::Surface`.
 This image type was added in GTK+ 3.10
<!-- struct InfoBar -->
`InfoBar` is a widget that can be used to show messages to
the user without showing a dialog. It is often temporarily shown
at the top or bottom of a document. In contrast to `Dialog`, which
has a action area at the bottom, `InfoBar` has an action area
at the side.

The API of `InfoBar` is very similar to `Dialog`, allowing you
to add buttons to the action area with `InfoBarExt::add_button` or
`InfoBar::new_with_buttons`. The sensitivity of action widgets
can be controlled with `InfoBarExt::set_response_sensitive`.
To add widgets to the main content area of a `InfoBar`, use
`InfoBarExt::get_content_area` and add your widgets to the container.

Similar to `MessageDialog`, the contents of a `InfoBar` can by
classified as error message, warning, informational message, etc,
by using `InfoBarExt::set_message_type`. GTK+ may use the message type
to determine how the message is displayed.

A simple example for using a `InfoBar`:

```C
GtkWidget *widget, *message_label, *content_area;
GtkWidget *grid;
GtkInfoBar *bar;

// set up info bar
widget = gtk_info_bar_new ();
bar = GTK_INFO_BAR (widget);
grid = gtk_grid_new ();

gtk_widget_set_no_show_all (widget, TRUE);
message_label = gtk_label_new ("");
content_area = gtk_info_bar_get_content_area (bar);
gtk_container_add (GTK_CONTAINER (content_area),
                   message_label);
gtk_info_bar_add_button (bar,
                         _("_OK"),
                         GTK_RESPONSE_OK);
g_signal_connect (bar,
                  "response",
                  G_CALLBACK (gtk_widget_hide),
                  NULL);
gtk_grid_attach (GTK_GRID (grid),
                 widget,
                 0, 2, 1, 1);

// ...

// show an error message
gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!");
gtk_info_bar_set_message_type (bar,
                               GTK_MESSAGE_ERROR);
gtk_widget_show (bar);
```

# `InfoBar` as `Buildable`

The `InfoBar` implementation of the `Buildable` interface exposes
the content area and action area as internal children with the names
“content_area” and “action_area”.

`InfoBar` supports a custom `<action-widgets>` element, which can contain
multiple `<action-widget>` elements. The “response” attribute specifies a
numeric response, and the content of the element is the id of widget
(which should be a child of the dialogs `action_area`).

# CSS nodes

`InfoBar` has a single CSS node with name infobar. The node may get
one of the style classes .info, .warning, .error or .question, depending
on the message type.

# Implements

[`InfoBarExt`](trait.InfoBarExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait InfoBarExt -->
Trait containing all `InfoBar` methods.

# Implementors

[`InfoBar`](struct.InfoBar.html)
<!-- impl InfoBar::fn new -->
Creates a new `InfoBar` object.

# Returns

a new `InfoBar` object
<!-- impl InfoBar::fn new_with_buttons -->
Creates a new `InfoBar` with buttons. Button text/response ID
pairs should be listed, with a `None` pointer ending the list.
Button text can be either a stock ID such as `GTK_STOCK_OK`, or
some arbitrary text. A response ID can be any positive number,
or one of the values in the `ResponseType` enumeration. If the
user clicks one of these dialog buttons, `InfoBar` will emit
the “response” signal with the corresponding response ID.
## `first_button_text`
stock ID or text to go in first button, or `None`

# Returns

a new `InfoBar`
<!-- trait InfoBarExt::fn add_action_widget -->
Add an activatable widget to the action area of a `InfoBar`,
connecting a signal handler that will emit the `InfoBar::response`
signal on the message area when the widget is activated. The widget
is appended to the end of the message areas action area.
## `child`
an activatable widget
## `response_id`
response ID for `child`
<!-- trait InfoBarExt::fn add_button -->
Adds a button with the given text and sets things up so that
clicking the button will emit the “response” signal with the given
response_id. The button is appended to the end of the info bars's
action area. The button widget is returned, but usually you don't
need it.
## `button_text`
text of button
## `response_id`
response ID for the button

# Returns

the `Button` widget
that was added
<!-- trait InfoBarExt::fn add_buttons -->
Adds more buttons, same as calling `InfoBarExt::add_button`
repeatedly. The variable argument list should be `None`-terminated
as with `InfoBar::new_with_buttons`. Each button must have both
text and response ID.
## `first_button_text`
button text or stock ID
<!-- trait InfoBarExt::fn get_action_area -->
Returns the action area of `self`.

# Returns

the action area
<!-- trait InfoBarExt::fn get_content_area -->
Returns the content area of `self`.

# Returns

the content area
<!-- trait InfoBarExt::fn get_message_type -->
Returns the message type of the message area.

# Returns

the message type of the message area.
<!-- trait InfoBarExt::fn get_revealed -->

Feature: `v3_22_29`


# Returns

the current value of the `InfoBar`:revealed property.
<!-- trait InfoBarExt::fn get_show_close_button -->
Returns whether the widget will display a standard close button.

# Returns

`true` if the widget displays standard close button
<!-- trait InfoBarExt::fn response -->
Emits the “response” signal with the given `response_id`.
## `response_id`
a response ID
<!-- trait InfoBarExt::fn set_default_response -->
Sets the last widget in the info bar’s action area with
the given response_id as the default widget for the dialog.
Pressing “Enter” normally activates the default widget.

Note that this function currently requires `self` to
be added to a widget hierarchy.
## `response_id`
a response ID
<!-- trait InfoBarExt::fn set_message_type -->
Sets the message type of the message area.

GTK+ uses this type to determine how the message is displayed.
## `message_type`
a `MessageType`
<!-- trait InfoBarExt::fn set_response_sensitive -->
Calls gtk_widget_set_sensitive (widget, setting) for each
widget in the info bars’s action area with the given response_id.
A convenient way to sensitize/desensitize dialog buttons.
## `response_id`
a response ID
## `setting`
TRUE for sensitive
<!-- trait InfoBarExt::fn set_revealed -->
Sets the `InfoBar`:revealed property to `revealed`. This will cause
`self` to show up with a slide-in transition.

Note that this property does not automatically show `self` and thus won’t
have any effect if it is invisible.

Feature: `v3_22_29`

## `revealed`
The new value of the property
<!-- trait InfoBarExt::fn set_show_close_button -->
If true, a standard close button is shown. When clicked it emits
the response `ResponseType::Close`.
## `setting`
`true` to include a close button
<!-- trait InfoBarExt::fn connect_close -->
The ::close signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user uses a keybinding to dismiss
the info bar.

The default binding for this signal is the Escape key.
<!-- trait InfoBarExt::fn connect_response -->
Emitted when an action widget is clicked or the application programmer
calls `DialogExt::response`. The `response_id` depends on which action
widget was clicked.
## `response_id`
the response ID
<!-- trait InfoBarExt::fn get_property_message_type -->
The type of the message.

The type may be used to determine the appearance of the info bar.
<!-- trait InfoBarExt::fn set_property_message_type -->
The type of the message.

The type may be used to determine the appearance of the info bar.
<!-- trait InfoBarExt::fn get_property_show_close_button -->
Whether to include a standard close button.
<!-- trait InfoBarExt::fn set_property_show_close_button -->
Whether to include a standard close button.
<!-- struct InputHints -->
Describes hints that might be taken into account by input methods
or applications. Note that input methods may already tailor their
behaviour according to the `InputPurpose` of the entry.

Some common sense is expected when using these flags - mixing
`InputHints::Lowercase` with any of the uppercase hints makes no sense.

This enumeration may be extended in the future; input methods should
ignore unknown values.
<!-- struct InputHints::const NONE -->
No special behaviour suggested
<!-- struct InputHints::const SPELLCHECK -->
Suggest checking for typos
<!-- struct InputHints::const NO_SPELLCHECK -->
Suggest not checking for typos
<!-- struct InputHints::const WORD_COMPLETION -->
Suggest word completion
<!-- struct InputHints::const LOWERCASE -->
Suggest to convert all text to lowercase
<!-- struct InputHints::const UPPERCASE_CHARS -->
Suggest to capitalize all text
<!-- struct InputHints::const UPPERCASE_WORDS -->
Suggest to capitalize the first
 character of each word
<!-- struct InputHints::const UPPERCASE_SENTENCES -->
Suggest to capitalize the
 first word of each sentence
<!-- struct InputHints::const INHIBIT_OSK -->
Suggest to not show an onscreen keyboard
 (e.g for a calculator that already has all the keys).
<!-- struct InputHints::const VERTICAL_WRITING -->
The text is vertical. Since 3.18
<!-- struct InputHints::const EMOJI -->
Suggest offering Emoji support. Since 3.22.20
<!-- struct InputHints::const NO_EMOJI -->
Suggest not offering Emoji support. Since 3.22.20
<!-- enum InputPurpose -->
Describes primary purpose of the input widget. This information is
useful for on-screen keyboards and similar input methods to decide
which keys should be presented to the user.

Note that the purpose is not meant to impose a totally strict rule
about allowed characters, and does not replace input validation.
It is fine for an on-screen keyboard to let the user override the
character set restriction that is expressed by the purpose. The
application is expected to validate the entry contents, even if
it specified a purpose.

The difference between `InputPurpose::Digits` and
`InputPurpose::Number` is that the former accepts only digits
while the latter also some punctuation (like commas or points, plus,
minus) and “e” or “E” as in 3.14E+000.

This enumeration may be extended in the future; input methods should
interpret unknown values as “free form”.
<!-- enum InputPurpose::variant FreeForm -->
Allow any character
<!-- enum InputPurpose::variant Alpha -->
Allow only alphabetic characters
<!-- enum InputPurpose::variant Digits -->
Allow only digits
<!-- enum InputPurpose::variant Number -->
Edited field expects numbers
<!-- enum InputPurpose::variant Phone -->
Edited field expects phone number
<!-- enum InputPurpose::variant Url -->
Edited field expects URL
<!-- enum InputPurpose::variant Email -->
Edited field expects email address
<!-- enum InputPurpose::variant Name -->
Edited field expects the name of a person
<!-- enum InputPurpose::variant Password -->
Like `InputPurpose::FreeForm`, but characters are hidden
<!-- enum InputPurpose::variant Pin -->
Like `InputPurpose::Digits`, but characters are hidden
<!-- enum InputPurpose::variant Terminal -->
Allow any character, in addition to control codes
<!-- struct Invisible -->
The `Invisible` widget is used internally in GTK+, and is probably not
very useful for application developers.

It is used for reliable pointer grabs and selection handling in the code
for drag-and-drop.

# Implements

[`InvisibleExt`](trait.InvisibleExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`InvisibleExtManual`](prelude/trait.InvisibleExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait InvisibleExt -->
Trait containing all `Invisible` methods.

# Implementors

[`Invisible`](struct.Invisible.html)
<!-- impl Invisible::fn new -->
Creates a new `Invisible`.

# Returns

a new `Invisible`.
<!-- impl Invisible::fn new_for_screen -->
Creates a new `Invisible` object for a specified screen
## `screen`
a `gdk::Screen` which identifies on which
 the new `Invisible` will be created.

# Returns

a newly created `Invisible` object
<!-- trait InvisibleExtManual::fn get_screen -->
Returns the `gdk::Screen` object associated with `self`

# Returns

the associated `gdk::Screen`.
<!-- trait InvisibleExt::fn set_screen -->
Sets the `gdk::Screen` where the `Invisible` object will be displayed.
## `screen`
a `gdk::Screen`.
<!-- struct JunctionSides -->
Describes how a rendered element connects to adjacent elements.
<!-- struct JunctionSides::const NONE -->
No junctions.
<!-- struct JunctionSides::const CORNER_TOPLEFT -->
Element connects on the top-left corner.
<!-- struct JunctionSides::const CORNER_TOPRIGHT -->
Element connects on the top-right corner.
<!-- struct JunctionSides::const CORNER_BOTTOMLEFT -->
Element connects on the bottom-left corner.
<!-- struct JunctionSides::const CORNER_BOTTOMRIGHT -->
Element connects on the bottom-right corner.
<!-- struct JunctionSides::const TOP -->
Element connects on the top side.
<!-- struct JunctionSides::const BOTTOM -->
Element connects on the bottom side.
<!-- struct JunctionSides::const LEFT -->
Element connects on the left side.
<!-- struct JunctionSides::const RIGHT -->
Element connects on the right side.
<!-- enum Justification -->
Used for justifying the text inside a `Label` widget. (See also
`Alignment`).
<!-- enum Justification::variant Left -->
The text is placed at the left edge of the label.
<!-- enum Justification::variant Right -->
The text is placed at the right edge of the label.
<!-- enum Justification::variant Center -->
The text is placed in the center of the label.
<!-- enum Justification::variant Fill -->
The text is placed is distributed across the label.
<!-- struct Label -->
The `Label` widget displays a small amount of text. As the name
implies, most labels are used to label another widget such as a
`Button`, a `MenuItem`, or a `ComboBox`.

# CSS nodes


```plain
label
├── [selection]
├── [link]
┊
╰── [link]
```

`Label` has a single CSS node with the name label. A wide variety
of style classes may be applied to labels, such as .title, .subtitle,
.dim-label, etc. In the `ShortcutsWindow`, labels are used wth the
.keycap style class.

If the label has a selection, it gets a subnode with name selection.

If the label has links, there is one subnode per link. These subnodes
carry the link or visited state depending on whether they have been
visited.

# `Label` as `Buildable`

The `Label` implementation of the `Buildable` interface supports a
custom `<attributes>` element, which supports any number of `<attribute>`
elements. The `<attribute>` element has attributes named “name“, “value“,
“start“ and “end“ and allows you to specify `pango::Attribute` values for
this label.

An example of a UI definition fragment specifying Pango attributes:

```C
  // Pressing Alt+H will activate this button
  GtkWidget *button = gtk_button_new ();
  GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
  gtk_container_add (GTK_CONTAINER (button), label);
```

There’s a convenience function to create buttons with a mnemonic label
already inside:


```C
  // Pressing Alt+H will activate this button
  GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello");
```

To create a mnemonic for a widget alongside the label, such as a
`Entry`, you have to point the label at the entry with
`LabelExt::set_mnemonic_widget`:


```C
  // Pressing Alt+H will focus the entry
  GtkWidget *entry = gtk_entry_new ();
  GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
  gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
```

# Markup (styled text)

To make it easy to format text in a label (changing colors,
fonts, etc.), label text can be provided in a simple
[markup format][PangoMarkupFormat].

Here’s how to create a label with a small font:

```C
  GtkWidget *label = gtk_label_new (NULL);
  gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
```

(See [complete documentation][PangoMarkupFormat] of available
tags in the Pango manual.)

The markup passed to `LabelExt::set_markup` must be valid; for example,
literal <, > and & characters must be escaped as &lt;, &gt;, and &amp;.
If you pass text obtained from the user, file, or a network to
`LabelExt::set_markup`, you’ll want to escape it with
`g_markup_escape_text` or `g_markup_printf_escaped`.

Markup strings are just a convenient way to set the `pango::AttrList` on
a label; `LabelExt::set_attributes` may be a simpler way to set
attributes in some cases. Be careful though; `pango::AttrList` tends to
cause internationalization problems, unless you’re applying attributes
to the entire string (i.e. unless you set the range of each attribute
to [0, `G_MAXINT`)). The reason is that specifying the start_index and
end_index for a `pango::Attribute` requires knowledge of the exact string
being displayed, so translations will cause problems.

# Selectable labels

Labels can be made selectable with `LabelExt::set_selectable`.
Selectable labels allow the user to copy the label contents to
the clipboard. Only labels that contain useful-to-copy information
— such as error messages — should be made selectable.

# Text layout # {`label`-text-layout}

A label can contain any number of paragraphs, but will have
performance problems if it contains more than a small number.
Paragraphs are separated by newlines or other paragraph separators
understood by Pango.

Labels can automatically wrap text if you call
`LabelExt::set_line_wrap`.

`LabelExt::set_justify` sets how the lines in a label align
with one another. If you want to set how the label as a whole
aligns in its available space, see the `Widget:halign` and
`Widget:valign` properties.

The `Label:width-chars` and `Label:max-width-chars` properties
can be used to control the size allocation of ellipsized or wrapped
labels. For ellipsizing labels, if either is specified (and less
than the actual text size), it is used as the minimum width, and the actual
text size is used as the natural width of the label. For wrapping labels,
width-chars is used as the minimum width, if specified, and max-width-chars
is used as the natural width. Even if max-width-chars specified, wrapping
labels will be rewrapped to use all of the available width.

Note that the interpretation of `Label:width-chars` and
`Label:max-width-chars` has changed a bit with the introduction of
[width-for-height geometry management.][geometry-management]

# Links

Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
to regular Pango markup. The markup for links is borrowed from HTML,
using the `<a>` with “href“ and “title“ attributes. GTK+ renders links
similar to the way they appear in web browsers, with colored, underlined
text. The “title“ attribute is displayed as a tooltip on the link.

An example looks like this:


```C
const gchar *text =
"Go to the"
"<a href=\"http://www.gtk.org title=\"&lt;i&gt;Our&lt;/i&gt; website\">"
"GTK+ website</a> for more...";
GtkWidget *label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), text);
```

It is possible to implement custom handling for links and their tooltips with
the `Label::activate-link` signal and the `LabelExt::get_current_uri` function.

# Implements

[`LabelExt`](trait.LabelExt.html), [`MiscExt`](trait.MiscExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait LabelExt -->
Trait containing all `Label` methods.

# Implementors

[`AccelLabel`](struct.AccelLabel.html), [`Label`](struct.Label.html)
<!-- impl Label::fn new -->
Creates a new label with the given text inside it. You can
pass `None` to get an empty label widget.
## `str`
The text of the label

# Returns

the new `Label`
<!-- impl Label::fn new_with_mnemonic -->
Creates a new `Label`, containing the text in `str`.

If characters in `str` are preceded by an underscore, they are
underlined. If you need a literal underscore character in a label, use
'__' (two underscores). The first underlined character represents a
keyboard accelerator called a mnemonic. The mnemonic key can be used
to activate another widget, chosen automatically, or explicitly using
`LabelExt::set_mnemonic_widget`.

If `LabelExt::set_mnemonic_widget` is not called, then the first
activatable ancestor of the `Label` will be chosen as the mnemonic
widget. For instance, if the label is inside a button or menu item,
the button or menu item will automatically become the mnemonic widget
and be activated by the mnemonic.
## `str`
The text of the label, with an underscore in front of the
 mnemonic character

# Returns

the new `Label`
<!-- trait LabelExt::fn get_angle -->
Gets the angle of rotation for the label. See
`LabelExt::set_angle`.

# Returns

the angle of rotation for the label
<!-- trait LabelExt::fn get_attributes -->
Gets the attribute list that was set on the label using
`LabelExt::set_attributes`, if any. This function does
not reflect attributes that come from the labels markup
(see `LabelExt::set_markup`). If you want to get the
effective attributes for the label, use
pango_layout_get_attribute (gtk_label_get_layout (label)).

# Returns

the attribute list, or `None`
 if none was set.
<!-- trait LabelExt::fn get_current_uri -->
Returns the URI for the currently active link in the label.
The active link is the one under the mouse pointer or, in a
selectable label, the link in which the text cursor is currently
positioned.

This function is intended for use in a `Label::activate-link` handler
or for use in a `Widget::query-tooltip` handler.

# Returns

the currently active URI. The string is owned by GTK+ and must
 not be freed or modified.
<!-- trait LabelExt::fn get_ellipsize -->
Returns the ellipsizing position of the label. See `LabelExt::set_ellipsize`.

# Returns

`pango::EllipsizeMode`
<!-- trait LabelExt::fn get_justify -->
Returns the justification of the label. See `LabelExt::set_justify`.

# Returns

`Justification`
<!-- trait LabelExt::fn get_label -->
Fetches the text from a label widget including any embedded
underlines indicating mnemonics and Pango markup. (See
`LabelExt::get_text`).

# Returns

the text of the label widget. This string is
 owned by the widget and must not be modified or freed.
<!-- trait LabelExt::fn get_layout -->
Gets the `pango::Layout` used to display the label.
The layout is useful to e.g. convert text positions to
pixel positions, in combination with `LabelExt::get_layout_offsets`.
The returned layout is owned by the `self` so need not be
freed by the caller. The `self` is free to recreate its layout at
any time, so it should be considered read-only.

# Returns

the `pango::Layout` for this label
<!-- trait LabelExt::fn get_layout_offsets -->
Obtains the coordinates where the label will draw the `pango::Layout`
representing the text in the label; useful to convert mouse events
into coordinates inside the `pango::Layout`, e.g. to take some action
if some part of the label is clicked. Of course you will need to
create a `EventBox` to receive the events, and pack the label
inside it, since labels are windowless (they return `false` from
`WidgetExt::get_has_window`). Remember
when using the `pango::Layout` functions you need to convert to
and from pixels using PANGO_PIXELS() or `PANGO_SCALE`.
## `x`
location to store X offset of layout, or `None`
## `y`
location to store Y offset of layout, or `None`
<!-- trait LabelExt::fn get_line_wrap -->
Returns whether lines in the label are automatically wrapped.
See `LabelExt::set_line_wrap`.

# Returns

`true` if the lines of the label are automatically wrapped.
<!-- trait LabelExt::fn get_line_wrap_mode -->
Returns line wrap mode used by the label. See `LabelExt::set_line_wrap_mode`.

# Returns

`true` if the lines of the label are automatically wrapped.
<!-- trait LabelExt::fn get_lines -->
Gets the number of lines to which an ellipsized, wrapping
label should be limited. See `LabelExt::set_lines`.

# Returns

The number of lines
<!-- trait LabelExt::fn get_max_width_chars -->
Retrieves the desired maximum width of `self`, in characters. See
`LabelExt::set_width_chars`.

# Returns

the maximum width of the label in characters.
<!-- trait LabelExt::fn get_mnemonic_keyval -->
If the label has been set so that it has an mnemonic key this function
returns the keyval used for the mnemonic accelerator. If there is no
mnemonic set up it returns `GDK_KEY_VoidSymbol`.

# Returns

GDK keyval usable for accelerators, or `GDK_KEY_VoidSymbol`
<!-- trait LabelExt::fn get_mnemonic_widget -->
Retrieves the target of the mnemonic (keyboard shortcut) of this
label. See `LabelExt::set_mnemonic_widget`.

# Returns

the target of the label’s mnemonic,
 or `None` if none has been set and the default algorithm will be used.
<!-- trait LabelExt::fn get_selectable -->
Gets the value set by `LabelExt::set_selectable`.

# Returns

`true` if the user can copy text from the label
<!-- trait LabelExt::fn get_selection_bounds -->
Gets the selected range of characters in the label, returning `true`
if there’s a selection.
## `start`
return location for start of selection, as a character offset
## `end`
return location for end of selection, as a character offset

# Returns

`true` if selection is non-empty
<!-- trait LabelExt::fn get_single_line_mode -->
Returns whether the label is in single line mode.

# Returns

`true` when the label is in single line mode.
<!-- trait LabelExt::fn get_text -->
Fetches the text from a label widget, as displayed on the
screen. This does not include any embedded underlines
indicating mnemonics or Pango markup. (See `LabelExt::get_label`)

# Returns

the text in the label widget. This is the internal
 string used by the label, and must not be modified.
<!-- trait LabelExt::fn get_track_visited_links -->
Returns whether the label is currently keeping track
of clicked links.

# Returns

`true` if clicked links are remembered
<!-- trait LabelExt::fn get_use_markup -->
Returns whether the label’s text is interpreted as marked up with
the [Pango text markup language][PangoMarkupFormat].
See gtk_label_set_use_markup ().

# Returns

`true` if the label’s text will be parsed for markup.
<!-- trait LabelExt::fn get_use_underline -->
Returns whether an embedded underline in the label indicates a
mnemonic. See `LabelExt::set_use_underline`.

# Returns

`true` whether an embedded underline in the label indicates
 the mnemonic accelerator keys.
<!-- trait LabelExt::fn get_width_chars -->
Retrieves the desired width of `self`, in characters. See
`LabelExt::set_width_chars`.

# Returns

the width of the label in characters.
<!-- trait LabelExt::fn get_xalign -->
Gets the `Label:xalign` property for `self`.

Feature: `v3_16`


# Returns

the xalign property
<!-- trait LabelExt::fn get_yalign -->
Gets the `Label:yalign` property for `self`.

Feature: `v3_16`


# Returns

the yalign property
<!-- trait LabelExt::fn select_region -->
Selects a range of characters in the label, if the label is selectable.
See `LabelExt::set_selectable`. If the label is not selectable,
this function has no effect. If `start_offset` or
`end_offset` are -1, then the end of the label will be substituted.
## `start_offset`
start offset (in characters not bytes)
## `end_offset`
end offset (in characters not bytes)
<!-- trait LabelExt::fn set_angle -->
Sets the angle of rotation for the label. An angle of 90 reads from
from bottom to top, an angle of 270, from top to bottom. The angle
setting for the label is ignored if the label is selectable,
wrapped, or ellipsized.
## `angle`
the angle that the baseline of the label makes with
 the horizontal, in degrees, measured counterclockwise
<!-- trait LabelExt::fn set_attributes -->
Sets a `pango::AttrList`; the attributes in the list are applied to the
label text.

The attributes set with this function will be applied
and merged with any other attributes previously effected by way
of the `Label:use-underline` or `Label:use-markup` properties.
While it is not recommended to mix markup strings with manually set
attributes, if you must; know that the attributes will be applied
to the label after the markup string is parsed.
## `attrs`
a `pango::AttrList`, or `None`
<!-- trait LabelExt::fn set_ellipsize -->
Sets the mode used to ellipsize (add an ellipsis: "...") to the text
if there is not enough space to render the entire string.
## `mode`
a `pango::EllipsizeMode`
<!-- trait LabelExt::fn set_justify -->
Sets the alignment of the lines in the text of the label relative to
each other. `Justification::Left` is the default value when the widget is
first created with `Label::new`. If you instead want to set the
alignment of the label as a whole, use `WidgetExt::set_halign` instead.
`LabelExt::set_justify` has no effect on labels containing only a
single line.
## `jtype`
a `Justification`
<!-- trait LabelExt::fn set_label -->
Sets the text of the label. The label is interpreted as
including embedded underlines and/or Pango markup depending
on the values of the `Label:use-underline` and
`Label:use-markup` properties.
## `str`
the new text to set for the label
<!-- trait LabelExt::fn set_line_wrap -->
Toggles line wrapping within the `Label` widget. `true` makes it break
lines if text exceeds the widget’s size. `false` lets the text get cut off
by the edge of the widget if it exceeds the widget size.

Note that setting line wrapping to `true` does not make the label
wrap at its parent container’s width, because GTK+ widgets
conceptually can’t make their requisition depend on the parent
container’s size. For a label that wraps at a specific position,
set the label’s width using `WidgetExt::set_size_request`.
## `wrap`
the setting
<!-- trait LabelExt::fn set_line_wrap_mode -->
If line wrapping is on (see `LabelExt::set_line_wrap`) this controls how
the line wrapping is done. The default is `pango::WrapMode::Word` which means
wrap on word boundaries.
## `wrap_mode`
the line wrapping mode
<!-- trait LabelExt::fn set_lines -->
Sets the number of lines to which an ellipsized, wrapping label
should be limited. This has no effect if the label is not wrapping
or ellipsized. Set this to -1 if you don’t want to limit the
number of lines.
## `lines`
the desired number of lines, or -1
<!-- trait LabelExt::fn set_markup -->
Parses `str` which is marked up with the
[Pango text markup language][PangoMarkupFormat], setting the
label’s text and attribute list based on the parse results.

If the `str` is external data, you may need to escape it with
`g_markup_escape_text` or `g_markup_printf_escaped`:


```C
GtkWidget *label = gtk_label_new (NULL);
const char *str = "some text";
const char *format = "<span style=\"italic\">\%s</span>";
char *markup;

markup = g_markup_printf_escaped (format, str);
gtk_label_set_markup (GTK_LABEL (label), markup);
g_free (markup);
```

This function will set the `Label:use-markup` property to `true` as
a side effect.

If you set the label contents using the `Label:label` property you
should also ensure that you set the `Label:use-markup` property
accordingly.

See also: `LabelExt::set_text`
## `str`
a markup string (see [Pango markup format][PangoMarkupFormat])
<!-- trait LabelExt::fn set_markup_with_mnemonic -->
Parses `str` which is marked up with the
[Pango text markup language][PangoMarkupFormat],
setting the label’s text and attribute list based on the parse results.
If characters in `str` are preceded by an underscore, they are underlined
indicating that they represent a keyboard accelerator called a mnemonic.

The mnemonic key can be used to activate another widget, chosen
automatically, or explicitly using `LabelExt::set_mnemonic_widget`.
## `str`
a markup string (see
 [Pango markup format][PangoMarkupFormat])
<!-- trait LabelExt::fn set_max_width_chars -->
Sets the desired maximum width in characters of `self` to `n_chars`.
## `n_chars`
the new desired maximum width, in characters.
<!-- trait LabelExt::fn set_mnemonic_widget -->
If the label has been set so that it has an mnemonic key (using
i.e. `LabelExt::set_markup_with_mnemonic`,
`LabelExt::set_text_with_mnemonic`, `Label::new_with_mnemonic`
or the “use_underline” property) the label can be associated with a
widget that is the target of the mnemonic. When the label is inside
a widget (like a `Button` or a `Notebook` tab) it is
automatically associated with the correct widget, but sometimes
(i.e. when the target is a `Entry` next to the label) you need to
set it explicitly using this function.

The target widget will be accelerated by emitting the
`Widget`::mnemonic-activate signal on it. The default handler for
this signal will activate the widget if there are no mnemonic collisions
and toggle focus between the colliding widgets otherwise.
## `widget`
the target `Widget`, or `None` to unset
<!-- trait LabelExt::fn set_pattern -->
The pattern of underlines you want under the existing text within the
`Label` widget. For example if the current text of the label says
“FooBarBaz” passing a pattern of “___ ___” will underline
“Foo” and “Baz” but not “Bar”.
## `pattern`
The pattern as described above.
<!-- trait LabelExt::fn set_selectable -->
Selectable labels allow the user to select text from the label, for
copy-and-paste.
## `setting`
`true` to allow selecting text in the label
<!-- trait LabelExt::fn set_single_line_mode -->
Sets whether the label is in single line mode.
## `single_line_mode`
`true` if the label should be in single line mode
<!-- trait LabelExt::fn set_text -->
Sets the text within the `Label` widget. It overwrites any text that
was there before.

This function will clear any previously set mnemonic accelerators, and
set the `Label:use-underline` property to `false` as a side effect.

This function will set the `Label:use-markup` property to `false`
as a side effect.

See also: `LabelExt::set_markup`
## `str`
The text you want to set
<!-- trait LabelExt::fn set_text_with_mnemonic -->
Sets the label’s text from the string `str`.
If characters in `str` are preceded by an underscore, they are underlined
indicating that they represent a keyboard accelerator called a mnemonic.
The mnemonic key can be used to activate another widget, chosen
automatically, or explicitly using `LabelExt::set_mnemonic_widget`.
## `str`
a string
<!-- trait LabelExt::fn set_track_visited_links -->
Sets whether the label should keep track of clicked
links (and use a different color for them).
## `track_links`
`true` to track visited links
<!-- trait LabelExt::fn set_use_markup -->
Sets whether the text of the label contains markup in
[Pango’s text markup language][PangoMarkupFormat].
See `LabelExt::set_markup`.
## `setting`
`true` if the label’s text should be parsed for markup.
<!-- trait LabelExt::fn set_use_underline -->
If true, an underline in the text indicates the next character should be
used for the mnemonic accelerator key.
## `setting`
`true` if underlines in the text indicate mnemonics
<!-- trait LabelExt::fn set_width_chars -->
Sets the desired width in characters of `self` to `n_chars`.
## `n_chars`
the new desired width, in characters.
<!-- trait LabelExt::fn set_xalign -->
Sets the `Label:xalign` property for `self`.

Feature: `v3_16`

## `xalign`
the new xalign value, between 0 and 1
<!-- trait LabelExt::fn set_yalign -->
Sets the `Label:yalign` property for `self`.

Feature: `v3_16`

## `yalign`
the new yalign value, between 0 and 1
<!-- trait LabelExt::fn connect_activate_current_link -->
A [keybinding signal][`BindingSignal`]
which gets emitted when the user activates a link in the label.

Applications may also emit the signal with `g_signal_emit_by_name`
if they need to control activation of URIs programmatically.

The default bindings for this signal are all forms of the Enter key.
<!-- trait LabelExt::fn connect_activate_link -->
The signal which gets emitted to activate a URI.
Applications may connect to it to override the default behaviour,
which is to call `gtk_show_uri_on_window`.
## `uri`
the URI that is activated

# Returns

`true` if the link has been activated
<!-- trait LabelExt::fn connect_copy_clipboard -->
The ::copy-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to copy the selection to the clipboard.

The default binding for this signal is Ctrl-c.
<!-- trait LabelExt::fn connect_move_cursor -->
The ::move-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a cursor movement.
If the cursor is not visible in `entry`, this signal causes
the viewport to be moved instead.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically.

The default bindings for this signal come in two variants,
the variant with the Shift modifier extends the selection,
the variant without the Shift modifer does not.
There are too many key combinations to list them all here.
- Arrow keys move by individual characters/lines
- Ctrl-arrow key combinations move by words/paragraphs
- Home/End keys move to the ends of the buffer
## `step`
the granularity of the move, as a `MovementStep`
## `count`
the number of `step` units to move
## `extend_selection`
`true` if the move should extend the selection
<!-- trait LabelExt::fn connect_populate_popup -->
The ::populate-popup signal gets emitted before showing the
context menu of the label. Note that only selectable labels
have context menus.

If you need to add items to the context menu, connect
to this signal and append your menuitems to the `menu`.
## `menu`
the menu that is being populated
<!-- trait LabelExt::fn get_property_angle -->
The angle that the baseline of the label makes with the horizontal,
in degrees, measured counterclockwise. An angle of 90 reads from
from bottom to top, an angle of 270, from top to bottom. Ignored
if the label is selectable.
<!-- trait LabelExt::fn set_property_angle -->
The angle that the baseline of the label makes with the horizontal,
in degrees, measured counterclockwise. An angle of 90 reads from
from bottom to top, an angle of 270, from top to bottom. Ignored
if the label is selectable.
<!-- trait LabelExt::fn get_property_ellipsize -->
The preferred place to ellipsize the string, if the label does
not have enough room to display the entire string, specified as a
`pango::EllipsizeMode`.

Note that setting this property to a value other than
`pango::EllipsizeMode::None` has the side-effect that the label requests
only enough space to display the ellipsis "...". In particular, this
means that ellipsizing labels do not work well in notebook tabs, unless
the `Notebook` tab-expand child property is set to `true`. Other ways
to set a label's width are `WidgetExt::set_size_request` and
`LabelExt::set_width_chars`.
<!-- trait LabelExt::fn set_property_ellipsize -->
The preferred place to ellipsize the string, if the label does
not have enough room to display the entire string, specified as a
`pango::EllipsizeMode`.

Note that setting this property to a value other than
`pango::EllipsizeMode::None` has the side-effect that the label requests
only enough space to display the ellipsis "...". In particular, this
means that ellipsizing labels do not work well in notebook tabs, unless
the `Notebook` tab-expand child property is set to `true`. Other ways
to set a label's width are `WidgetExt::set_size_request` and
`LabelExt::set_width_chars`.
<!-- trait LabelExt::fn get_property_label -->
The contents of the label.

If the string contains [Pango XML markup][PangoMarkupFormat], you will
have to set the `Label:use-markup` property to `true` in order for the
label to display the markup attributes. See also `LabelExt::set_markup`
for a convenience function that sets both this property and the
`Label:use-markup` property at the same time.

If the string contains underlines acting as mnemonics, you will have to
set the `Label:use-underline` property to `true` in order for the label
to display them.
<!-- trait LabelExt::fn set_property_label -->
The contents of the label.

If the string contains [Pango XML markup][PangoMarkupFormat], you will
have to set the `Label:use-markup` property to `true` in order for the
label to display the markup attributes. See also `LabelExt::set_markup`
for a convenience function that sets both this property and the
`Label:use-markup` property at the same time.

If the string contains underlines acting as mnemonics, you will have to
set the `Label:use-underline` property to `true` in order for the label
to display them.
<!-- trait LabelExt::fn get_property_lines -->
The number of lines to which an ellipsized, wrapping label
should be limited. This property has no effect if the
label is not wrapping or ellipsized. Set this property to
-1 if you don't want to limit the number of lines.
<!-- trait LabelExt::fn set_property_lines -->
The number of lines to which an ellipsized, wrapping label
should be limited. This property has no effect if the
label is not wrapping or ellipsized. Set this property to
-1 if you don't want to limit the number of lines.
<!-- trait LabelExt::fn get_property_max_width_chars -->
The desired maximum width of the label, in characters. If this property
is set to -1, the width will be calculated automatically.

See the section on [text layout][label-text-layout]
for details of how `Label:width-chars` and `Label:max-width-chars`
determine the width of ellipsized and wrapped labels.
<!-- trait LabelExt::fn set_property_max_width_chars -->
The desired maximum width of the label, in characters. If this property
is set to -1, the width will be calculated automatically.

See the section on [text layout][label-text-layout]
for details of how `Label:width-chars` and `Label:max-width-chars`
determine the width of ellipsized and wrapped labels.
<!-- trait LabelExt::fn get_property_single_line_mode -->
Whether the label is in single line mode. In single line mode,
the height of the label does not depend on the actual text, it
is always set to ascent + descent of the font. This can be an
advantage in situations where resizing the label because of text
changes would be distracting, e.g. in a statusbar.
<!-- trait LabelExt::fn set_property_single_line_mode -->
Whether the label is in single line mode. In single line mode,
the height of the label does not depend on the actual text, it
is always set to ascent + descent of the font. This can be an
advantage in situations where resizing the label because of text
changes would be distracting, e.g. in a statusbar.
<!-- trait LabelExt::fn get_property_track_visited_links -->
Set this property to `true` to make the label track which links
have been visited. It will then apply the `StateFlags::Visited`
when rendering this link, in addition to `StateFlags::Link`.
<!-- trait LabelExt::fn set_property_track_visited_links -->
Set this property to `true` to make the label track which links
have been visited. It will then apply the `StateFlags::Visited`
when rendering this link, in addition to `StateFlags::Link`.
<!-- trait LabelExt::fn get_property_width_chars -->
The desired width of the label, in characters. If this property is set to
-1, the width will be calculated automatically.

See the section on [text layout][label-text-layout]
for details of how `Label:width-chars` and `Label:max-width-chars`
determine the width of ellipsized and wrapped labels.
<!-- trait LabelExt::fn set_property_width_chars -->
The desired width of the label, in characters. If this property is set to
-1, the width will be calculated automatically.

See the section on [text layout][label-text-layout]
for details of how `Label:width-chars` and `Label:max-width-chars`
determine the width of ellipsized and wrapped labels.
<!-- trait LabelExt::fn get_property_wrap_mode -->
If line wrapping is on (see the `Label:wrap` property) this controls
how the line wrapping is done. The default is `pango::WrapMode::Word`, which
means wrap on word boundaries.
<!-- trait LabelExt::fn set_property_wrap_mode -->
If line wrapping is on (see the `Label:wrap` property) this controls
how the line wrapping is done. The default is `pango::WrapMode::Word`, which
means wrap on word boundaries.
<!-- trait LabelExt::fn get_property_xalign -->
The xalign property determines the horizontal aligment of the label text
inside the labels size allocation. Compare this to `Widget:halign`,
which determines how the labels size allocation is positioned in the
space available for the label.

Feature: `v3_16`

<!-- trait LabelExt::fn set_property_xalign -->
The xalign property determines the horizontal aligment of the label text
inside the labels size allocation. Compare this to `Widget:halign`,
which determines how the labels size allocation is positioned in the
space available for the label.

Feature: `v3_16`

<!-- trait LabelExt::fn get_property_yalign -->
The yalign property determines the vertical aligment of the label text
inside the labels size allocation. Compare this to `Widget:valign`,
which determines how the labels size allocation is positioned in the
space available for the label.

Feature: `v3_16`

<!-- trait LabelExt::fn set_property_yalign -->
The yalign property determines the vertical aligment of the label text
inside the labels size allocation. Compare this to `Widget:valign`,
which determines how the labels size allocation is positioned in the
space available for the label.

Feature: `v3_16`

<!-- struct Layout -->
`Layout` is similar to `DrawingArea` in that it’s a “blank slate” and
doesn’t do anything except paint a blank background by default. It’s
different in that it supports scrolling natively due to implementing
`Scrollable`, and can contain child widgets since it’s a `Container`.

If you just want to draw, a `DrawingArea` is a better choice since it has
lower overhead. If you just need to position child widgets at specific
points, then `Fixed` provides that functionality on its own.

When handling expose events on a `Layout`, you must draw to the `gdk::Window`
returned by `LayoutExt::get_bin_window`, rather than to the one returned by
`WidgetExt::get_window` as you would for a `DrawingArea`.

# Implements

[`LayoutExt`](trait.LayoutExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ScrollableExt`](trait.ScrollableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait LayoutExt -->
Trait containing all `Layout` methods.

# Implementors

[`Layout`](struct.Layout.html)
<!-- impl Layout::fn new -->
Creates a new `Layout`. Unless you have a specific adjustment
you’d like the layout to use for scrolling, pass `None` for
`hadjustment` and `vadjustment`.
## `hadjustment`
horizontal scroll adjustment, or `None`
## `vadjustment`
vertical scroll adjustment, or `None`

# Returns

a new `Layout`
<!-- trait LayoutExt::fn get_bin_window -->
Retrieve the bin window of the layout used for drawing operations.

# Returns

a `gdk::Window`
<!-- trait LayoutExt::fn get_size -->
Gets the size that has been set on the layout, and that determines
the total extents of the layout’s scrollbar area. See
gtk_layout_set_size ().
## `width`
location to store the width set on
 `self`, or `None`
## `height`
location to store the height set on
 `self`, or `None`
<!-- trait LayoutExt::fn move -->
Moves a current child of `self` to a new position.
## `child_widget`
a current child of `self`
## `x`
X position to move to
## `y`
Y position to move to
<!-- trait LayoutExt::fn put -->
Adds `child_widget` to `self`, at position (`x`,`y`).
`self` becomes the new parent container of `child_widget`.
## `child_widget`
child widget
## `x`
X position of child widget
## `y`
Y position of child widget
<!-- trait LayoutExt::fn set_size -->
Sets the size of the scrollable area of the layout.
## `width`
width of entire scrollable area
## `height`
height of entire scrollable area
<!-- struct LevelBar -->
The `LevelBar` is a bar widget that can be used
as a level indicator. Typical use cases are displaying the strength
of a password, or showing the charge level of a battery.

Use `LevelBarExt::set_value` to set the current value, and
`LevelBarExt::add_offset_value` to set the value offsets at which
the bar will be considered in a different state. GTK will add a few
offsets by default on the level bar: `GTK_LEVEL_BAR_OFFSET_LOW`,
`GTK_LEVEL_BAR_OFFSET_HIGH` and `GTK_LEVEL_BAR_OFFSET_FULL`, with
values 0.25, 0.75 and 1.0 respectively.

Note that it is your responsibility to update preexisting offsets
when changing the minimum or maximum value. GTK+ will simply clamp
them to the new range.

## Adding a custom offset on the bar


```C

static GtkWidget *
create_level_bar (void)
{
  GtkWidget *widget;
  GtkLevelBar *bar;

  widget = gtk_level_bar_new ();
  bar = GTK_LEVEL_BAR (widget);

  // This changes the value of the default low offset

  gtk_level_bar_add_offset_value (bar,
                                  GTK_LEVEL_BAR_OFFSET_LOW,
                                  0.10);

  // This adds a new offset to the bar; the application will
  // be able to change its color CSS like this:
  //
  // levelbar block.my-offset {
  //   background-color: magenta;
  //   border-style: solid;
  //   border-color: black;
  //   border-style: 1px;
  // }

  gtk_level_bar_add_offset_value (bar, "my-offset", 0.60);

  return widget;
}
```

The default interval of values is between zero and one, but it’s possible to
modify the interval using `LevelBarExt::set_min_value` and
`LevelBarExt::set_max_value`. The value will be always drawn in proportion to
the admissible interval, i.e. a value of 15 with a specified interval between
10 and 20 is equivalent to a value of 0.5 with an interval between 0 and 1.
When `LevelBarMode::Discrete` is used, the bar level is rendered
as a finite number of separated blocks instead of a single one. The number
of blocks that will be rendered is equal to the number of units specified by
the admissible interval.

For instance, to build a bar rendered with five blocks, it’s sufficient to
set the minimum value to 0 and the maximum value to 5 after changing the indicator
mode to discrete.

`LevelBar` was introduced in GTK+ 3.6.

# `LevelBar` as `Buildable`

The `LevelBar` implementation of the `Buildable` interface supports a
custom `<offsets>` element, which can contain any number of `<offset>` elements,
each of which must have name and value attributes.

# CSS nodes


```plain
levelbar[.discrete]
╰── trough
    ├── block.filled.level-name
    ┊
    ├── block.empty
    ┊
```

`LevelBar` has a main CSS node with name levelbar and one of the style
classes .discrete or .continuous and a subnode with name trough. Below the
trough node are a number of nodes with name block and style class .filled
or .empty. In continuous mode, there is exactly one node of each, in discrete
mode, the number of filled and unfilled nodes corresponds to blocks that are
drawn. The block.filled nodes also get a style class .level-name corresponding
to the level for the current value.

In horizontal orientation, the nodes are always arranged from left to right,
regardless of text direction.

# Implements

[`LevelBarExt`](trait.LevelBarExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait LevelBarExt -->
Trait containing all `LevelBar` methods.

# Implementors

[`LevelBar`](struct.LevelBar.html)
<!-- impl LevelBar::fn new -->
Creates a new `LevelBar`.

# Returns

a `LevelBar`.
<!-- impl LevelBar::fn new_for_interval -->
Utility constructor that creates a new `LevelBar` for the specified
interval.
## `min_value`
a positive value
## `max_value`
a positive value

# Returns

a `LevelBar`
<!-- trait LevelBarExt::fn add_offset_value -->
Adds a new offset marker on `self` at the position specified by `value`.
When the bar value is in the interval topped by `value` (or between `value`
and `LevelBar:max-value` in case the offset is the last one on the bar)
a style class named `level-``name` will be applied
when rendering the level bar fill.
If another offset marker named `name` exists, its value will be
replaced by `value`.
## `name`
the name of the new offset
## `value`
the value for the new offset
<!-- trait LevelBarExt::fn get_inverted -->
Return the value of the `LevelBar:inverted` property.

# Returns

`true` if the level bar is inverted
<!-- trait LevelBarExt::fn get_max_value -->
Returns the value of the `LevelBar:max-value` property.

# Returns

a positive value
<!-- trait LevelBarExt::fn get_min_value -->
Returns the value of the `LevelBar:min-value` property.

# Returns

a positive value
<!-- trait LevelBarExt::fn get_mode -->
Returns the value of the `LevelBar:mode` property.

# Returns

a `LevelBarMode`
<!-- trait LevelBarExt::fn get_offset_value -->
Fetches the value specified for the offset marker `name` in `self`,
returning `true` in case an offset named `name` was found.
## `name`
the name of an offset in the bar
## `value`
location where to store the value

# Returns

`true` if the specified offset is found
<!-- trait LevelBarExt::fn get_value -->
Returns the value of the `LevelBar:value` property.

# Returns

a value in the interval between
 `LevelBar:min-value` and `LevelBar:max-value`
<!-- trait LevelBarExt::fn remove_offset_value -->
Removes an offset marker previously added with
`LevelBarExt::add_offset_value`.
## `name`
the name of an offset in the bar
<!-- trait LevelBarExt::fn set_inverted -->
Sets the value of the `LevelBar:inverted` property.
## `inverted`
`true` to invert the level bar
<!-- trait LevelBarExt::fn set_max_value -->
Sets the value of the `LevelBar:max-value` property.

You probably want to update preexisting level offsets after calling
this function.
## `value`
a positive value
<!-- trait LevelBarExt::fn set_min_value -->
Sets the value of the `LevelBar:min-value` property.

You probably want to update preexisting level offsets after calling
this function.
## `value`
a positive value
<!-- trait LevelBarExt::fn set_mode -->
Sets the value of the `LevelBar:mode` property.
## `mode`
a `LevelBarMode`
<!-- trait LevelBarExt::fn set_value -->
Sets the value of the `LevelBar:value` property.
## `value`
a value in the interval between
 `LevelBar:min-value` and `LevelBar:max-value`
<!-- trait LevelBarExt::fn connect_offset_changed -->
Emitted when an offset specified on the bar changes value as an
effect to `LevelBarExt::add_offset_value` being called.

The signal supports detailed connections; you can connect to the
detailed signal "changed::x" in order to only receive callbacks when
the value of offset "x" changes.
## `name`
the name of the offset that changed value
<!-- trait LevelBarExt::fn get_property_inverted -->
Level bars normally grow from top to bottom or left to right.
Inverted level bars grow in the opposite direction.
<!-- trait LevelBarExt::fn set_property_inverted -->
Level bars normally grow from top to bottom or left to right.
Inverted level bars grow in the opposite direction.
<!-- trait LevelBarExt::fn get_property_max_value -->
The `LevelBar:max-value` property determaxes the maximum value of
the interval that can be displayed by the bar.
<!-- trait LevelBarExt::fn set_property_max_value -->
The `LevelBar:max-value` property determaxes the maximum value of
the interval that can be displayed by the bar.
<!-- trait LevelBarExt::fn get_property_min_value -->
The `LevelBar:min-value` property determines the minimum value of
the interval that can be displayed by the bar.
<!-- trait LevelBarExt::fn set_property_min_value -->
The `LevelBar:min-value` property determines the minimum value of
the interval that can be displayed by the bar.
<!-- trait LevelBarExt::fn get_property_mode -->
The `LevelBar:mode` property determines the way `LevelBar`
interprets the value properties to draw the level fill area.
Specifically, when the value is `LevelBarMode::Continuous`,
`LevelBar` will draw a single block representing the current value in
that area; when the value is `LevelBarMode::Discrete`,
the widget will draw a succession of separate blocks filling the
draw area, with the number of blocks being equal to the units separating
the integral roundings of `LevelBar:min-value` and `LevelBar:max-value`.
<!-- trait LevelBarExt::fn set_property_mode -->
The `LevelBar:mode` property determines the way `LevelBar`
interprets the value properties to draw the level fill area.
Specifically, when the value is `LevelBarMode::Continuous`,
`LevelBar` will draw a single block representing the current value in
that area; when the value is `LevelBarMode::Discrete`,
the widget will draw a succession of separate blocks filling the
draw area, with the number of blocks being equal to the units separating
the integral roundings of `LevelBar:min-value` and `LevelBar:max-value`.
<!-- trait LevelBarExt::fn get_property_value -->
The `LevelBar:value` property determines the currently
filled value of the level bar.
<!-- trait LevelBarExt::fn set_property_value -->
The `LevelBar:value` property determines the currently
filled value of the level bar.
<!-- enum LevelBarMode -->
Describes how `LevelBar` contents should be rendered.
Note that this enumeration could be extended with additional modes
in the future.
<!-- enum LevelBarMode::variant Continuous -->
the bar has a continuous mode
<!-- enum LevelBarMode::variant Discrete -->
the bar has a discrete mode
<!-- enum License -->
The type of license for an application.

This enumeration can be expanded at later date.
<!-- enum License::variant Unknown -->
No license specified
<!-- enum License::variant Custom -->
A license text is going to be specified by the
 developer
<!-- enum License::variant Gpl20 -->
The GNU General Public License, version 2.0 or later
<!-- enum License::variant Gpl30 -->
The GNU General Public License, version 3.0 or later
<!-- enum License::variant Lgpl21 -->
The GNU Lesser General Public License, version 2.1 or later
<!-- enum License::variant Lgpl30 -->
The GNU Lesser General Public License, version 3.0 or later
<!-- enum License::variant Bsd -->
The BSD standard license
<!-- enum License::variant MitX11 -->
The MIT/X11 standard license
<!-- enum License::variant Artistic -->
The Artistic License, version 2.0
<!-- enum License::variant Gpl20Only -->
The GNU General Public License, version 2.0 only. Since 3.12.
<!-- enum License::variant Gpl30Only -->
The GNU General Public License, version 3.0 only. Since 3.12.
<!-- enum License::variant Lgpl21Only -->
The GNU Lesser General Public License, version 2.1 only. Since 3.12.
<!-- enum License::variant Lgpl30Only -->
The GNU Lesser General Public License, version 3.0 only. Since 3.12.
<!-- enum License::variant Agpl30 -->
The GNU Affero General Public License, version 3.0 or later. Since: 3.22.
<!-- enum License::variant Agpl30Only -->
The GNU Affero General Public License, version 3.0 only. Since: 3.22.27.
<!-- struct LinkButton -->
A `LinkButton` is a `Button` with a hyperlink, similar to the one
used by web browsers, which triggers an action when clicked. It is useful
to show quick links to resources.

A link button is created by calling either `LinkButton::new` or
`LinkButton::new_with_label`. If using the former, the URI you pass
to the constructor is used as a label for the widget.

The URI bound to a `LinkButton` can be set specifically using
`LinkButtonExt::set_uri`, and retrieved using `LinkButtonExt::get_uri`.

By default, `LinkButton` calls `gtk_show_uri_on_window` when the button is
clicked. This behaviour can be overridden by connecting to the
`LinkButton::activate-link` signal and returning `true` from the
signal handler.

# CSS nodes

`LinkButton` has a single CSS node with name button. To differentiate
it from a plain `Button`, it gets the .link style class.

# Implements

[`LinkButtonExt`](trait.LinkButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait LinkButtonExt -->
Trait containing all `LinkButton` methods.

# Implementors

[`LinkButton`](struct.LinkButton.html)
<!-- impl LinkButton::fn new -->
Creates a new `LinkButton` with the URI as its text.
## `uri`
a valid URI

# Returns

a new link button widget.
<!-- impl LinkButton::fn new_with_label -->
Creates a new `LinkButton` containing a label.
## `uri`
a valid URI
## `label`
the text of the button

# Returns

a new link button widget.
<!-- trait LinkButtonExt::fn get_uri -->
Retrieves the URI set using `LinkButtonExt::set_uri`.

# Returns

a valid URI. The returned string is owned by the link button
 and should not be modified or freed.
<!-- trait LinkButtonExt::fn get_visited -->
Retrieves the “visited” state of the URI where the `LinkButton`
points. The button becomes visited when it is clicked. If the URI
is changed on the button, the “visited” state is unset again.

The state may also be changed using `LinkButtonExt::set_visited`.

# Returns

`true` if the link has been visited, `false` otherwise
<!-- trait LinkButtonExt::fn set_uri -->
Sets `uri` as the URI where the `LinkButton` points. As a side-effect
this unsets the “visited” state of the button.
## `uri`
a valid URI
<!-- trait LinkButtonExt::fn set_visited -->
Sets the “visited” state of the URI where the `LinkButton`
points. See `LinkButtonExt::get_visited` for more details.
## `visited`
the new “visited” state
<!-- trait LinkButtonExt::fn connect_activate_link -->
The ::activate-link signal is emitted each time the `LinkButton`
has been clicked.

The default handler will call `gtk_show_uri_on_window` with the URI stored inside
the `LinkButton:uri` property.

To override the default behavior, you can connect to the ::activate-link
signal and stop the propagation of the signal by returning `true` from
your handler.
<!-- trait LinkButtonExt::fn get_property_uri -->
The URI bound to this button.
<!-- trait LinkButtonExt::fn set_property_uri -->
The URI bound to this button.
<!-- trait LinkButtonExt::fn get_property_visited -->
The 'visited' state of this button. A visited link is drawn in a
different color.
<!-- trait LinkButtonExt::fn set_property_visited -->
The 'visited' state of this button. A visited link is drawn in a
different color.
<!-- struct ListBox -->
A `ListBox` is a vertical container that contains `ListBoxRow`
children. These rows can by dynamically sorted and filtered, and
headers can be added dynamically depending on the row content.
It also allows keyboard and mouse navigation and selection like
a typical list.

Using `ListBox` is often an alternative to `TreeView`, especially
when the list contents has a more complicated layout than what is allowed
by a `CellRenderer`, or when the contents is interactive (i.e. has a
button in it).

Although a `ListBox` must have only `ListBoxRow` children you can
add any kind of widget to it via `ContainerExt::add`, and a `ListBoxRow`
widget will automatically be inserted between the list and the widget.

``GtkListBoxRows`` can be marked as activatable or selectable. If a row
is activatable, `ListBox::row-activated` will be emitted for it when
the user tries to activate it. If it is selectable, the row will be marked
as selected when the user tries to select it.

The `ListBox` widget was added in GTK+ 3.10.

# `ListBox` as `Buildable`

The `ListBox` implementation of the `Buildable` interface supports
setting a child as the placeholder by specifying “placeholder” as the “type”
attribute of a `<child>` element. See `ListBoxExt::set_placeholder` for info.

# CSS nodes


```plain
list
╰── row[.activatable]
```

`ListBox` uses a single CSS node named list. Each `ListBoxRow` uses
a single CSS node named row. The row nodes get the .activatable
style class added when appropriate.

# Implements

[`ListBoxExt`](trait.ListBoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ListBoxExtManual`](prelude/trait.ListBoxExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ListBoxExt -->
Trait containing all `ListBox` methods.

# Implementors

[`ListBox`](struct.ListBox.html)
<!-- impl ListBox::fn new -->
Creates a new `ListBox` container.

# Returns

a new `ListBox`
<!-- trait ListBoxExt::fn bind_model -->
Binds `model` to `self`.

If `self` was already bound to a model, that previous binding is
destroyed.

The contents of `self` are cleared and then filled with widgets that
represent items from `model`. `self` is updated whenever `model` changes.
If `model` is `None`, `self` is left empty.

It is undefined to add or remove widgets directly (for example, with
`ListBoxExt::insert` or `ContainerExt::add`) while `self` is bound to a
model.

Note that using a model is incompatible with the filtering and sorting
functionality in `ListBox`. When using a model, filtering and sorting
should be implemented by the model.

Feature: `v3_16`

## `model`
the `gio::ListModel` to be bound to `self`
## `create_widget_func`
a function that creates widgets for items
 or `None` in case you also passed `None` as `model`
## `user_data`
user data passed to `create_widget_func`
## `user_data_free_func`
function for freeing `user_data`
<!-- trait ListBoxExt::fn drag_highlight_row -->
This is a helper function for implementing DnD onto a `ListBox`.
The passed in `row` will be highlighted via `WidgetExt::drag_highlight`,
and any previously highlighted row will be unhighlighted.

The row will also be unhighlighted when the widget gets
a drag leave event.
## `row`
a `ListBoxRow`
<!-- trait ListBoxExt::fn drag_unhighlight_row -->
If a row has previously been highlighted via `ListBoxExt::drag_highlight_row`
it will have the highlight removed.
<!-- trait ListBoxExt::fn get_activate_on_single_click -->
Returns whether rows activate on single clicks.

# Returns

`true` if rows are activated on single click, `false` otherwise
<!-- trait ListBoxExt::fn get_adjustment -->
Gets the adjustment (if any) that the widget uses to
for vertical scrolling.

# Returns

the adjustment
<!-- trait ListBoxExt::fn get_row_at_index -->
Gets the n-th child in the list (not counting headers).
If `_index` is negative or larger than the number of items in the
list, `None` is returned.
## `index_`
the index of the row

# Returns

the child `Widget` or `None`
<!-- trait ListBoxExt::fn get_row_at_y -->
Gets the row at the `y` position.
## `y`
position

# Returns

the row or `None`
 in case no row exists for the given y coordinate.
<!-- trait ListBoxExt::fn get_selected_row -->
Gets the selected row.

Note that the box may allow multiple selection, in which
case you should use `ListBoxExt::selected_foreach` to
find all selected rows.

# Returns

the selected row
<!-- trait ListBoxExt::fn get_selected_rows -->
Creates a list of all selected children.

# Returns


 A `glib::List` containing the `Widget` for each selected child.
 Free with `glib::List::free` when done.
<!-- trait ListBoxExt::fn get_selection_mode -->
Gets the selection mode of the listbox.

# Returns

a `SelectionMode`
<!-- trait ListBoxExt::fn insert -->
Insert the `child` into the `self` at `position`. If a sort function is
set, the widget will actually be inserted at the calculated position and
this function has the same effect of `ContainerExt::add`.

If `position` is -1, or larger than the total number of items in the
`self`, then the `child` will be appended to the end.
## `child`
the `Widget` to add
## `position`
the position to insert `child` in
<!-- trait ListBoxExt::fn invalidate_filter -->
Update the filtering for all rows. Call this when result
of the filter function on the `self` is changed due
to an external factor. For instance, this would be used
if the filter function just looked for a specific search
string and the entry with the search string has changed.
<!-- trait ListBoxExt::fn invalidate_headers -->
Update the separators for all rows. Call this when result
of the header function on the `self` is changed due
to an external factor.
<!-- trait ListBoxExt::fn invalidate_sort -->
Update the sorting for all rows. Call this when result
of the sort function on the `self` is changed due
to an external factor.
<!-- trait ListBoxExt::fn prepend -->
Prepend a widget to the list. If a sort function is set, the widget will
actually be inserted at the calculated position and this function has the
same effect of `ContainerExt::add`.
## `child`
the `Widget` to add
<!-- trait ListBoxExt::fn select_all -->
Select all children of `self`, if the selection mode allows it.
<!-- trait ListBoxExt::fn select_row -->
Make `row` the currently selected row.
## `row`
The row to select or `None`
<!-- trait ListBoxExt::fn selected_foreach -->
Calls a function for each selected child.

Note that the selection cannot be modified from within this function.
## `func`
the function to call for each selected child
## `data`
user data to pass to the function
<!-- trait ListBoxExt::fn set_activate_on_single_click -->
If `single` is `true`, rows will be activated when you click on them,
otherwise you need to double-click.
## `single`
a boolean
<!-- trait ListBoxExt::fn set_adjustment -->
Sets the adjustment (if any) that the widget uses to
for vertical scrolling. For instance, this is used
to get the page size for PageUp/Down key handling.

In the normal case when the `self` is packed inside
a `ScrolledWindow` the adjustment from that will
be picked up automatically, so there is no need
to manually do that.
## `adjustment`
the adjustment, or `None`
<!-- trait ListBoxExt::fn set_filter_func -->
By setting a filter function on the `self` one can decide dynamically which
of the rows to show. For instance, to implement a search function on a list that
filters the original list to only show the matching rows.

The `filter_func` will be called for each row after the call, and it will
continue to be called each time a row changes (via `ListBoxRowExt::changed`) or
when `ListBoxExt::invalidate_filter` is called.

Note that using a filter function is incompatible with using a model
(see `ListBoxExt::bind_model`).
## `filter_func`
callback that lets you filter which rows to show
## `user_data`
user data passed to `filter_func`
## `destroy`
destroy notifier for `user_data`
<!-- trait ListBoxExt::fn set_header_func -->
By setting a header function on the `self` one can dynamically add headers
in front of rows, depending on the contents of the row and its position in the list.
For instance, one could use it to add headers in front of the first item of a
new kind, in a list sorted by the kind.

The `update_header` can look at the current header widget using `ListBoxRowExt::get_header`
and either update the state of the widget as needed, or set a new one using
`ListBoxRowExt::set_header`. If no header is needed, set the header to `None`.

Note that you may get many calls `update_header` to this for a particular row when e.g.
changing things that don’t affect the header. In this case it is important for performance
to not blindly replace an existing header with an identical one.

The `update_header` function will be called for each row after the call, and it will
continue to be called each time a row changes (via `ListBoxRowExt::changed`) and when
the row before changes (either by `ListBoxRowExt::changed` on the previous row, or when
the previous row becomes a different row). It is also called for all rows when
`ListBoxExt::invalidate_headers` is called.
## `update_header`
callback that lets you add row headers
## `user_data`
user data passed to `update_header`
## `destroy`
destroy notifier for `user_data`
<!-- trait ListBoxExt::fn set_placeholder -->
Sets the placeholder widget that is shown in the list when
it doesn't display any visible children.
## `placeholder`
a `Widget` or `None`
<!-- trait ListBoxExt::fn set_selection_mode -->
Sets how selection works in the listbox.
See `SelectionMode` for details.
## `mode`
The `SelectionMode`
<!-- trait ListBoxExt::fn set_sort_func -->
By setting a sort function on the `self` one can dynamically reorder the rows
of the list, based on the contents of the rows.

The `sort_func` will be called for each row after the call, and will continue to
be called each time a row changes (via `ListBoxRowExt::changed`) and when
`ListBoxExt::invalidate_sort` is called.

Note that using a sort function is incompatible with using a model
(see `ListBoxExt::bind_model`).
## `sort_func`
the sort function
## `user_data`
user data passed to `sort_func`
## `destroy`
destroy notifier for `user_data`
<!-- trait ListBoxExt::fn unselect_all -->
Unselect all children of `self`, if the selection mode allows it.
<!-- trait ListBoxExt::fn unselect_row -->
Unselects a single row of `self`, if the selection mode allows it.
## `row`
the row to unselected
<!-- trait ListBoxExt::fn connect_row_activated -->
The ::row-activated signal is emitted when a row has been activated by the user.
## `row`
the activated row
<!-- trait ListBoxExt::fn connect_row_selected -->
The ::row-selected signal is emitted when a new row is selected, or
(with a `None` `row`) when the selection is cleared.

When the `box_` is using `SelectionMode::Multiple`, this signal will not
give you the full picture of selection changes, and you should use
the `ListBox::selected-rows-changed` signal instead.
## `row`
the selected row
<!-- trait ListBoxExt::fn connect_select_all -->
The ::select-all signal is a [keybinding signal][`BindingSignal`]
which gets emitted to select all children of the box, if the selection
mode permits it.

The default bindings for this signal is Ctrl-a.
<!-- trait ListBoxExt::fn connect_selected_rows_changed -->
The ::selected-rows-changed signal is emitted when the
set of selected rows changes.
<!-- trait ListBoxExt::fn connect_unselect_all -->
The ::unselect-all signal is a [keybinding signal][`BindingSignal`]
which gets emitted to unselect all children of the box, if the selection
mode permits it.

The default bindings for this signal is Ctrl-Shift-a.
<!-- struct ListBoxRow -->


# Implements

[`ListBoxRowExt`](trait.ListBoxRowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ListBoxRowExt -->
Trait containing all `ListBoxRow` methods.

# Implementors

[`ListBoxRow`](struct.ListBoxRow.html)
<!-- impl ListBoxRow::fn new -->
Creates a new `ListBoxRow`, to be used as a child of a `ListBox`.

# Returns

a new `ListBoxRow`
<!-- trait ListBoxRowExt::fn changed -->
Marks `self` as changed, causing any state that depends on this
to be updated. This affects sorting, filtering and headers.

Note that calls to this method must be in sync with the data
used for the row functions. For instance, if the list is
mirroring some external data set, and *two* rows changed in the
external data set then when you call `ListBoxRowExt::changed`
on the first row the sort function must only read the new data
for the first of the two changed rows, otherwise the resorting
of the rows will be wrong.

This generally means that if you don’t fully control the data
model you have to duplicate the data that affects the listbox
row functions into the row widgets themselves. Another alternative
is to call `ListBoxExt::invalidate_sort` on any model change,
but that is more expensive.
<!-- trait ListBoxRowExt::fn get_activatable -->
Gets the value of the `ListBoxRow:activatable` property
for this row.

# Returns

`true` if the row is activatable
<!-- trait ListBoxRowExt::fn get_header -->
Returns the current header of the `self`. This can be used
in a ``GtkListBoxUpdateHeaderFunc`` to see if there is a header
set already, and if so to update the state of it.

# Returns

the current header, or `None` if none
<!-- trait ListBoxRowExt::fn get_index -->
Gets the current index of the `self` in its `ListBox` container.

# Returns

the index of the `self`, or -1 if the `self` is not in a listbox
<!-- trait ListBoxRowExt::fn get_selectable -->
Gets the value of the `ListBoxRow:selectable` property
for this row.

# Returns

`true` if the row is selectable
<!-- trait ListBoxRowExt::fn is_selected -->
Returns whether the child is currently selected in its
`ListBox` container.

# Returns

`true` if `self` is selected
<!-- trait ListBoxRowExt::fn set_activatable -->
Set the `ListBoxRow:activatable` property for this row.
## `activatable`
`true` to mark the row as activatable
<!-- trait ListBoxRowExt::fn set_header -->
Sets the current header of the `self`. This is only allowed to be called
from a ``GtkListBoxUpdateHeaderFunc``. It will replace any existing
header in the row, and be shown in front of the row in the listbox.
## `header`
the header, or `None`
<!-- trait ListBoxRowExt::fn set_selectable -->
Set the `ListBoxRow:selectable` property for this row.
## `selectable`
`true` to mark the row as selectable
<!-- trait ListBoxRowExt::fn connect_activate -->
This is a keybinding signal, which will cause this row to be activated.

If you want to be notified when the user activates a row (by key or not),
use the `ListBox::row-activated` signal on the row’s parent `ListBox`.
<!-- trait ListBoxRowExt::fn get_property_activatable -->
The property determines whether the `ListBox::row-activated`
signal will be emitted for this row.
<!-- trait ListBoxRowExt::fn set_property_activatable -->
The property determines whether the `ListBox::row-activated`
signal will be emitted for this row.
<!-- trait ListBoxRowExt::fn get_property_selectable -->
The property determines whether this row can be selected.
<!-- trait ListBoxRowExt::fn set_property_selectable -->
The property determines whether this row can be selected.
<!-- struct ListStore -->
The `ListStore` object is a list model for use with a `TreeView`
widget. It implements the `TreeModel` interface, and consequentialy,
can use all of the methods available there. It also implements the
`TreeSortable` interface so it can be sorted by the view.
Finally, it also implements the tree
[drag and drop][gtk3-`TreeView`-drag-and-drop]
interfaces.

The `ListStore` can accept most GObject types as a column type, though
it can’t accept all custom types. Internally, it will keep a copy of
data passed in (such as a string or a boxed pointer). Columns that
accept `GObjects` are handled a little differently. The
`ListStore` will keep a reference to the object instead of copying the
value. As a result, if the object is modified, it is up to the
application writer to call `TreeModel::row_changed` to emit the
`TreeModel::row_changed` signal. This most commonly affects lists with
``GdkPixbufs`` stored.

An example for creating a simple list store:

```C
enum {
  COLUMN_STRING,
  COLUMN_INT,
  COLUMN_BOOLEAN,
  N_COLUMNS
};

{
  GtkListStore *list_store;
  GtkTreePath *path;
  GtkTreeIter iter;
  gint i;

  list_store = gtk_list_store_new (N_COLUMNS,
                                   G_TYPE_STRING,
                                   G_TYPE_INT,
                                   G_TYPE_BOOLEAN);

  for (i = 0; i < 10; i++)
    {
      gchar *some_data;

      some_data = get_some_data (i);

      // Add a new row to the model
      gtk_list_store_append (list_store, &iter);
      gtk_list_store_set (list_store, &iter,
                          COLUMN_STRING, some_data,
                          COLUMN_INT, i,
                          COLUMN_BOOLEAN,  FALSE,
                          -1);

      // As the store will keep a copy of the string internally,
      // we free some_data.
      g_free (some_data);
    }

  // Modify a particular row
  path = gtk_tree_path_new_from_string ("4");
  gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
                           &iter,
                           path);
  gtk_tree_path_free (path);
  gtk_list_store_set (list_store, &iter,
                      COLUMN_BOOLEAN, TRUE,
                      -1);
}
```

# Performance Considerations

Internally, the `ListStore` was implemented with a linked list with
a tail pointer prior to GTK+ 2.6. As a result, it was fast at data
insertion and deletion, and not fast at random data access. The
`ListStore` sets the `TreeModelFlags::ItersPersist` flag, which means
that ``GtkTreeIters`` can be cached while the row exists. Thus, if
access to a particular row is needed often and your code is expected to
run on older versions of GTK+, it is worth keeping the iter around.

# Atomic Operations

It is important to note that only the methods
`GtkListStoreExt::insert_with_values` and `GtkListStoreExt::insert_with_valuesv`
are atomic, in the sense that the row is being appended to the store and the
values filled in in a single operation with regard to `TreeModel` signaling.
In contrast, using e.g. `GtkListStoreExt::append` and then `GtkListStoreExt::set`
will first create a row, which triggers the `TreeModel::row-inserted` signal
on `ListStore`. The row, however, is still empty, and any signal handler
connecting to `TreeModel::row-inserted` on this particular store should be prepared
for the situation that the row might be empty. This is especially important
if you are wrapping the `ListStore` inside a `TreeModelFilter` and are
using a ``GtkTreeModelFilterVisibleFunc``. Using any of the non-atomic operations
to append rows to the `ListStore` will cause the
``GtkTreeModelFilterVisibleFunc`` to be visited with an empty row first; the
function must be prepared for that.

# `ListStore` as `Buildable`

The `ListStore` implementation of the `Buildable` interface allows
to specify the model columns with a `<columns>` element that may contain
multiple `<column>` elements, each specifying one model column. The “type”
attribute specifies the data type for the column.

Additionally, it is possible to specify content for the list store
in the UI definition, with the `<data>` element. It can contain multiple
`<row>` elements, each specifying to content for one row of the list model.
Inside a `<row>`, the `<col>` elements specify the content for individual cells.

Note that it is probably more common to define your models in the code,
and one might consider it a layering violation to specify the content of
a list store in a UI definition, data, not presentation, and common wisdom
is to separate the two, as far as possible.

An example of a UI Definition fragment for a list store:

```C
<object class="GtkListStore">
  <columns>
    <column type="gchararray"/>
    <column type="gchararray"/>
    <column type="gint"/>
  </columns>
  <data>
    <row>
      <col id="0">John</col>
      <col id="1">Doe</col>
      <col id="2">25</col>
    </row>
    <row>
      <col id="0">Johan</col>
      <col id="1">Dahlin</col>
      <col id="2">50</col>
    </row>
  </data>
</object>
```

# Implements

[`GtkListStoreExt`](trait.GtkListStoreExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`TreeDragDestExt`](trait.TreeDragDestExt.html), [`TreeDragSourceExt`](trait.TreeDragSourceExt.html), [`TreeModelExt`](trait.TreeModelExt.html), [`TreeSortableExt`](trait.TreeSortableExt.html), [`GtkListStoreExtManual`](prelude/trait.GtkListStoreExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`TreeSortableExtManual`](prelude/trait.TreeSortableExtManual.html)
<!-- trait GtkListStoreExt -->
Trait containing all `ListStore` methods.

# Implementors

[`ListStore`](struct.ListStore.html)
<!-- impl ListStore::fn new -->
Creates a new list store as with `n_columns` columns each of the types passed
in. Note that only types derived from standard GObject fundamental types
are supported.

As an example, `gtk_list_store_new (3, G_TYPE_INT, G_TYPE_STRING,
GDK_TYPE_PIXBUF);` will create a new `ListStore` with three columns, of type
int, string and `gdk_pixbuf::Pixbuf` respectively.
## `n_columns`
number of columns in the list store

# Returns

a new `ListStore`
<!-- impl ListStore::fn newv -->
Non-vararg creation function. Used primarily by language bindings.
## `n_columns`
number of columns in the list store
## `types`
an array of `glib::Type` types for the columns, from first to last

# Returns

a new `ListStore`
<!-- trait GtkListStoreExt::fn append -->
Appends a new row to `self`. `iter` will be changed to point to this new
row. The row will be empty after this function is called. To fill in
values, you need to call `GtkListStoreExt::set` or `ListStore::set_value`.
## `iter`
An unset `TreeIter` to set to the appended row
<!-- trait GtkListStoreExt::fn clear -->
Removes all rows from the list store.
<!-- trait GtkListStoreExt::fn insert -->
Creates a new row at `position`. `iter` will be changed to point to this new
row. If `position` is -1 or is larger than the number of rows on the list,
then the new row will be appended to the list. The row will be empty after
this function is called. To fill in values, you need to call
`GtkListStoreExt::set` or `ListStore::set_value`.
## `iter`
An unset `TreeIter` to set to the new row
## `position`
position to insert the new row, or -1 for last
<!-- trait GtkListStoreExt::fn insert_after -->
Inserts a new row after `sibling`. If `sibling` is `None`, then the row will be
prepended to the beginning of the list. `iter` will be changed to point to
this new row. The row will be empty after this function is called. To fill
in values, you need to call `GtkListStoreExt::set` or `ListStore::set_value`.
## `iter`
An unset `TreeIter` to set to the new row
## `sibling`
A valid `TreeIter`, or `None`
<!-- trait GtkListStoreExt::fn insert_before -->
Inserts a new row before `sibling`. If `sibling` is `None`, then the row will
be appended to the end of the list. `iter` will be changed to point to this
new row. The row will be empty after this function is called. To fill in
values, you need to call `GtkListStoreExt::set` or `ListStore::set_value`.
## `iter`
An unset `TreeIter` to set to the new row
## `sibling`
A valid `TreeIter`, or `None`
<!-- trait GtkListStoreExt::fn insert_with_values -->
Creates a new row at `position`. `iter` will be changed to point to this new
row. If `position` is -1, or larger than the number of rows in the list, then
the new row will be appended to the list. The row will be filled with the
values given to this function.

Calling
`gtk_list_store_insert_with_values (list_store, iter, position...)`
has the same effect as calling

```C
static void
insert_value (GtkListStore *list_store,
              GtkTreeIter  *iter,
              int           position)
{
  gtk_list_store_insert (list_store, iter, position);
  gtk_list_store_set (list_store,
                      iter
                      // ...
                      );
}
```
with the difference that the former will only emit a row_inserted signal,
while the latter will emit row_inserted, row_changed and, if the list store
is sorted, rows_reordered. Since emitting the rows_reordered signal
repeatedly can affect the performance of the program,
`GtkListStoreExt::insert_with_values` should generally be preferred when
inserting rows in a sorted list store.
## `iter`
An unset `TreeIter` to set to the new row, or `None`
## `position`
position to insert the new row, or -1 to append after existing
 rows
<!-- trait GtkListStoreExt::fn insert_with_valuesv -->
A variant of `GtkListStoreExt::insert_with_values` which
takes the columns and values as two arrays, instead of
varargs. This function is mainly intended for
language-bindings.
## `iter`
An unset `TreeIter` to set to the new row, or `None`.
## `position`
position to insert the new row, or -1 for last
## `columns`
an array of column numbers
## `values`
an array of GValues
## `n_values`
the length of the `columns` and `values` arrays
<!-- trait GtkListStoreExt::fn iter_is_valid -->
> This function is slow. Only use it for debugging and/or testing
> purposes.

Checks if the given iter is a valid iter for this `ListStore`.
## `iter`
A `TreeIter`.

# Returns

`true` if the iter is valid, `false` if the iter is invalid.
<!-- trait GtkListStoreExt::fn move_after -->
Moves `iter` in `self` to the position after `position`. Note that this
function only works with unsorted stores. If `position` is `None`, `iter`
will be moved to the start of the list.
## `iter`
A `TreeIter`.
## `position`
A `TreeIter` or `None`.
<!-- trait GtkListStoreExt::fn move_before -->
Moves `iter` in `self` to the position before `position`. Note that this
function only works with unsorted stores. If `position` is `None`, `iter`
will be moved to the end of the list.
## `iter`
A `TreeIter`.
## `position`
A `TreeIter`, or `None`.
<!-- trait GtkListStoreExt::fn prepend -->
Prepends a new row to `self`. `iter` will be changed to point to this new
row. The row will be empty after this function is called. To fill in
values, you need to call `GtkListStoreExt::set` or `ListStore::set_value`.
## `iter`
An unset `TreeIter` to set to the prepend row
<!-- trait GtkListStoreExt::fn remove -->
Removes the given row from the list store. After being removed,
`iter` is set to be the next valid row, or invalidated if it pointed
to the last row in `self`.
## `iter`
A valid `TreeIter`

# Returns

`true` if `iter` is valid, `false` if not.
<!-- trait GtkListStoreExtManual::fn reorder -->
Reorders `self` to follow the order indicated by `new_order`. Note that
this function only works with unsorted stores.
## `new_order`
an array of integers mapping the new
 position of each child to its old position before the re-ordering,
 i.e. `new_order``[newpos] = oldpos`. It must have
 exactly as many items as the list store’s length.
<!-- trait GtkListStoreExt::fn set -->
Sets the value of one or more cells in the row referenced by `iter`.
The variable argument list should contain integer column numbers,
each column number followed by the value to be set.
The list is terminated by a -1. For example, to set column 0 with type
`G_TYPE_STRING` to “Foo”, you would write `gtk_list_store_set (store, iter,
0, "Foo", -1)`.

The value will be referenced by the store if it is a `G_TYPE_OBJECT`, and it
will be copied if it is a `G_TYPE_STRING` or `G_TYPE_BOXED`.
## `iter`
row iterator
<!-- trait GtkListStoreExt::fn set_column_types -->
This function is meant primarily for `GObjects` that inherit from `ListStore`,
and should only be used when constructing a new `ListStore`. It will not
function after a row has been added, or a method on the `TreeModel`
interface is called.
## `n_columns`
Number of columns for the list store
## `types`
An array length n of `GTypes`
<!-- trait GtkListStoreExt::fn set_valist -->
See `GtkListStoreExt::set`; this version takes a va_list for use by language
bindings.
## `iter`
A valid `TreeIter` for the row being modified
## `var_args`
va_list of column/value pairs
<!-- trait GtkListStoreExtManual::fn set_value -->
Sets the data in the cell specified by `iter` and `column`.
The type of `value` must be convertible to the type of the
column.
## `iter`
A valid `TreeIter` for the row being modified
## `column`
column number to modify
## `value`
new value for the cell
<!-- trait GtkListStoreExt::fn set_valuesv -->
A variant of `GtkListStoreExt::set_valist` which
takes the columns and values as two arrays, instead of
varargs. This function is mainly intended for
language-bindings and in case the number of columns to
change is not known until run-time.
## `iter`
A valid `TreeIter` for the row being modified
## `columns`
an array of column numbers
## `values`
an array of GValues
## `n_values`
the length of the `columns` and `values` arrays
<!-- trait GtkListStoreExt::fn swap -->
Swaps `a` and `b` in `self`. Note that this function only works with
unsorted stores.
## `a`
A `TreeIter`.
## `b`
Another `TreeIter`.
<!-- struct LockButton -->
`LockButton` is a widget that can be used in control panels or
preference dialogs to allow users to obtain and revoke authorizations
needed to operate the controls. The required authorization is represented
by a `gio::Permission` object. Concrete implementations of `gio::Permission` may use
PolicyKit or some other authorization framework. To obtain a PolicyKit-based
`gio::Permission`, use `polkit_permission_new`.

If the user is not currently allowed to perform the action, but can obtain
the permission, the widget looks like this:

![](lockbutton-locked.png)

and the user can click the button to request the permission. Depending
on the platform, this may pop up an authentication dialog or ask the user
to authenticate in some other way. Once the user has obtained the permission,
the widget changes to this:

![](lockbutton-unlocked.png)

and the permission can be dropped again by clicking the button. If the user
is not able to obtain the permission at all, the widget looks like this:

![](lockbutton-sorry.png)

If the user has the permission and cannot drop it, the button is hidden.

The text (and tooltips) that are shown in the various cases can be adjusted
with the `LockButton:text-lock`, `LockButton:text-unlock`,
`LockButton:tooltip-lock`, `LockButton:tooltip-unlock` and
`LockButton:tooltip-not-authorized` properties.

# Implements

[`LockButtonExt`](trait.LockButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait LockButtonExt -->
Trait containing all `LockButton` methods.

# Implementors

[`LockButton`](struct.LockButton.html)
<!-- impl LockButton::fn new -->
Creates a new lock button which reflects the `permission`.
## `permission`
a `gio::Permission`

# Returns

a new `LockButton`
<!-- trait LockButtonExt::fn get_permission -->
Obtains the `gio::Permission` object that controls `self`.

# Returns

the `gio::Permission` of `self`
<!-- trait LockButtonExt::fn set_permission -->
Sets the `gio::Permission` object that controls `self`.
## `permission`
a `gio::Permission` object, or `None`
<!-- struct Menu -->
A `Menu` is a `MenuShell` that implements a drop down menu
consisting of a list of `MenuItem` objects which can be navigated
and activated by the user to perform application functions.

A `Menu` is most commonly dropped down by activating a
`MenuItem` in a `MenuBar` or popped up by activating a
`MenuItem` in another `Menu`.

A `Menu` can also be popped up by activating a `ComboBox`.
Other composite widgets such as the `Notebook` can pop up a
`Menu` as well.

Applications can display a `Menu` as a popup menu by calling the
`GtkMenuExt::popup` function. The example below shows how an application
can pop up a menu when the 3rd mouse button is pressed.

## Connecting the popup signal handler.


```C
  // connect our handler which will popup the menu
  g_signal_connect_swapped (window, "button_press_event",
G_CALLBACK (my_popup_handler), menu);
```

## Signal handler which displays a popup menu.


```C
static gint
my_popup_handler (GtkWidget *widget, GdkEvent *event)
{
  GtkMenu *menu;
  GdkEventButton *event_button;

  g_return_val_if_fail (widget != NULL, FALSE);
  g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
  g_return_val_if_fail (event != NULL, FALSE);

  // The "widget" is the menu that was supplied when
  // g_signal_connect_swapped() was called.
  menu = GTK_MENU (widget);

  if (event->type == GDK_BUTTON_PRESS)
    {
      event_button = (GdkEventButton *) event;
      if (event_button->button == GDK_BUTTON_SECONDARY)
        {
          gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
                          event_button->button, event_button->time);
          return TRUE;
        }
    }

  return FALSE;
}
```

# CSS nodes


```plain
menu
├── arrow.top
├── <child>
┊
├── <child>
╰── arrow.bottom
```

The main CSS node of `Menu` has name menu, and there are two subnodes
with name arrow, for scrolling menu arrows. These subnodes get the
.top and .bottom style classes.

# Implements

[`GtkMenuExt`](trait.GtkMenuExt.html), [`MenuShellExt`](trait.MenuShellExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`GtkMenuExtManual`](prelude/trait.GtkMenuExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait GtkMenuExt -->
Trait containing all `Menu` methods.

# Implementors

[`Menu`](struct.Menu.html), [`RecentChooserMenu`](struct.RecentChooserMenu.html)
<!-- impl Menu::fn new -->
Creates a new `Menu`

# Returns

a new `Menu`
<!-- impl Menu::fn new_from_model -->
Creates a `Menu` and populates it with menu items and
submenus according to `model`.

The created menu items are connected to actions found in the
`ApplicationWindow` to which the menu belongs - typically
by means of being attached to a widget (see `GtkMenuExt::attach_to_widget`)
that is contained within the ``GtkApplicationWindows`` widget hierarchy.

Actions can also be added using `WidgetExt::insert_action_group` on the menu's
attach widget or on any of its parent widgets.
## `model`
a `gio::MenuModel`

# Returns

a new `Menu`
<!-- impl Menu::fn get_for_attach_widget -->
Returns a list of the menus which are attached to this widget.
This list is owned by GTK+ and must not be modified.
## `widget`
a `Widget`

# Returns

the list
 of menus attached to his widget.
<!-- trait GtkMenuExt::fn attach -->
Adds a new `MenuItem` to a (table) menu. The number of “cells” that
an item will occupy is specified by `left_attach`, `right_attach`,
`top_attach` and `bottom_attach`. These each represent the leftmost,
rightmost, uppermost and lower column and row numbers of the table.
(Columns and rows are indexed from zero).

Note that this function is not related to `GtkMenuExt::detach`.
## `child`
a `MenuItem`
## `left_attach`
The column number to attach the left side of the item to
## `right_attach`
The column number to attach the right side of the item to
## `top_attach`
The row number to attach the top of the item to
## `bottom_attach`
The row number to attach the bottom of the item to
<!-- trait GtkMenuExt::fn attach_to_widget -->
Attaches the menu to the widget and provides a callback function
that will be invoked when the menu calls `GtkMenuExt::detach` during
its destruction.

If the menu is attached to the widget then it will be destroyed
when the widget is destroyed, as if it was a child widget.
An attached menu will also move between screens correctly if the
widgets moves between screens.
## `attach_widget`
the `Widget` that the menu will be attached to
## `detacher`
the user supplied callback function
 that will be called when the menu calls `GtkMenuExt::detach`
<!-- trait GtkMenuExt::fn detach -->
Detaches the menu from the widget to which it had been attached.
This function will call the callback function, `detacher`, provided
when the `GtkMenuExt::attach_to_widget` function was called.
<!-- trait GtkMenuExt::fn get_accel_group -->
Gets the `AccelGroup` which holds global accelerators for the
menu. See `GtkMenuExt::set_accel_group`.

# Returns

the `AccelGroup` associated with the menu
<!-- trait GtkMenuExt::fn get_accel_path -->
Retrieves the accelerator path set on the menu.

# Returns

the accelerator path set on the menu.
<!-- trait GtkMenuExt::fn get_active -->
Returns the selected menu item from the menu. This is used by the
`ComboBox`.

# Returns

the `MenuItem` that was last selected
 in the menu. If a selection has not yet been made, the
 first menu item is selected.
<!-- trait GtkMenuExt::fn get_attach_widget -->
Returns the `Widget` that the menu is attached to.

# Returns

the `Widget` that the menu is attached to
<!-- trait GtkMenuExt::fn get_monitor -->
Retrieves the number of the monitor on which to show the menu.

# Returns

the number of the monitor on which the menu should
 be popped up or -1, if no monitor has been set
<!-- trait GtkMenuExt::fn get_reserve_toggle_size -->
Returns whether the menu reserves space for toggles and
icons, regardless of their actual presence.

# Returns

Whether the menu reserves toggle space
<!-- trait GtkMenuExt::fn place_on_monitor -->
Places `self` on the given monitor.

Feature: `v3_22`

## `monitor`
the monitor to place the menu on
<!-- trait GtkMenuExt::fn popdown -->
Removes the menu from the screen.
<!-- trait GtkMenuExt::fn popup -->
Displays a menu and makes it available for selection.

Applications can use this function to display context-sensitive
menus, and will typically supply `None` for the `parent_menu_shell`,
`parent_menu_item`, `func` and `data` parameters. The default menu
positioning function will position the menu at the current mouse
cursor position.

The `button` parameter should be the mouse button pressed to initiate
the menu popup. If the menu popup was initiated by something other
than a mouse button press, such as a mouse button release or a keypress,
`button` should be 0.

The `activate_time` parameter is used to conflict-resolve initiation
of concurrent requests for mouse/keyboard grab requests. To function
properly, this needs to be the timestamp of the user event (such as
a mouse click or key press) that caused the initiation of the popup.
Only if no such event is available, `gtk_get_current_event_time` can
be used instead.

Note that this function does not work very well on GDK backends that
do not have global coordinates, such as Wayland or Mir. You should
probably use one of the gtk_menu_popup_at_ variants, which do not
have this problem.

# Deprecated since 3.22

Please use `GtkMenuExt::popup_at_widget`,
 `GtkMenuExt::popup_at_pointer`. or `GtkMenuExt::popup_at_rect` instead
## `parent_menu_shell`
the menu shell containing the
 triggering menu item, or `None`
## `parent_menu_item`
the menu item whose activation
 triggered the popup, or `None`
## `func`
a user supplied function used to position
 the menu, or `None`
## `data`
user supplied data to be passed to `func`.
## `button`
the mouse button which was pressed to initiate the event.
## `activate_time`
the time at which the activation event occurred.
<!-- trait GtkMenuExt::fn popup_at_pointer -->
Displays `self` and makes it available for selection.

See gtk_menu_popup_at_widget () to pop up a menu at a widget.
gtk_menu_popup_at_rect () also allows you to position a menu at an arbitrary
rectangle.

`self` will be positioned at the pointer associated with `trigger_event`.

Properties that influence the behaviour of this function are
`Menu:anchor-hints`, `Menu:rect-anchor-dx`, `Menu:rect-anchor-dy`, and
`Menu:menu-type-hint`. Connect to the `Menu::popped-up` signal to find
out how it was actually positioned.

Feature: `v3_22`

## `trigger_event`
the ``GdkEvent`` that initiated this request or
 `None` if it's the current event
<!-- trait GtkMenuExt::fn popup_at_rect -->
Displays `self` and makes it available for selection.

See gtk_menu_popup_at_widget () and gtk_menu_popup_at_pointer (), which
handle more common cases for popping up menus.

`self` will be positioned at `rect`, aligning their anchor points. `rect` is
relative to the top-left corner of `rect_window`. `rect_anchor` and
`menu_anchor` determine anchor points on `rect` and `self` to pin together.
`self` can optionally be offset by `Menu:rect-anchor-dx` and
`Menu:rect-anchor-dy`.

Anchors should be specified under the assumption that the text direction is
left-to-right; they will be flipped horizontally automatically if the text
direction is right-to-left.

Other properties that influence the behaviour of this function are
`Menu:anchor-hints` and `Menu:menu-type-hint`. Connect to the
`Menu::popped-up` signal to find out how it was actually positioned.

Feature: `v3_22`

## `rect_window`
the `gdk::Window` `rect` is relative to
## `rect`
the `gdk::Rectangle` to align `self` with
## `rect_anchor`
the point on `rect` to align with `self`'s anchor point
## `menu_anchor`
the point on `self` to align with `rect`'s anchor point
## `trigger_event`
the ``GdkEvent`` that initiated this request or
 `None` if it's the current event
<!-- trait GtkMenuExt::fn popup_at_widget -->
Displays `self` and makes it available for selection.

See gtk_menu_popup_at_pointer () to pop up a menu at the master pointer.
gtk_menu_popup_at_rect () also allows you to position a menu at an arbitrary
rectangle.

![](popup-anchors.png)

`self` will be positioned at `widget`, aligning their anchor points.
`widget_anchor` and `menu_anchor` determine anchor points on `widget` and `self`
to pin together. `self` can optionally be offset by `Menu:rect-anchor-dx`
and `Menu:rect-anchor-dy`.

Anchors should be specified under the assumption that the text direction is
left-to-right; they will be flipped horizontally automatically if the text
direction is right-to-left.

Other properties that influence the behaviour of this function are
`Menu:anchor-hints` and `Menu:menu-type-hint`. Connect to the
`Menu::popped-up` signal to find out how it was actually positioned.

Feature: `v3_22`

## `widget`
the `Widget` to align `self` with
## `widget_anchor`
the point on `widget` to align with `self`'s anchor point
## `menu_anchor`
the point on `self` to align with `widget`'s anchor point
## `trigger_event`
the ``GdkEvent`` that initiated this request or
 `None` if it's the current event
<!-- trait GtkMenuExt::fn popup_for_device -->
Displays a menu and makes it available for selection.

Applications can use this function to display context-sensitive menus,
and will typically supply `None` for the `parent_menu_shell`,
`parent_menu_item`, `func`, `data` and `destroy` parameters. The default
menu positioning function will position the menu at the current position
of `device` (or its corresponding pointer).

The `button` parameter should be the mouse button pressed to initiate
the menu popup. If the menu popup was initiated by something other than
a mouse button press, such as a mouse button release or a keypress,
`button` should be 0.

The `activate_time` parameter is used to conflict-resolve initiation of
concurrent requests for mouse/keyboard grab requests. To function
properly, this needs to be the time stamp of the user event (such as
a mouse click or key press) that caused the initiation of the popup.
Only if no such event is available, `gtk_get_current_event_time` can
be used instead.

Note that this function does not work very well on GDK backends that
do not have global coordinates, such as Wayland or Mir. You should
probably use one of the gtk_menu_popup_at_ variants, which do not
have this problem.

# Deprecated since 3.22

Please use `GtkMenuExt::popup_at_widget`,
 `GtkMenuExt::popup_at_pointer`. or `GtkMenuExt::popup_at_rect` instead
## `device`
a `gdk::Device`
## `parent_menu_shell`
the menu shell containing the triggering
 menu item, or `None`
## `parent_menu_item`
the menu item whose activation triggered
 the popup, or `None`
## `func`
a user supplied function used to position the menu,
 or `None`
## `data`
user supplied data to be passed to `func`
## `destroy`
destroy notify for `data`
## `button`
the mouse button which was pressed to initiate the event
## `activate_time`
the time at which the activation event occurred
<!-- trait GtkMenuExt::fn reorder_child -->
Moves `child` to a new `position` in the list of `self`
children.
## `child`
the `MenuItem` to move
## `position`
the new position to place `child`.
 Positions are numbered from 0 to n - 1
<!-- trait GtkMenuExt::fn reposition -->
Repositions the menu according to its position function.
<!-- trait GtkMenuExt::fn set_accel_group -->
Set the `AccelGroup` which holds global accelerators for the
menu. This accelerator group needs to also be added to all windows
that this menu is being used in with `GtkWindowExt::add_accel_group`,
in order for those windows to support all the accelerators
contained in this group.
## `accel_group`
the `AccelGroup` to be associated
 with the menu.
<!-- trait GtkMenuExt::fn set_accel_path -->
Sets an accelerator path for this menu from which accelerator paths
for its immediate children, its menu items, can be constructed.
The main purpose of this function is to spare the programmer the
inconvenience of having to call `GtkMenuItemExt::set_accel_path` on
each menu item that should support runtime user changable accelerators.
Instead, by just calling `GtkMenuExt::set_accel_path` on their parent,
each menu item of this menu, that contains a label describing its
purpose, automatically gets an accel path assigned.

For example, a menu containing menu items “New” and “Exit”, will, after
`gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File");` has been
called, assign its items the accel paths: `"<Gnumeric-Sheet>/File/New"`
and `"<Gnumeric-Sheet>/File/Exit"`.

Assigning accel paths to menu items then enables the user to change
their accelerators at runtime. More details about accelerator paths
and their default setups can be found at `AccelMap::add_entry`.

Note that `accel_path` string will be stored in a `glib::Quark`. Therefore,
if you pass a static string, you can save some memory by interning
it first with `g_intern_static_string`.
## `accel_path`
a valid accelerator path, or `None` to unset the path
<!-- trait GtkMenuExt::fn set_active -->
Selects the specified menu item within the menu. This is used by
the `ComboBox` and should not be used by anyone else.
## `index`
the index of the menu item to select. Index values are
 from 0 to n-1
<!-- trait GtkMenuExt::fn set_monitor -->
Informs GTK+ on which monitor a menu should be popped up.
See `gdk::Monitor::get_geometry`.

This function should be called from a ``GtkMenuPositionFunc``
if the menu should not appear on the same monitor as the pointer.
This information can’t be reliably inferred from the coordinates
returned by a ``GtkMenuPositionFunc``, since, for very long menus,
these coordinates may extend beyond the monitor boundaries or even
the screen boundaries.
## `monitor_num`
the number of the monitor on which the menu should
 be popped up
<!-- trait GtkMenuExt::fn set_reserve_toggle_size -->
Sets whether the menu should reserve space for drawing toggles
or icons, regardless of their actual presence.
## `reserve_toggle_size`
whether to reserve size for toggles
<!-- trait GtkMenuExt::fn set_screen -->
Sets the `gdk::Screen` on which the menu will be displayed.
## `screen`
a `gdk::Screen`, or `None` if the screen should be
 determined by the widget the menu is attached to
<!-- trait GtkMenuExt::fn connect_move_scroll -->
## `scroll_type`
a `ScrollType`
<!-- trait GtkMenuExt::fn connect_popped_up -->
Emitted when the position of `menu` is finalized after being popped up
using gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), or
gtk_menu_popup_at_pointer ().

`menu` might be flipped over the anchor rectangle in order to keep it
on-screen, in which case `flipped_x` and `flipped_y` will be set to `true`
accordingly.

`flipped_rect` is the ideal position of `menu` after any possible flipping,
but before any possible sliding. `final_rect` is `flipped_rect`, but possibly
translated in the case that flipping is still ineffective in keeping `menu`
on-screen.

![](popup-slide.png)

The blue menu is `menu`'s ideal position, the green menu is `flipped_rect`,
and the red menu is `final_rect`.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dx`, `Menu:rect-anchor-dy`, and
`Menu:menu-type-hint`.

Feature: `v3_22`

## `flipped_rect`
the position of `menu` after any possible
 flipping or `None` if the backend can't obtain it
## `final_rect`
the final position of `menu` or `None` if the
 backend can't obtain it
## `flipped_x`
`true` if the anchors were flipped horizontally
## `flipped_y`
`true` if the anchors were flipped vertically
<!-- trait GtkMenuExt::fn get_property_accel_group -->
The accel group holding accelerators for the menu.
<!-- trait GtkMenuExt::fn set_property_accel_group -->
The accel group holding accelerators for the menu.
<!-- trait GtkMenuExt::fn get_property_accel_path -->
An accel path used to conveniently construct accel paths of child items.
<!-- trait GtkMenuExt::fn set_property_accel_path -->
An accel path used to conveniently construct accel paths of child items.
<!-- trait GtkMenuExt::fn get_property_active -->
The index of the currently selected menu item, or -1 if no
menu item is selected.
<!-- trait GtkMenuExt::fn set_property_active -->
The index of the currently selected menu item, or -1 if no
menu item is selected.
<!-- trait GtkMenuExt::fn get_property_anchor_hints -->
Positioning hints for aligning the menu relative to a rectangle.

These hints determine how the menu should be positioned in the case that
the menu would fall off-screen if placed in its ideal position.

![](popup-flip.png)

For example, `gdk::AnchorHints::FlipY` will replace `gdk::Gravity::NorthWest` with
`gdk::Gravity::SouthWest` and vice versa if the menu extends beyond the
bottom edge of the monitor.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:rect-anchor-dx`,
`Menu:rect-anchor-dy`, `Menu:menu-type-hint`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn set_property_anchor_hints -->
Positioning hints for aligning the menu relative to a rectangle.

These hints determine how the menu should be positioned in the case that
the menu would fall off-screen if placed in its ideal position.

![](popup-flip.png)

For example, `gdk::AnchorHints::FlipY` will replace `gdk::Gravity::NorthWest` with
`gdk::Gravity::SouthWest` and vice versa if the menu extends beyond the
bottom edge of the monitor.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:rect-anchor-dx`,
`Menu:rect-anchor-dy`, `Menu:menu-type-hint`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn get_property_attach_widget -->
The widget the menu is attached to. Setting this property attaches
the menu without a ``GtkMenuDetachFunc``. If you need to use a detacher,
use `GtkMenuExt::attach_to_widget` directly.
<!-- trait GtkMenuExt::fn set_property_attach_widget -->
The widget the menu is attached to. Setting this property attaches
the menu without a ``GtkMenuDetachFunc``. If you need to use a detacher,
use `GtkMenuExt::attach_to_widget` directly.
<!-- trait GtkMenuExt::fn get_property_menu_type_hint -->
The `gdk::WindowTypeHint` to use for the menu's `gdk::Window`.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dx`, `Menu:rect-anchor-dy`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn set_property_menu_type_hint -->
The `gdk::WindowTypeHint` to use for the menu's `gdk::Window`.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dx`, `Menu:rect-anchor-dy`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn get_property_monitor -->
The monitor the menu will be popped up on.
<!-- trait GtkMenuExt::fn set_property_monitor -->
The monitor the menu will be popped up on.
<!-- trait GtkMenuExt::fn get_property_rect_anchor_dx -->
Horizontal offset to apply to the menu, i.e. the rectangle or widget
anchor.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dy`, `Menu:menu-type-hint`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn set_property_rect_anchor_dx -->
Horizontal offset to apply to the menu, i.e. the rectangle or widget
anchor.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dy`, `Menu:menu-type-hint`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn get_property_rect_anchor_dy -->
Vertical offset to apply to the menu, i.e. the rectangle or widget anchor.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dx`, `Menu:menu-type-hint`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn set_property_rect_anchor_dy -->
Vertical offset to apply to the menu, i.e. the rectangle or widget anchor.

See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (),
gtk_menu_popup_at_pointer (), `Menu:anchor-hints`,
`Menu:rect-anchor-dx`, `Menu:menu-type-hint`, and `Menu::popped-up`.

Feature: `v3_22`

<!-- trait GtkMenuExt::fn get_property_reserve_toggle_size -->
A boolean that indicates whether the menu reserves space for
toggles and icons, regardless of their actual presence.

This property should only be changed from its default value
for special-purposes such as tabular menus. Regular menus that
are connected to a menu bar or context menus should reserve
toggle space for consistency.
<!-- trait GtkMenuExt::fn set_property_reserve_toggle_size -->
A boolean that indicates whether the menu reserves space for
toggles and icons, regardless of their actual presence.

This property should only be changed from its default value
for special-purposes such as tabular menus. Regular menus that
are connected to a menu bar or context menus should reserve
toggle space for consistency.
<!-- struct MenuBar -->
The `MenuBar` is a subclass of `MenuShell` which contains one or
more ``GtkMenuItems``. The result is a standard menu bar which can hold
many menu items.

# CSS nodes

`MenuBar` has a single CSS node with name menubar.

# Implements

[`MenuBarExt`](trait.MenuBarExt.html), [`MenuShellExt`](trait.MenuShellExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait MenuBarExt -->
Trait containing all `MenuBar` methods.

# Implementors

[`MenuBar`](struct.MenuBar.html)
<!-- impl MenuBar::fn new -->
Creates a new `MenuBar`

# Returns

the new menu bar, as a `Widget`
<!-- impl MenuBar::fn new_from_model -->
Creates a new `MenuBar` and populates it with menu items
and submenus according to `model`.

The created menu items are connected to actions found in the
`ApplicationWindow` to which the menu bar belongs - typically
by means of being contained within the ``GtkApplicationWindows``
widget hierarchy.
## `model`
a `gio::MenuModel`

# Returns

a new `MenuBar`
<!-- trait MenuBarExt::fn get_child_pack_direction -->
Retrieves the current child pack direction of the menubar.
See `MenuBarExt::set_child_pack_direction`.

# Returns

the child pack direction
<!-- trait MenuBarExt::fn get_pack_direction -->
Retrieves the current pack direction of the menubar.
See `MenuBarExt::set_pack_direction`.

# Returns

the pack direction
<!-- trait MenuBarExt::fn set_child_pack_direction -->
Sets how widgets should be packed inside the children of a menubar.
## `child_pack_dir`
a new `PackDirection`
<!-- trait MenuBarExt::fn set_pack_direction -->
Sets how items should be packed inside a menubar.
## `pack_dir`
a new `PackDirection`
<!-- trait MenuBarExt::fn get_property_child_pack_direction -->
The child pack direction of the menubar. It determines how
the widgets contained in child menuitems are arranged.
<!-- trait MenuBarExt::fn set_property_child_pack_direction -->
The child pack direction of the menubar. It determines how
the widgets contained in child menuitems are arranged.
<!-- trait MenuBarExt::fn get_property_pack_direction -->
The pack direction of the menubar. It determines how
menuitems are arranged in the menubar.
<!-- trait MenuBarExt::fn set_property_pack_direction -->
The pack direction of the menubar. It determines how
menuitems are arranged in the menubar.
<!-- struct MenuButton -->
The `MenuButton` widget is used to display a popup when clicked on.
This popup can be provided either as a `Menu`, a `Popover` or an
abstract `gio::MenuModel`.

The `MenuButton` widget can hold any valid child widget. That is, it
can hold almost any other standard `Widget`. The most commonly used
child is `Image`. If no widget is explicitely added to the `MenuButton`,
a `Image` is automatically created, using an arrow image oriented
according to `MenuButton:direction` or the generic “open-menu-symbolic”
icon if the direction is not set.

The positioning of the popup is determined by the `MenuButton:direction`
property of the menu button.

For menus, the `Widget:halign` and `Widget:valign` properties of the
menu are also taken into account. For example, when the direction is
`ArrowType::Down` and the horizontal alignment is `Align::Start`, the
menu will be positioned below the button, with the starting edge
(depending on the text direction) of the menu aligned with the starting
edge of the button. If there is not enough space below the button, the
menu is popped up above the button instead. If the alignment would move
part of the menu offscreen, it is “pushed in”.

## Direction = Down

- halign = start

 ![](down-start.png)

- halign = center

 ![](down-center.png)

- halign = end

 ![](down-end.png)

## Direction = Up

- halign = start

 ![](up-start.png)

- halign = center

 ![](up-center.png)

- halign = end

 ![](up-end.png)

## Direction = Left

- valign = start

 ![](left-start.png)

- valign = center

 ![](left-center.png)

- valign = end

 ![](left-end.png)

## Direction = Right

- valign = start

 ![](right-start.png)

- valign = center

 ![](right-center.png)

- valign = end

 ![](right-end.png)

# CSS nodes

`MenuButton` has a single CSS node with name button. To differentiate
it from a plain `Button`, it gets the .popup style class.

# Implements

[`MenuButtonExt`](trait.MenuButtonExt.html), [`ToggleButtonExt`](trait.ToggleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait MenuButtonExt -->
Trait containing all `MenuButton` methods.

# Implementors

[`MenuButton`](struct.MenuButton.html)
<!-- impl MenuButton::fn new -->
Creates a new `MenuButton` widget with downwards-pointing
arrow as the only child. You can replace the child widget
with another `Widget` should you wish to.

# Returns

The newly created `MenuButton` widget
<!-- trait MenuButtonExt::fn get_align_widget -->
Returns the parent `Widget` to use to line up with menu.

# Returns

a `Widget` value or `None`
<!-- trait MenuButtonExt::fn get_direction -->
Returns the direction the popup will be pointing at when popped up.

# Returns

a `ArrowType` value
<!-- trait MenuButtonExt::fn get_menu_model -->
Returns the `gio::MenuModel` used to generate the popup.

# Returns

a `gio::MenuModel` or `None`
<!-- trait MenuButtonExt::fn get_popover -->
Returns the `Popover` that pops out of the button.
If the button is not using a `Popover`, this function
returns `None`.

# Returns

a `Popover` or `None`
<!-- trait MenuButtonExt::fn get_popup -->
Returns the `Menu` that pops out of the button.
If the button does not use a `Menu`, this function
returns `None`.

# Returns

a `Menu` or `None`
<!-- trait MenuButtonExt::fn get_use_popover -->
Returns whether a `Popover` or a `Menu` will be constructed
from the menu model.

# Returns

`true` if using a `Popover`
<!-- trait MenuButtonExt::fn set_align_widget -->
Sets the `Widget` to use to line the menu with when popped up.
Note that the `align_widget` must contain the `MenuButton` itself.

Setting it to `None` means that the menu will be aligned with the
button itself.

Note that this property is only used with menus currently,
and not for popovers.
## `align_widget`
a `Widget`
<!-- trait MenuButtonExt::fn set_direction -->
Sets the direction in which the popup will be popped up, as
well as changing the arrow’s direction. The child will not
be changed to an arrow if it was customized.

If the does not fit in the available space in the given direction,
GTK+ will its best to keep it inside the screen and fully visible.

If you pass `ArrowType::None` for a `direction`, the popup will behave
as if you passed `ArrowType::Down` (although you won’t see any arrows).
## `direction`
a `ArrowType`
<!-- trait MenuButtonExt::fn set_menu_model -->
Sets the `gio::MenuModel` from which the popup will be constructed,
or `None` to dissociate any existing menu model and disable the button.

Depending on the value of `MenuButton:use-popover`, either a
`Menu` will be created with `Menu::new_from_model`, or a
`Popover` with `Popover::new_from_model`. In either case,
actions will be connected as documented for these functions.

If `MenuButton:popup` or `MenuButton:popover` are already set, those
widgets are dissociated from the `self`, and those properties are set
to `None`.
## `menu_model`
a `gio::MenuModel`, or `None` to unset and disable the
 button
<!-- trait MenuButtonExt::fn set_popover -->
Sets the `Popover` that will be popped up when the `self` is clicked,
or `None` to dissociate any existing popover and disable the button.

If `MenuButton:menu-model` or `MenuButton:popup` are set, those objects
are dissociated from the `self`, and those properties are set to `None`.
## `popover`
a `Popover`, or `None` to unset and disable the button
<!-- trait MenuButtonExt::fn set_popup -->
Sets the `Menu` that will be popped up when the `self` is clicked, or
`None` to dissociate any existing menu and disable the button.

If `MenuButton:menu-model` or `MenuButton:popover` are set, those objects
are dissociated from the `self`, and those properties are set to `None`.
## `menu`
a `Menu`, or `None` to unset and disable the button
<!-- trait MenuButtonExt::fn set_use_popover -->
Sets whether to construct a `Popover` instead of `Menu`
when `MenuButtonExt::set_menu_model` is called. Note that
this property is only consulted when a new menu model is set.
## `use_popover`
`true` to construct a popover from the menu model
<!-- trait MenuButtonExt::fn get_property_align_widget -->
The `Widget` to use to align the menu with.
<!-- trait MenuButtonExt::fn set_property_align_widget -->
The `Widget` to use to align the menu with.
<!-- trait MenuButtonExt::fn get_property_direction -->
The `ArrowType` representing the direction in which the
menu or popover will be popped out.
<!-- trait MenuButtonExt::fn set_property_direction -->
The `ArrowType` representing the direction in which the
menu or popover will be popped out.
<!-- trait MenuButtonExt::fn get_property_menu_model -->
The `gio::MenuModel` from which the popup will be created.
Depending on the `MenuButton:use-popover` property, that may
be a menu or a popover.

See `MenuButtonExt::set_menu_model` for the interaction with the
`MenuButton:popup` property.
<!-- trait MenuButtonExt::fn set_property_menu_model -->
The `gio::MenuModel` from which the popup will be created.
Depending on the `MenuButton:use-popover` property, that may
be a menu or a popover.

See `MenuButtonExt::set_menu_model` for the interaction with the
`MenuButton:popup` property.
<!-- trait MenuButtonExt::fn get_property_popover -->
The `Popover` that will be popped up when the button is clicked.
<!-- trait MenuButtonExt::fn set_property_popover -->
The `Popover` that will be popped up when the button is clicked.
<!-- trait MenuButtonExt::fn get_property_popup -->
The `Menu` that will be popped up when the button is clicked.
<!-- trait MenuButtonExt::fn set_property_popup -->
The `Menu` that will be popped up when the button is clicked.
<!-- trait MenuButtonExt::fn get_property_use_popover -->
Whether to construct a `Popover` from the menu model,
or a `Menu`.
<!-- trait MenuButtonExt::fn set_property_use_popover -->
Whether to construct a `Popover` from the menu model,
or a `Menu`.
<!-- enum MenuDirectionType -->
An enumeration representing directional movements within a menu.
<!-- enum MenuDirectionType::variant Parent -->
To the parent menu shell
<!-- enum MenuDirectionType::variant Child -->
To the submenu, if any, associated with the item
<!-- enum MenuDirectionType::variant Next -->
To the next menu item
<!-- enum MenuDirectionType::variant Prev -->
To the previous menu item
<!-- struct MenuItem -->
The `MenuItem` widget and the derived widgets are the only valid
children for menus. Their function is to correctly handle highlighting,
alignment, events and submenus.

As a `MenuItem` derives from `Bin` it can hold any valid child widget,
although only a few are really useful.

By default, a `MenuItem` sets a `AccelLabel` as its child.
`MenuItem` has direct functions to set the label and its mnemonic.
For more advanced label settings, you can fetch the child widget from the `Bin`.

An example for setting markup and accelerator on a MenuItem:

```C
GtkWidget *menu_item = gtk_menu_item_new_with_label ("Example Menu Item");

GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item));
gtk_label_set_markup (GTK_LABEL (child), "<i>new label</i> with <b>markup</b>");
gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0);
```

# `MenuItem` as `Buildable`

The `MenuItem` implementation of the `Buildable` interface supports
adding a submenu by specifying “submenu” as the “type” attribute of
a `<child>` element.

An example of UI definition fragment with submenus:

```plain
menuitem
├── <child>
╰── [arrow.right]
```

`MenuItem` has a single CSS node with name menuitem. If the menuitem
has a submenu, it gets another CSS node with name arrow, which has
the .left or .right style class.

# Implements

[`GtkMenuItemExt`](trait.GtkMenuItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait GtkMenuItemExt -->
Trait containing all `MenuItem` methods.

# Implementors

[`CheckMenuItem`](struct.CheckMenuItem.html), [`MenuItem`](struct.MenuItem.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html)
<!-- impl MenuItem::fn new -->
Creates a new `MenuItem`.

# Returns

the newly created `MenuItem`
<!-- impl MenuItem::fn new_with_label -->
Creates a new `MenuItem` whose child is a `Label`.
## `label`
the text for the label

# Returns

the newly created `MenuItem`
<!-- impl MenuItem::fn new_with_mnemonic -->
Creates a new `MenuItem` containing a label.

The label will be created using `Label::new_with_mnemonic`,
so underscores in `label` indicate the mnemonic for the menu item.
## `label`
The text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `MenuItem`
<!-- trait GtkMenuItemExt::fn activate -->
Emits the `MenuItem::activate` signal on the given item
<!-- trait GtkMenuItemExt::fn deselect -->
Emits the `MenuItem::deselect` signal on the given item.
<!-- trait GtkMenuItemExt::fn get_accel_path -->
Retrieve the accelerator path that was previously set on `self`.

See `GtkMenuItemExt::set_accel_path` for details.

# Returns

the accelerator path corresponding to
 this menu item’s functionality, or `None` if not set
<!-- trait GtkMenuItemExt::fn get_label -->
Sets `text` on the `self` label

# Returns

The text in the `self` label. This is the internal
 string used by the label, and must not be modified.
<!-- trait GtkMenuItemExt::fn get_reserve_indicator -->
Returns whether the `self` reserves space for
the submenu indicator, regardless if it has a submenu
or not.

# Returns

`true` if `self` always reserves space for the
 submenu indicator
<!-- trait GtkMenuItemExt::fn get_submenu -->
Gets the submenu underneath this menu item, if any.
See `GtkMenuItemExt::set_submenu`.

# Returns

submenu for this menu item, or `None` if none
<!-- trait GtkMenuItemExt::fn get_use_underline -->
Checks if an underline in the text indicates the next character
should be used for the mnemonic accelerator key.

# Returns

`true` if an embedded underline in the label
 indicates the mnemonic accelerator key.
<!-- trait GtkMenuItemExt::fn select -->
Emits the `MenuItem::select` signal on the given item.
<!-- trait GtkMenuItemExt::fn set_accel_path -->
Set the accelerator path on `self`, through which runtime
changes of the menu item’s accelerator caused by the user can be
identified and saved to persistent storage (see `AccelMap::save`
on this). To set up a default accelerator for this menu item, call
`AccelMap::add_entry` with the same `accel_path`. See also
`AccelMap::add_entry` on the specifics of accelerator paths,
and `GtkMenuExt::set_accel_path` for a more convenient variant of
this function.

This function is basically a convenience wrapper that handles
calling `WidgetExt::set_accel_path` with the appropriate accelerator
group for the menu item.

Note that you do need to set an accelerator on the parent menu with
`GtkMenuExt::set_accel_group` for this to work.

Note that `accel_path` string will be stored in a `glib::Quark`.
Therefore, if you pass a static string, you can save some memory
by interning it first with `g_intern_static_string`.
## `accel_path`
accelerator path, corresponding to this menu
 item’s functionality, or `None` to unset the current path.
<!-- trait GtkMenuItemExt::fn set_label -->
Sets `text` on the `self` label
## `label`
the text you want to set
<!-- trait GtkMenuItemExt::fn set_reserve_indicator -->
Sets whether the `self` should reserve space for
the submenu indicator, regardless if it actually has
a submenu or not.

There should be little need for applications to call
this functions.
## `reserve`
the new value
<!-- trait GtkMenuItemExt::fn set_submenu -->
Sets or replaces the menu item’s submenu, or removes it when a `None`
submenu is passed.
## `submenu`
the submenu, or `None`
<!-- trait GtkMenuItemExt::fn set_use_underline -->
If true, an underline in the text indicates the next character
should be used for the mnemonic accelerator key.
## `setting`
`true` if underlines in the text indicate mnemonics
<!-- trait GtkMenuItemExt::fn toggle_size_allocate -->
Emits the `MenuItem::toggle-size-allocate` signal on the given item.
## `allocation`
the allocation to use as signal data.
<!-- trait GtkMenuItemExt::fn toggle_size_request -->
Emits the `MenuItem::toggle-size-request` signal on the given item.
## `requisition`
the requisition to use as signal data.
<!-- trait GtkMenuItemExt::fn connect_activate -->
Emitted when the item is activated.
<!-- trait GtkMenuItemExt::fn connect_activate_item -->
Emitted when the item is activated, but also if the menu item has a
submenu. For normal applications, the relevant signal is
`MenuItem::activate`.
<!-- trait GtkMenuItemExt::fn get_property_accel_path -->
Sets the accelerator path of the menu item, through which runtime
changes of the menu item's accelerator caused by the user can be
identified and saved to persistant storage.
<!-- trait GtkMenuItemExt::fn set_property_accel_path -->
Sets the accelerator path of the menu item, through which runtime
changes of the menu item's accelerator caused by the user can be
identified and saved to persistant storage.
<!-- trait GtkMenuItemExt::fn get_property_label -->
The text for the child label.
<!-- trait GtkMenuItemExt::fn set_property_label -->
The text for the child label.
<!-- trait GtkMenuItemExt::fn get_property_right_justified -->
Sets whether the menu item appears justified
at the right side of a menu bar.
<!-- trait GtkMenuItemExt::fn set_property_right_justified -->
Sets whether the menu item appears justified
at the right side of a menu bar.
<!-- trait GtkMenuItemExt::fn get_property_submenu -->
The submenu attached to the menu item, or `None` if it has none.
<!-- trait GtkMenuItemExt::fn set_property_submenu -->
The submenu attached to the menu item, or `None` if it has none.
<!-- trait GtkMenuItemExt::fn get_property_use_underline -->
`true` if underlines in the text indicate mnemonics.
<!-- trait GtkMenuItemExt::fn set_property_use_underline -->
`true` if underlines in the text indicate mnemonics.
<!-- struct MenuShell -->
A `MenuShell` is the abstract base class used to derive the
`Menu` and `MenuBar` subclasses.

A `MenuShell` is a container of `MenuItem` objects arranged
in a list which can be navigated, selected, and activated by the
user to perform application functions. A `MenuItem` can have a
submenu associated with it, allowing for nested hierarchical menus.

# Terminology

A menu item can be “selected”, this means that it is displayed
in the prelight state, and if it has a submenu, that submenu
will be popped up.

A menu is “active” when it is visible onscreen and the user
is selecting from it. A menubar is not active until the user
clicks on one of its menuitems. When a menu is active,
passing the mouse over a submenu will pop it up.

There is also is a concept of the current menu and a current
menu item. The current menu item is the selected menu item
that is furthest down in the hierarchy. (Every active menu shell
does not necessarily contain a selected menu item, but if
it does, then the parent menu shell must also contain
a selected menu item.) The current menu is the menu that
contains the current menu item. It will always have a GTK
grab and receive all key presses.

# Implements

[`MenuShellExt`](trait.MenuShellExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait MenuShellExt -->
Trait containing all `MenuShell` methods.

# Implementors

[`MenuBar`](struct.MenuBar.html), [`MenuShell`](struct.MenuShell.html), [`Menu`](struct.Menu.html)
<!-- trait MenuShellExt::fn activate_item -->
Activates the menu item within the menu shell.
## `menu_item`
the `MenuItem` to activate
## `force_deactivate`
if `true`, force the deactivation of the
 menu shell after the menu item is activated
<!-- trait MenuShellExt::fn append -->
Adds a new `MenuItem` to the end of the menu shell's
item list.
## `child`
The `MenuItem` to add
<!-- trait MenuShellExt::fn bind_model -->
Establishes a binding between a `MenuShell` and a `gio::MenuModel`.

The contents of `shell` are removed and then refilled with menu items
according to `model`. When `model` changes, `shell` is updated.
Calling this function twice on `shell` with different `model` will
cause the first binding to be replaced with a binding to the new
model. If `model` is `None` then any previous binding is undone and
all children are removed.

`with_separators` determines if toplevel items (eg: sections) have
separators inserted between them. This is typically desired for
menus but doesn’t make sense for menubars.

If `action_namespace` is non-`None` then the effect is as if all
actions mentioned in the `model` have their names prefixed with the
namespace, plus a dot. For example, if the action “quit” is
mentioned and `action_namespace` is “app” then the effective action
name is “app.quit”.

This function uses `Actionable` to define the action name and
target values on the created menu items. If you want to use an
action group other than “app” and “win”, or if you want to use a
`MenuShell` outside of a `ApplicationWindow`, then you will need
to attach your own action group to the widget hierarchy using
`WidgetExt::insert_action_group`. As an example, if you created a
group with a “quit” action and inserted it with the name “mygroup”
then you would use the action name “mygroup.quit” in your
`gio::MenuModel`.

For most cases you are probably better off using
`Menu::new_from_model` or `MenuBar::new_from_model` or just
directly passing the `gio::MenuModel` to `GtkApplicationExt::set_app_menu` or
`GtkApplicationExt::set_menubar`.
## `model`
the `gio::MenuModel` to bind to or `None` to remove
 binding
## `action_namespace`
the namespace for actions in `model`
## `with_separators`
`true` if toplevel items in `shell` should have
 separators between them
<!-- trait MenuShellExt::fn cancel -->
Cancels the selection within the menu shell.
<!-- trait MenuShellExt::fn deactivate -->
Deactivates the menu shell.

Typically this results in the menu shell being erased
from the screen.
<!-- trait MenuShellExt::fn deselect -->
Deselects the currently selected item from the menu shell,
if any.
<!-- trait MenuShellExt::fn get_parent_shell -->
Gets the parent menu shell.

The parent menu shell of a submenu is the `Menu` or `MenuBar`
from which it was opened up.

# Returns

the parent `MenuShell`
<!-- trait MenuShellExt::fn get_selected_item -->
Gets the currently selected item.

# Returns

the currently selected item
<!-- trait MenuShellExt::fn get_take_focus -->
Returns `true` if the menu shell will take the keyboard focus on popup.

# Returns

`true` if the menu shell will take the keyboard focus on popup.
<!-- trait MenuShellExt::fn insert -->
Adds a new `MenuItem` to the menu shell’s item list
at the position indicated by `position`.
## `child`
The `MenuItem` to add
## `position`
The position in the item list where `child`
 is added. Positions are numbered from 0 to n-1
<!-- trait MenuShellExt::fn prepend -->
Adds a new `MenuItem` to the beginning of the menu shell's
item list.
## `child`
The `MenuItem` to add
<!-- trait MenuShellExt::fn select_first -->
Select the first visible or selectable child of the menu shell;
don’t select tearoff items unless the only item is a tearoff
item.
## `search_sensitive`
if `true`, search for the first selectable
 menu item, otherwise select nothing if
 the first item isn’t sensitive. This
 should be `false` if the menu is being
 popped up initially.
<!-- trait MenuShellExt::fn select_item -->
Selects the menu item from the menu shell.
## `menu_item`
The `MenuItem` to select
<!-- trait MenuShellExt::fn set_take_focus -->
If `take_focus` is `true` (the default) the menu shell will take
the keyboard focus so that it will receive all keyboard events
which is needed to enable keyboard navigation in menus.

Setting `take_focus` to `false` is useful only for special applications
like virtual keyboard implementations which should not take keyboard
focus.

The `take_focus` state of a menu or menu bar is automatically
propagated to submenus whenever a submenu is popped up, so you
don’t have to worry about recursively setting it for your entire
menu hierarchy. Only when programmatically picking a submenu and
popping it up manually, the `take_focus` property of the submenu
needs to be set explicitly.

Note that setting it to `false` has side-effects:

If the focus is in some other app, it keeps the focus and keynav in
the menu doesn’t work. Consequently, keynav on the menu will only
work if the focus is on some toplevel owned by the onscreen keyboard.

To avoid confusing the user, menus with `take_focus` set to `false`
should not display mnemonics or accelerators, since it cannot be
guaranteed that they will work.

See also `gdk_keyboard_grab`
## `take_focus`
`true` if the menu shell should take the keyboard
 focus on popup
<!-- trait MenuShellExt::fn connect_activate_current -->
An action signal that activates the current menu item within
the menu shell.
## `force_hide`
if `true`, hide the menu after activating the menu item
<!-- trait MenuShellExt::fn connect_cancel -->
An action signal which cancels the selection within the menu shell.
Causes the `MenuShell::selection-done` signal to be emitted.
<!-- trait MenuShellExt::fn connect_cycle_focus -->
A keybinding signal which moves the focus in the
given `direction`.
## `direction`
the direction to cycle in
<!-- trait MenuShellExt::fn connect_deactivate -->
This signal is emitted when a menu shell is deactivated.
<!-- trait MenuShellExt::fn connect_insert -->
The ::insert signal is emitted when a new `MenuItem` is added to
a `MenuShell`. A separate signal is used instead of
`Container`::add because of the need for an additional position
parameter.

The inverse of this signal is the `Container`::removed signal.
## `child`
the `MenuItem` that is being inserted
## `position`
the position at which the insert occurs
<!-- trait MenuShellExt::fn connect_move_current -->
An keybinding signal which moves the current menu item
in the direction specified by `direction`.
## `direction`
the direction to move
<!-- trait MenuShellExt::fn connect_move_selected -->
The ::move-selected signal is emitted to move the selection to
another item.
## `distance`
+1 to move to the next item, -1 to move to the previous

# Returns

`true` to stop the signal emission, `false` to continue
<!-- trait MenuShellExt::fn connect_selection_done -->
This signal is emitted when a selection has been
completed within a menu shell.
<!-- trait MenuShellExt::fn get_property_take_focus -->
A boolean that determines whether the menu and its submenus grab the
keyboard focus. See `MenuShellExt::set_take_focus` and
`MenuShellExt::get_take_focus`.
<!-- trait MenuShellExt::fn set_property_take_focus -->
A boolean that determines whether the menu and its submenus grab the
keyboard focus. See `MenuShellExt::set_take_focus` and
`MenuShellExt::get_take_focus`.
<!-- struct MenuToolButton -->
A `MenuToolButton` is a `ToolItem` that contains a button and
a small additional button with an arrow. When clicked, the arrow
button pops up a dropdown menu.

Use `MenuToolButton::new` to create a new
`MenuToolButton`.

# `MenuToolButton` as `Buildable`

The `MenuToolButton` implementation of the `Buildable` interface
supports adding a menu by specifying “menu” as the “type” attribute
of a `<child>` element.

An example for a UI definition fragment with menus:

```text
<object class="GtkMenuToolButton">
  <child type="menu">
    <object class="GtkMenu"/>
  </child>
</object>
```

# Implements

[`MenuToolButtonExt`](trait.MenuToolButtonExt.html), [`ToolButtonExt`](trait.ToolButtonExt.html), [`ToolItemExt`](trait.ToolItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait MenuToolButtonExt -->
Trait containing all `MenuToolButton` methods.

# Implementors

[`MenuToolButton`](struct.MenuToolButton.html)
<!-- impl MenuToolButton::fn new -->
Creates a new `MenuToolButton` using `icon_widget` as icon and
`label` as label.
## `icon_widget`
a widget that will be used as icon widget, or `None`
## `label`
a string that will be used as label, or `None`

# Returns

the new `MenuToolButton`
<!-- trait MenuToolButtonExt::fn get_menu -->
Gets the `Menu` associated with `MenuToolButton`.

# Returns

the `Menu` associated
 with `MenuToolButton`
<!-- trait MenuToolButtonExt::fn set_arrow_tooltip_markup -->
Sets the tooltip markup text to be used as tooltip for the arrow button
which pops up the menu. See `ToolItem::set_tooltip_text` for setting
a tooltip on the whole `MenuToolButton`.
## `markup`
markup text to be used as tooltip text for button’s arrow button
<!-- trait MenuToolButtonExt::fn set_arrow_tooltip_text -->
Sets the tooltip text to be used as tooltip for the arrow button which
pops up the menu. See `ToolItem::set_tooltip_text` for setting a tooltip
on the whole `MenuToolButton`.
## `text`
text to be used as tooltip text for button’s arrow button
<!-- trait MenuToolButtonExt::fn set_menu -->
Sets the `Menu` that is popped up when the user clicks on the arrow.
If `menu` is NULL, the arrow button becomes insensitive.
## `menu`
the `Menu` associated with `MenuToolButton`
<!-- trait MenuToolButtonExt::fn connect_show_menu -->
The ::show-menu signal is emitted before the menu is shown.

It can be used to populate the menu on demand, using
`MenuToolButtonExt::set_menu`.

Note that even if you populate the menu dynamically in this way,
you must set an empty menu on the `MenuToolButton` beforehand,
since the arrow is made insensitive if the menu is not set.
<!-- struct MessageDialog -->
`MessageDialog` presents a dialog with some message text. It’s simply a
convenience widget; you could construct the equivalent of `MessageDialog`
from `Dialog` without too much effort, but `MessageDialog` saves typing.

One difference from `Dialog` is that `MessageDialog` sets the
`Window:skip-taskbar-hint` property to `true`, so that the dialog is hidden
from the taskbar by default.

The easiest way to do a modal message dialog is to use `DialogExt::run`, though
you can also pass in the `DialogFlags::Modal` flag, `DialogExt::run` automatically
makes the dialog modal and waits for the user to respond to it. `DialogExt::run`
returns when any dialog button is clicked.

An example for using a modal dialog:

```C
 GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_message_dialog_new (parent_window,
                                  flags,
                                  GTK_MESSAGE_ERROR,
                                  GTK_BUTTONS_CLOSE,
                                  "Error reading “%s”: %s",
                                  filename,
                                  g_strerror (errno));
 gtk_dialog_run (GTK_DIALOG (dialog));
 gtk_widget_destroy (dialog);
```

You might do a non-modal `MessageDialog` as follows:

An example for a non-modal dialog:

```C
 GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_message_dialog_new (parent_window,
                                  flags,
                                  GTK_MESSAGE_ERROR,
                                  GTK_BUTTONS_CLOSE,
                                  "Error reading “%s”: %s",
                                  filename,
                                  g_strerror (errno));

 // Destroy the dialog when the user responds to it
 // (e.g. clicks a button)

 g_signal_connect_swapped (dialog, "response",
                           G_CALLBACK (gtk_widget_destroy),
                           dialog);
```

# `MessageDialog` as `Buildable`

The `MessageDialog` implementation of the `Buildable` interface exposes
the message area as an internal child with the name “message_area”.

# Implements

[`MessageDialogExt`](trait.MessageDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait MessageDialogExt -->
Trait containing all `MessageDialog` methods.

# Implementors

[`MessageDialog`](struct.MessageDialog.html)
<!-- impl MessageDialog::fn new -->
Creates a new message dialog, which is a simple dialog with some text
the user may want to see. When the user clicks a button a “response”
signal is emitted with response IDs from `ResponseType`. See
`Dialog` for more details.
## `parent`
transient parent, or `None` for none
## `flags`
flags
## `type_`
type of message
## `buttons`
set of buttons to use
## `message_format`
`printf`-style format string, or `None`

# Returns

a new `MessageDialog`
<!-- impl MessageDialog::fn new_with_markup -->
Creates a new message dialog, which is a simple dialog with some text that
is marked up with the [Pango text markup language][PangoMarkupFormat].
When the user clicks a button a “response” signal is emitted with
response IDs from `ResponseType`. See `Dialog` for more details.

Special XML characters in the `printf` arguments passed to this
function will automatically be escaped as necessary.
(See `g_markup_printf_escaped` for how this is implemented.)
Usually this is what you want, but if you have an existing
Pango markup string that you want to use literally as the
label, then you need to use `MessageDialogExt::set_markup`
instead, since you can’t pass the markup string either
as the format (it might contain “%” characters) or as a string
argument.

```C
 GtkWidget *dialog;
 GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_message_dialog_new (parent_window,
                                  flags,
                                  GTK_MESSAGE_ERROR,
                                  GTK_BUTTONS_CLOSE,
                                  NULL);
 gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog),
                                markup);
```
## `parent`
transient parent, or `None` for none
## `flags`
flags
## `type_`
type of message
## `buttons`
set of buttons to use
## `message_format`
`printf`-style format string, or `None`

# Returns

a new `MessageDialog`
<!-- trait MessageDialogExt::fn format_secondary_markup -->
Sets the secondary text of the message dialog to be `message_format` (with
`printf`-style), which is marked up with the
[Pango text markup language][PangoMarkupFormat].

Due to an oversight, this function does not escape special XML characters
like `MessageDialog::new_with_markup` does. Thus, if the arguments
may contain special XML characters, you should use `g_markup_printf_escaped`
to escape it.


```C
gchar *msg;

msg = g_markup_printf_escaped (message_format, ...);
gtk_message_dialog_format_secondary_markup (message_dialog,
                                            "%s", msg);
g_free (msg);
```
## `message_format`
`printf`-style markup string (see
 [Pango markup format][PangoMarkupFormat]), or `None`
<!-- trait MessageDialogExt::fn format_secondary_text -->
Sets the secondary text of the message dialog to be `message_format`
(with `printf`-style).
## `message_format`
`printf`-style format string, or `None`
<!-- trait MessageDialogExt::fn get_message_area -->
Returns the message area of the dialog. This is the box where the
dialog’s primary and secondary labels are packed. You can add your
own extra content to that box and it will appear below those labels.
See `DialogExt::get_content_area` for the corresponding
function in the parent `Dialog`.

# Returns

A `Box` corresponding to the
 “message area” in the `self`.
<!-- trait MessageDialogExt::fn set_markup -->
Sets the text of the message dialog to be `str`, which is marked
up with the [Pango text markup language][PangoMarkupFormat].
## `str`
markup string (see [Pango markup format][PangoMarkupFormat])
<!-- trait MessageDialogExt::fn get_property_message_area -->
The `Box` that corresponds to the message area of this dialog. See
`MessageDialogExt::get_message_area` for a detailed description of this
area.
<!-- trait MessageDialogExt::fn get_property_message_type -->
The type of the message.
<!-- trait MessageDialogExt::fn set_property_message_type -->
The type of the message.
<!-- trait MessageDialogExt::fn get_property_secondary_text -->
The secondary text of the message dialog.
<!-- trait MessageDialogExt::fn set_property_secondary_text -->
The secondary text of the message dialog.
<!-- trait MessageDialogExt::fn get_property_secondary_use_markup -->
`true` if the secondary text of the dialog includes Pango markup.
See `pango_parse_markup`.
<!-- trait MessageDialogExt::fn set_property_secondary_use_markup -->
`true` if the secondary text of the dialog includes Pango markup.
See `pango_parse_markup`.
<!-- trait MessageDialogExt::fn get_property_text -->
The primary text of the message dialog. If the dialog has
a secondary text, this will appear as the title.
<!-- trait MessageDialogExt::fn set_property_text -->
The primary text of the message dialog. If the dialog has
a secondary text, this will appear as the title.
<!-- trait MessageDialogExt::fn get_property_use_markup -->
`true` if the primary text of the dialog includes Pango markup.
See `pango_parse_markup`.
<!-- trait MessageDialogExt::fn set_property_use_markup -->
`true` if the primary text of the dialog includes Pango markup.
See `pango_parse_markup`.
<!-- enum MessageType -->
The type of message being displayed in the dialog.
<!-- enum MessageType::variant Info -->
Informational message
<!-- enum MessageType::variant Warning -->
Non-fatal warning message
<!-- enum MessageType::variant Question -->
Question requiring a choice
<!-- enum MessageType::variant Error -->
Fatal error message
<!-- enum MessageType::variant Other -->
None of the above
<!-- struct Misc -->
The `Misc` widget is an abstract widget which is not useful itself, but
is used to derive subclasses which have alignment and padding attributes.

The horizontal and vertical padding attributes allows extra space to be
added around the widget.

The horizontal and vertical alignment attributes enable the widget to be
positioned within its allocated area. Note that if the widget is added to
a container in such a way that it expands automatically to fill its
allocated area, the alignment settings will not alter the widget's position.

Note that the desired effect can in most cases be achieved by using the
`Widget:halign`, `Widget:valign` and `Widget:margin` properties
on the child widget, so `Misc` should not be used in new code. To reflect
this fact, all `Misc` API has been deprecated.

# Implements

[`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- struct ModelButton -->
`ModelButton` is a button class that can use a `gio::Action` as its model.
In contrast to `ToggleButton` or `RadioButton`, which can also
be backed by a `gio::Action` via the `Actionable:action-name` property,
`ModelButton` will adapt its appearance according to the kind of
action it is backed by, and appear either as a plain, check or
radio button.

Model buttons are used when popovers from a menu model with
`Popover::new_from_model`; they can also be used manually in
a `PopoverMenu`.

When the action is specified via the `Actionable:action-name`
and `Actionable:action-target` properties, the role of the button
(i.e. whether it is a plain, check or radio button) is determined by
the type of the action and doesn't have to be explicitly specified
with the `ModelButton:role` property.

The content of the button is specified by the `ModelButton:text`
and `ModelButton:icon` properties.

The appearance of model buttons can be influenced with the
`ModelButton:centered` and `ModelButton:iconic` properties.

Model buttons have built-in support for submenus in `PopoverMenu`.
To make a `ModelButton` that opens a submenu when activated, set
the `ModelButton:menu-name` property. To make a button that goes
back to the parent menu, you should set the `ModelButton:inverted`
property to place the submenu indicator at the opposite side.

# Example


```plain
modelbutton
├── <child>
╰── check
```


```plain
modelbutton
├── <child>
╰── radio
```


```plain
modelbutton
├── <child>
╰── arrow
```

`ModelButton` has a main CSS node with name modelbutton, and a subnode,
which will have the name check, radio or arrow, depending on the role
of the button and whether it has a menu name set.

The subnode is positioned before or after the content nodes and gets the
.left or .right style class, depending on where it is located.


```plain
button.model
├── <child>
╰── check
```

Iconic model buttons (see `ModelButton:iconic`) change the name of
their main node to button and add a .model style class to it. The indicator
subnode is invisible in this case.

Feature: `v3_16`

# Implements

[`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl ModelButton::fn new -->
Creates a new `ModelButton`.

Feature: `v3_16`


# Returns

the newly created `ModelButton` widget
<!-- impl ModelButton::fn get_property_active -->
The state of the button. This is reflecting the state of the associated
`gio::Action`.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_active -->
The state of the button. This is reflecting the state of the associated
`gio::Action`.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_centered -->
Whether to render the button contents centered instead of left-aligned.
This property should be set for title-like items.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_centered -->
Whether to render the button contents centered instead of left-aligned.
This property should be set for title-like items.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_icon -->
A `gio::Icon` that will be used if iconic appearance for the button is
desired.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_icon -->
A `gio::Icon` that will be used if iconic appearance for the button is
desired.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_iconic -->
If this property is set, the button will show an icon if one is set.
If no icon is set, the text will be used. This is typically used for
horizontal sections of linked buttons.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_iconic -->
If this property is set, the button will show an icon if one is set.
If no icon is set, the text will be used. This is typically used for
horizontal sections of linked buttons.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_inverted -->
Whether to show the submenu indicator at the opposite side than normal.
This property should be set for model buttons that 'go back' to a parent
menu.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_inverted -->
Whether to show the submenu indicator at the opposite side than normal.
This property should be set for model buttons that 'go back' to a parent
menu.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_menu_name -->
The name of a submenu to open when the button is activated.
If this is set, the button should not have an action associated with it.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_menu_name -->
The name of a submenu to open when the button is activated.
If this is set, the button should not have an action associated with it.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_role -->
Specifies whether the button is a plain, check or radio button.
When `Actionable:action-name` is set, the role will be determined
from the action and does not have to be set explicitly.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_role -->
Specifies whether the button is a plain, check or radio button.
When `Actionable:action-name` is set, the role will be determined
from the action and does not have to be set explicitly.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_text -->
The label for the button.

Feature: `v3_16`

<!-- impl ModelButton::fn set_property_text -->
The label for the button.

Feature: `v3_16`

<!-- impl ModelButton::fn get_property_use_markup -->
If `true`, XML tags in the text of the button are interpreted as by
`pango_parse_markup` to format the enclosed spans of text. If `false`, the
text will be displayed verbatim.

Feature: `v3_24`

<!-- impl ModelButton::fn set_property_use_markup -->
If `true`, XML tags in the text of the button are interpreted as by
`pango_parse_markup` to format the enclosed spans of text. If `false`, the
text will be displayed verbatim.

Feature: `v3_24`

<!-- struct MountOperation -->
This should not be accessed directly. Use the accessor functions below.

# Implements

[`MountOperationExt`](trait.MountOperationExt.html), [`gio::MountOperationExt`](../gio/trait.MountOperationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait MountOperationExt -->
Trait containing all `MountOperation` methods.

# Implementors

[`MountOperation`](struct.MountOperation.html)
<!-- impl MountOperation::fn new -->
Creates a new `MountOperation`
## `parent`
transient parent of the window, or `None`

# Returns

a new `MountOperation`
<!-- trait MountOperationExt::fn get_parent -->
Gets the transient parent used by the `MountOperation`

# Returns

the transient parent for windows shown by `self`
<!-- trait MountOperationExt::fn get_screen -->
Gets the screen on which windows of the `MountOperation`
will be shown.

# Returns

the screen on which windows of `self` are shown
<!-- trait MountOperationExt::fn is_showing -->
Returns whether the `MountOperation` is currently displaying
a window.

# Returns

`true` if `self` is currently displaying a window
<!-- trait MountOperationExt::fn set_parent -->
Sets the transient parent for windows shown by the
`MountOperation`.
## `parent`
transient parent of the window, or `None`
<!-- trait MountOperationExt::fn set_screen -->
Sets the screen to show windows of the `MountOperation` on.
## `screen`
a `gdk::Screen`
<!-- enum MovementStep -->
<!-- enum MovementStep::variant LogicalPositions -->
Move forward or back by graphemes
<!-- enum MovementStep::variant VisualPositions -->
Move left or right by graphemes
<!-- enum MovementStep::variant Words -->
Move forward or back by words
<!-- enum MovementStep::variant DisplayLines -->
Move up or down lines (wrapped lines)
<!-- enum MovementStep::variant DisplayLineEnds -->
Move to either end of a line
<!-- enum MovementStep::variant Paragraphs -->
Move up or down paragraphs (newline-ended lines)
<!-- enum MovementStep::variant ParagraphEnds -->
Move to either end of a paragraph
<!-- enum MovementStep::variant Pages -->
Move by pages
<!-- enum MovementStep::variant BufferEnds -->
Move to ends of the buffer
<!-- enum MovementStep::variant HorizontalPages -->
Move horizontally by pages
<!-- struct NativeDialog -->
Native dialogs are platform dialogs that don't use `Dialog` or
`Window`. They are used in order to integrate better with a
platform, by looking the same as other native applications and
supporting platform specific features.

The `Dialog` functions cannot be used on such objects, but we
need a similar API in order to drive them. The `NativeDialog`
object is an API that allows you to do this. It allows you to set
various common properties on the dialog, as well as show and hide
it and get a `NativeDialog::response` signal when the user finished
with the dialog.

There is also a `NativeDialogExt::run` helper that makes it easy
to run any native dialog in a modal way with a recursive mainloop,
similar to `DialogExt::run`.

Feature: `v3_20`

# Implements

[`NativeDialogExt`](trait.NativeDialogExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait NativeDialogExt -->
Trait containing all `NativeDialog` methods.

Feature: `v3_20`

# Implementors

[`FileChooserNative`](struct.FileChooserNative.html), [`NativeDialog`](struct.NativeDialog.html)
<!-- trait NativeDialogExt::fn destroy -->
Destroys a dialog.

When a dialog is destroyed, it will break any references it holds
to other objects. If it is visible it will be hidden and any underlying
window system resources will be destroyed.

Note that this does not release any reference to the object (as opposed to
destroying a `Window`) because there is no reference from the windowing
system to the `NativeDialog`.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn get_modal -->
Returns whether the dialog is modal. See `NativeDialogExt::set_modal`.

Feature: `v3_20`


# Returns

`true` if the dialog is set to be modal
<!-- trait NativeDialogExt::fn get_title -->
Gets the title of the `NativeDialog`.

Feature: `v3_20`


# Returns

the title of the dialog, or `None` if none has
 been set explicitly. The returned string is owned by the widget
 and must not be modified or freed.
<!-- trait NativeDialogExt::fn get_transient_for -->
Fetches the transient parent for this window. See
`NativeDialogExt::set_transient_for`.

Feature: `v3_20`


# Returns

the transient parent for this window,
or `None` if no transient parent has been set.
<!-- trait NativeDialogExt::fn get_visible -->
Determines whether the dialog is visible.

Feature: `v3_20`


# Returns

`true` if the dialog is visible
<!-- trait NativeDialogExt::fn hide -->
Hides the dialog if it is visilbe, aborting any interaction. Once this
is called the `NativeDialog::response` signal will not be emitted
until after the next call to `NativeDialogExt::show`.

If the dialog is not visible this does nothing.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn run -->
Blocks in a recursive main loop until `self` emits the
`NativeDialog::response` signal. It then returns the response ID
from the ::response signal emission.

Before entering the recursive main loop, `NativeDialogExt::run`
calls `NativeDialogExt::show` on the dialog for you.

After `NativeDialogExt::run` returns, then dialog will be hidden.

Typical usage of this function might be:

```C
  gint result = gtk_native_dialog_run (GTK_NATIVE_DIALOG (dialog));
  switch (result)
    {
      case GTK_RESPONSE_ACCEPT:
         do_application_specific_something ();
         break;
      default:
         do_nothing_since_dialog_was_cancelled ();
         break;
    }
  g_object_unref (dialog);
```

Note that even though the recursive main loop gives the effect of a
modal dialog (it prevents the user from interacting with other
windows in the same window group while the dialog is run), callbacks
such as timeouts, IO channel watches, DND drops, etc, will
be triggered during a `gtk_nautilus_dialog_run` call.

Feature: `v3_20`


# Returns

response ID
<!-- trait NativeDialogExt::fn set_modal -->
Sets a dialog modal or non-modal. Modal dialogs prevent interaction
with other windows in the same application. To keep modal dialogs
on top of main application windows, use
`NativeDialogExt::set_transient_for` to make the dialog transient for the
parent; most [window managers][gtk-X11-arch]
will then disallow lowering the dialog below the parent.

Feature: `v3_20`

## `modal`
whether the window is modal
<!-- trait NativeDialogExt::fn set_title -->
Sets the title of the `NativeDialog`.

Feature: `v3_20`

## `title`
title of the dialog
<!-- trait NativeDialogExt::fn set_transient_for -->
Dialog windows should be set transient for the main application
window they were spawned from. This allows
[window managers][gtk-X11-arch] to e.g. keep the
dialog on top of the main window, or center the dialog over the
main window.

Passing `None` for `parent` unsets the current transient window.

Feature: `v3_20`

## `parent`
parent window, or `None`
<!-- trait NativeDialogExt::fn show -->
Shows the dialog on the display, allowing the user to interact with
it. When the user accepts the state of the dialog the dialog will
be automatically hidden and the `NativeDialog::response` signal
will be emitted.

Multiple calls while the dialog is visible will be ignored.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn connect_response -->
Emitted when the user responds to the dialog.

When this is called the dialog has been hidden.

If you call `NativeDialogExt::hide` before the user responds to
the dialog this signal will not be emitted.

Feature: `v3_20`

## `response_id`
the response ID
<!-- trait NativeDialogExt::fn get_property_modal -->
Whether the window should be modal with respect to its transient parent.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn set_property_modal -->
Whether the window should be modal with respect to its transient parent.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn get_property_title -->
The title of the dialog window

Feature: `v3_20`

<!-- trait NativeDialogExt::fn set_property_title -->
The title of the dialog window

Feature: `v3_20`

<!-- trait NativeDialogExt::fn get_property_transient_for -->
The transient parent of the dialog, or `None` for none.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn set_property_transient_for -->
The transient parent of the dialog, or `None` for none.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn get_property_visible -->
Whether the window is currenlty visible.

Feature: `v3_20`

<!-- trait NativeDialogExt::fn set_property_visible -->
Whether the window is currenlty visible.

Feature: `v3_20`

<!-- struct Notebook -->
The `Notebook` widget is a `Container` whose children are pages that
can be switched between using tab labels along one edge.

There are many configuration options for `Notebook`. Among other
things, you can choose on which edge the tabs appear
(see `NotebookExt::set_tab_pos`), whether, if there are too many
tabs to fit the notebook should be made bigger or scrolling
arrows added (see `NotebookExt::set_scrollable`), and whether there
will be a popup menu allowing the users to switch pages.
(see `NotebookExt::popup_enable`, `NotebookExt::popup_disable`)

# `Notebook` as `Buildable`

The `Notebook` implementation of the `Buildable` interface
supports placing children into tabs by specifying “tab” as the
“type” attribute of a `<child>` element. Note that the content
of the tab must be created before the tab can be filled.
A tab child can be specified without specifying a `<child>`
type attribute.

To add a child widget in the notebooks action area, specify
"action-start" or “action-end” as the “type” attribute of the
`<child>` element.

An example of a UI definition fragment with `Notebook`:

```plain
notebook
├── header.top
│   ├── [<action widget>]
│   ├── tabs
│   │   ├── [arrow]
│   │   ├── tab
│   │   │   ╰── <tab label>
┊   ┊   ┊
│   │   ├── tab[.reorderable-page]
│   │   │   ╰── <tab label>
│   │   ╰── [arrow]
│   ╰── [<action widget>]
│
╰── stack
    ├── <child>
    ┊
    ╰── <child>
```

`Notebook` has a main CSS node with name notebook, a subnode
with name header and below that a subnode with name tabs which
contains one subnode per tab with name tab.

If action widgets are present, their CSS nodes are placed next
to the tabs node. If the notebook is scrollable, CSS nodes with
name arrow are placed as first and last child of the tabs node.

The main node gets the .frame style class when the notebook
has a border (see `NotebookExt::set_show_border`).

The header node gets one of the style class .top, .bottom,
.left or .right, depending on where the tabs are placed. For
reorderable pages, the tab node gets the .reorderable-page class.

A tab node gets the .dnd style class while it is moved with drag-and-drop.

The nodes are always arranged from left-to-right, regarldess of text direction.

# Implements

[`NotebookExt`](trait.NotebookExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`NotebookExtManual`](prelude/trait.NotebookExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait NotebookExt -->
Trait containing all `Notebook` methods.

# Implementors

[`Notebook`](struct.Notebook.html)
<!-- impl Notebook::fn new -->
Creates a new `Notebook` widget with no pages.

# Returns

the newly created `Notebook`
<!-- trait NotebookExtManual::fn append_page -->
Appends a page to `self`.
## `child`
the `Widget` to use as the contents of the page
## `tab_label`
the `Widget` to be used as the label
 for the page, or `None` to use the default label, “page N”

# Returns

the index (starting from 0) of the appended
 page in the notebook, or -1 if function fails
<!-- trait NotebookExtManual::fn append_page_menu -->
Appends a page to `self`, specifying the widget to use as the
label in the popup menu.
## `child`
the `Widget` to use as the contents of the page
## `tab_label`
the `Widget` to be used as the label
 for the page, or `None` to use the default label, “page N”
## `menu_label`
the widget to use as a label for the
 page-switch menu, if that is enabled. If `None`, and `tab_label`
 is a `Label` or `None`, then the menu label will be a newly
 created label with the same text as `tab_label`; if `tab_label`
 is not a `Label`, `menu_label` must be specified if the
 page-switch menu is to be used.

# Returns

the index (starting from 0) of the appended
 page in the notebook, or -1 if function fails
<!-- trait NotebookExt::fn detach_tab -->
Removes the child from the notebook.

This function is very similar to `ContainerExt::remove`,
but additionally informs the notebook that the removal
is happening as part of a tab DND operation, which should
not be cancelled.

Feature: `v3_16`

## `child`
a child
<!-- trait NotebookExt::fn get_action_widget -->
Gets one of the action widgets. See `NotebookExt::set_action_widget`.
## `pack_type`
pack type of the action widget to receive

# Returns

The action widget with the given
`pack_type` or `None` when this action widget has not been set
<!-- trait NotebookExtManual::fn get_current_page -->
Returns the page number of the current page.

# Returns

the index (starting from 0) of the current
 page in the notebook. If the notebook has no pages,
 then -1 will be returned.
<!-- trait NotebookExt::fn get_group_name -->
Gets the current group name for `self`.

# Returns

the group name, or `None` if none is set
<!-- trait NotebookExt::fn get_menu_label -->
Retrieves the menu label widget of the page containing `child`.
## `child`
a widget contained in a page of `self`

# Returns

the menu label, or `None` if the
notebook page does not have a menu label other than the default (the tab
label).
<!-- trait NotebookExt::fn get_menu_label_text -->
Retrieves the text of the menu label for the page containing
`child`.
## `child`
the child widget of a page of the notebook.

# Returns

the text of the tab label, or `None` if the widget does
not have a menu label other than the default menu label, or the menu label
widget is not a `Label`. The string is owned by the widget and must not be
freed.
<!-- trait NotebookExtManual::fn get_n_pages -->
Gets the number of pages in a notebook.

# Returns

the number of pages in the notebook
<!-- trait NotebookExtManual::fn get_nth_page -->
Returns the child widget contained in page number `page_num`.
## `page_num`
the index of a page in the notebook, or -1
 to get the last page

# Returns

the child widget, or `None` if `page_num`
is out of bounds
<!-- trait NotebookExt::fn get_scrollable -->
Returns whether the tab label area has arrows for scrolling.
See `NotebookExt::set_scrollable`.

# Returns

`true` if arrows for scrolling are present
<!-- trait NotebookExt::fn get_show_border -->
Returns whether a bevel will be drawn around the notebook pages.
See `NotebookExt::set_show_border`.

# Returns

`true` if the bevel is drawn
<!-- trait NotebookExt::fn get_show_tabs -->
Returns whether the tabs of the notebook are shown.
See `NotebookExt::set_show_tabs`.

# Returns

`true` if the tabs are shown
<!-- trait NotebookExt::fn get_tab_detachable -->
Returns whether the tab contents can be detached from `self`.
## `child`
a child `Widget`

# Returns

`true` if the tab is detachable.
<!-- trait NotebookExt::fn get_tab_label -->
Returns the tab label widget for the page `child`.
`None` is returned if `child` is not in `self` or
if no tab label has specifically been set for `child`.
## `child`
the page

# Returns

the tab label
<!-- trait NotebookExt::fn get_tab_label_text -->
Retrieves the text of the tab label for the page containing
`child`.
## `child`
a widget contained in a page of `self`

# Returns

the text of the tab label, or `None` if the tab label
widget is not a `Label`. The string is owned by the widget and must not be
freed.
<!-- trait NotebookExt::fn get_tab_pos -->
Gets the edge at which the tabs for switching pages in the
notebook are drawn.

# Returns

the edge at which the tabs are drawn
<!-- trait NotebookExt::fn get_tab_reorderable -->
Gets whether the tab can be reordered via drag and drop or not.
## `child`
a child `Widget`

# Returns

`true` if the tab is reorderable.
<!-- trait NotebookExtManual::fn insert_page -->
Insert a page into `self` at the given position.
## `child`
the `Widget` to use as the contents of the page
## `tab_label`
the `Widget` to be used as the label
 for the page, or `None` to use the default label, “page N”
## `position`
the index (starting at 0) at which to insert the page,
 or -1 to append the page after all other pages

# Returns

the index (starting from 0) of the inserted
 page in the notebook, or -1 if function fails
<!-- trait NotebookExtManual::fn insert_page_menu -->
Insert a page into `self` at the given position, specifying
the widget to use as the label in the popup menu.
## `child`
the `Widget` to use as the contents of the page
## `tab_label`
the `Widget` to be used as the label
 for the page, or `None` to use the default label, “page N”
## `menu_label`
the widget to use as a label for the
 page-switch menu, if that is enabled. If `None`, and `tab_label`
 is a `Label` or `None`, then the menu label will be a newly
 created label with the same text as `tab_label`; if `tab_label`
 is not a `Label`, `menu_label` must be specified if the
 page-switch menu is to be used.
## `position`
the index (starting at 0) at which to insert the page,
 or -1 to append the page after all other pages.

# Returns

the index (starting from 0) of the inserted
 page in the notebook
<!-- trait NotebookExt::fn next_page -->
Switches to the next page. Nothing happens if the current page is
the last page.
<!-- trait NotebookExtManual::fn page_num -->
Finds the index of the page which contains the given child
widget.
## `child`
a `Widget`

# Returns

the index of the page containing `child`, or
 -1 if `child` is not in the notebook
<!-- trait NotebookExt::fn popup_disable -->
Disables the popup menu.
<!-- trait NotebookExt::fn popup_enable -->
Enables the popup menu: if the user clicks with the right
mouse button on the tab labels, a menu with all the pages
will be popped up.
<!-- trait NotebookExtManual::fn prepend_page -->
Prepends a page to `self`.
## `child`
the `Widget` to use as the contents of the page
## `tab_label`
the `Widget` to be used as the label
 for the page, or `None` to use the default label, “page N”

# Returns

the index (starting from 0) of the prepended
 page in the notebook, or -1 if function fails
<!-- trait NotebookExtManual::fn prepend_page_menu -->
Prepends a page to `self`, specifying the widget to use as the
label in the popup menu.
## `child`
the `Widget` to use as the contents of the page
## `tab_label`
the `Widget` to be used as the label
 for the page, or `None` to use the default label, “page N”
## `menu_label`
the widget to use as a label for the
 page-switch menu, if that is enabled. If `None`, and `tab_label`
 is a `Label` or `None`, then the menu label will be a newly
 created label with the same text as `tab_label`; if `tab_label`
 is not a `Label`, `menu_label` must be specified if the
 page-switch menu is to be used.

# Returns

the index (starting from 0) of the prepended
 page in the notebook, or -1 if function fails
<!-- trait NotebookExt::fn prev_page -->
Switches to the previous page. Nothing happens if the current page
is the first page.
<!-- trait NotebookExtManual::fn remove_page -->
Removes a page from the notebook given its index
in the notebook.
## `page_num`
the index of a notebook page, starting
 from 0. If -1, the last page will be removed.
<!-- trait NotebookExtManual::fn reorder_child -->
Reorders the page containing `child`, so that it appears in position
`position`. If `position` is greater than or equal to the number of
children in the list or negative, `child` will be moved to the end
of the list.
## `child`
the child to move
## `position`
the new position, or -1 to move to the end
<!-- trait NotebookExt::fn set_action_widget -->
Sets `widget` as one of the action widgets. Depending on the pack type
the widget will be placed before or after the tabs. You can use
a `Box` if you need to pack more than one widget on the same side.

Note that action widgets are “internal” children of the notebook and thus
not included in the list returned from `ContainerExt::foreach`.
## `widget`
a `Widget`
## `pack_type`
pack type of the action widget
<!-- trait NotebookExtManual::fn set_current_page -->
Switches to the page number `page_num`.

Note that due to historical reasons, `Notebook` refuses
to switch to a page unless the child widget is visible.
Therefore, it is recommended to show child widgets before
adding them to a notebook.
## `page_num`
index of the page to switch to, starting from 0.
 If negative, the last page will be used. If greater
 than the number of pages in the notebook, nothing
 will be done.
<!-- trait NotebookExt::fn set_group_name -->
Sets a group name for `self`.

Notebooks with the same name will be able to exchange tabs
via drag and drop. A notebook with a `None` group name will
not be able to exchange tabs with any other notebook.
## `group_name`
the name of the notebook group,
 or `None` to unset it
<!-- trait NotebookExt::fn set_menu_label -->
Changes the menu label for the page containing `child`.
## `child`
the child widget
## `menu_label`
the menu label, or `None` for default
<!-- trait NotebookExt::fn set_menu_label_text -->
Creates a new label and sets it as the menu label of `child`.
## `child`
the child widget
## `menu_text`
the label text
<!-- trait NotebookExt::fn set_scrollable -->
Sets whether the tab label area will have arrows for
scrolling if there are too many tabs to fit in the area.
## `scrollable`
`true` if scroll arrows should be added
<!-- trait NotebookExt::fn set_show_border -->
Sets whether a bevel will be drawn around the notebook pages.
This only has a visual effect when the tabs are not shown.
See `NotebookExt::set_show_tabs`.
## `show_border`
`true` if a bevel should be drawn around the notebook
<!-- trait NotebookExt::fn set_show_tabs -->
Sets whether to show the tabs for the notebook or not.
## `show_tabs`
`true` if the tabs should be shown
<!-- trait NotebookExt::fn set_tab_detachable -->
Sets whether the tab can be detached from `self` to another
notebook or widget.

Note that 2 notebooks must share a common group identificator
(see `NotebookExt::set_group_name`) to allow automatic tabs
interchange between them.

If you want a widget to interact with a notebook through DnD
(i.e.: accept dragged tabs from it) it must be set as a drop
destination and accept the target “GTK_NOTEBOOK_TAB”. The notebook
will fill the selection with a `Widget`** pointing to the child
widget that corresponds to the dropped tab.

Note that you should use `NotebookExt::detach_tab` instead
of `ContainerExt::remove` if you want to remove the tab from
the source notebook as part of accepting a drop. Otherwise,
the source notebook will think that the dragged tab was
removed from underneath the ongoing drag operation, and
will initiate a drag cancel animation.


```C
 static void
 on_drag_data_received (GtkWidget        *widget,
                        GdkDragContext   *context,
                        gint              x,
                        gint              y,
                        GtkSelectionData *data,
                        guint             info,
                        guint             time,
                        gpointer          user_data)
 {
   GtkWidget *notebook;
   GtkWidget **child;

   notebook = gtk_drag_get_source_widget (context);
   child = (void*) gtk_selection_data_get_data (data);

   // process_widget (*child);

   gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
 }
```

If you want a notebook to accept drags from other widgets,
you will have to set your own DnD code to do it.
## `child`
a child `Widget`
## `detachable`
whether the tab is detachable or not
<!-- trait NotebookExt::fn set_tab_label -->
Changes the tab label for `child`.
If `None` is specified for `tab_label`, then the page will
have the label “page N”.
## `child`
the page
## `tab_label`
the tab label widget to use, or `None`
 for default tab label
<!-- trait NotebookExt::fn set_tab_label_text -->
Creates a new label and sets it as the tab label for the page
containing `child`.
## `child`
the page
## `tab_text`
the label text
<!-- trait NotebookExt::fn set_tab_pos -->
Sets the edge at which the tabs for switching pages in the
notebook are drawn.
## `pos`
the edge to draw the tabs at
<!-- trait NotebookExt::fn set_tab_reorderable -->
Sets whether the notebook tab can be reordered
via drag and drop or not.
## `child`
a child `Widget`
## `reorderable`
whether the tab is reorderable or not
<!-- trait NotebookExt::fn connect_create_window -->
The ::create-window signal is emitted when a detachable
tab is dropped on the root window.

A handler for this signal can create a window containing
a notebook where the tab will be attached. It is also
responsible for moving/resizing the window and adding the
necessary properties to the notebook (e.g. the
`Notebook:group-name` ).
## `page`
the tab of `notebook` that is being detached
## `x`
the X coordinate where the drop happens
## `y`
the Y coordinate where the drop happens

# Returns

a `Notebook` that `page` should be
 added to, or `None`.
<!-- trait NotebookExt::fn connect_page_added -->
the ::page-added signal is emitted in the notebook
right after a page is added to the notebook.
## `child`
the child `Widget` affected
## `page_num`
the new page number for `child`
<!-- trait NotebookExt::fn connect_page_removed -->
the ::page-removed signal is emitted in the notebook
right after a page is removed from the notebook.
## `child`
the child `Widget` affected
## `page_num`
the `child` page number
<!-- trait NotebookExt::fn connect_page_reordered -->
the ::page-reordered signal is emitted in the notebook
right after a page has been reordered.
## `child`
the child `Widget` affected
## `page_num`
the new page number for `child`
<!-- trait NotebookExt::fn connect_switch_page -->
Emitted when the user or a function changes the current page.
## `page`
the new current page
## `page_num`
the index of the page
<!-- trait NotebookExt::fn get_property_group_name -->
Group name for tab drag and drop.
<!-- trait NotebookExt::fn set_property_group_name -->
Group name for tab drag and drop.
<!-- enum NotebookTab -->
<!-- enum NumberUpLayout -->
Used to determine the layout of pages on a sheet when printing
multiple pages per sheet.
<!-- enum NumberUpLayout::variant Lrtb -->
![](layout-lrtb.png)
<!-- enum NumberUpLayout::variant Lrbt -->
![](layout-lrbt.png)
<!-- enum NumberUpLayout::variant Rltb -->
![](layout-rltb.png)
<!-- enum NumberUpLayout::variant Rlbt -->
![](layout-rlbt.png)
<!-- enum NumberUpLayout::variant Tblr -->
![](layout-tblr.png)
<!-- enum NumberUpLayout::variant Tbrl -->
![](layout-tbrl.png)
<!-- enum NumberUpLayout::variant Btlr -->
![](layout-btlr.png)
<!-- enum NumberUpLayout::variant Btrl -->
![](layout-btrl.png)
<!-- struct OffscreenWindow -->
`OffscreenWindow` is strictly intended to be used for obtaining
snapshots of widgets that are not part of a normal widget hierarchy.
Since `OffscreenWindow` is a toplevel widget you cannot obtain
snapshots of a full window with it since you cannot pack a toplevel
widget in another toplevel.

The idea is to take a widget and manually set the state of it,
add it to a `OffscreenWindow` and then retrieve the snapshot
as a `cairo::Surface` or `gdk_pixbuf::Pixbuf`.

`OffscreenWindow` derives from `Window` only as an implementation
detail. Applications should not use any API specific to `Window`
to operate on this object. It should be treated as a `Bin` that
has no parent widget.

When contained offscreen widgets are redrawn, `OffscreenWindow`
will emit a `Widget::damage-event` signal.

# Implements

[`OffscreenWindowExt`](trait.OffscreenWindowExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait OffscreenWindowExt -->
Trait containing all `OffscreenWindow` methods.

# Implementors

[`OffscreenWindow`](struct.OffscreenWindow.html)
<!-- impl OffscreenWindow::fn new -->
Creates a toplevel container widget that is used to retrieve
snapshots of widgets without showing them on the screen.

# Returns

A pointer to a `Widget`
<!-- trait OffscreenWindowExt::fn get_pixbuf -->
Retrieves a snapshot of the contained widget in the form of
a `gdk_pixbuf::Pixbuf`. This is a new pixbuf with a reference count of 1,
and the application should unreference it once it is no longer
needed.

# Returns

A `gdk_pixbuf::Pixbuf` pointer, or `None`.
<!-- trait OffscreenWindowExt::fn get_surface -->
Retrieves a snapshot of the contained widget in the form of
a `cairo::Surface`. If you need to keep this around over window
resizes then you should add a reference to it.

# Returns

A `cairo::Surface` pointer to the offscreen
 surface, or `None`.
<!-- struct Orientable -->
The `Orientable` interface is implemented by all widgets that can be
oriented horizontally or vertically. Historically, such widgets have been
realized as subclasses of a common base class (e.g `Box`/`HBox`/`VBox`
or `Scale`/`HScale`/`VScale`). `Orientable` is more flexible in that
it allows the orientation to be changed at runtime, allowing the widgets
to “flip”.

`Orientable` was introduced in GTK+ 2.16.

# Implements

[`OrientableExt`](trait.OrientableExt.html)
<!-- trait OrientableExt -->
Trait containing all `Orientable` methods.

# Implementors

[`AppChooserWidget`](struct.AppChooserWidget.html), [`Box`](struct.Box.html), [`ButtonBox`](struct.ButtonBox.html), [`CellAreaBox`](struct.CellAreaBox.html), [`CellRendererProgress`](struct.CellRendererProgress.html), [`CellView`](struct.CellView.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`FileChooserButton`](struct.FileChooserButton.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FlowBox`](struct.FlowBox.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`Grid`](struct.Grid.html), [`InfoBar`](struct.InfoBar.html), [`LevelBar`](struct.LevelBar.html), [`Orientable`](struct.Orientable.html), [`Paned`](struct.Paned.html), [`ProgressBar`](struct.ProgressBar.html), [`Range`](struct.Range.html), [`RecentChooserWidget`](struct.RecentChooserWidget.html), [`ScaleButton`](struct.ScaleButton.html), [`Scale`](struct.Scale.html), [`Scrollbar`](struct.Scrollbar.html), [`Separator`](struct.Separator.html), [`ShortcutLabel`](struct.ShortcutLabel.html), [`ShortcutsGroup`](struct.ShortcutsGroup.html), [`ShortcutsSection`](struct.ShortcutsSection.html), [`ShortcutsShortcut`](struct.ShortcutsShortcut.html), [`SpinButton`](struct.SpinButton.html), [`StackSwitcher`](struct.StackSwitcher.html), [`Statusbar`](struct.Statusbar.html), [`ToolPalette`](struct.ToolPalette.html), [`Toolbar`](struct.Toolbar.html), [`VolumeButton`](struct.VolumeButton.html)
<!-- trait OrientableExt::fn get_orientation -->
Retrieves the orientation of the `self`.

# Returns

the orientation of the `self`.
<!-- trait OrientableExt::fn set_orientation -->
Sets the orientation of the `self`.
## `orientation`
the orientable’s new orientation.
<!-- trait OrientableExt::fn get_property_orientation -->
The orientation of the orientable.
<!-- trait OrientableExt::fn set_property_orientation -->
The orientation of the orientable.
<!-- enum Orientation -->
Represents the orientation of widgets and other objects which can be switched
between horizontal and vertical orientation on the fly, like `Toolbar` or
`GesturePan`.
<!-- enum Orientation::variant Horizontal -->
The element is in horizontal orientation.
<!-- enum Orientation::variant Vertical -->
The element is in vertical orientation.
<!-- struct Overlay -->
`Overlay` is a container which contains a single main child, on top
of which it can place “overlay” widgets. The position of each overlay
widget is determined by its `Widget:halign` and `Widget:valign`
properties. E.g. a widget with both alignments set to `Align::Start`
will be placed at the top left corner of the `Overlay` container,
whereas an overlay with halign set to `Align::Center` and valign set
to `Align::End` will be placed a the bottom edge of the `Overlay`,
horizontally centered. The position can be adjusted by setting the margin
properties of the child to non-zero values.

More complicated placement of overlays is possible by connecting
to the `Overlay::get-child-position` signal.

An overlay’s minimum and natural sizes are those of its main child. The sizes
of overlay children are not considered when measuring these preferred sizes.

# `Overlay` as `Buildable`

The `Overlay` implementation of the `Buildable` interface
supports placing a child as an overlay by specifying “overlay” as
the “type” attribute of a `<child>` element.

# CSS nodes

`Overlay` has a single CSS node with the name “overlay”. Overlay children
whose alignments cause them to be positioned at an edge get the style classes
“.left”, “.right”, “.top”, and/or “.bottom” according to their position.

# Implements

[`OverlayExt`](trait.OverlayExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OverlaySignals`](prelude/trait.OverlaySignals.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait OverlayExt -->
Trait containing all `Overlay` methods.

# Implementors

[`Overlay`](struct.Overlay.html)
<!-- impl Overlay::fn new -->
Creates a new `Overlay`.

# Returns

a new `Overlay` object.
<!-- trait OverlayExt::fn add_overlay -->
Adds `widget` to `self`.

The widget will be stacked on top of the main widget
added with `ContainerExt::add`.

The position at which `widget` is placed is determined
from its `Widget:halign` and `Widget:valign` properties.
## `widget`
a `Widget` to be added to the container
<!-- trait OverlayExt::fn get_overlay_pass_through -->
Convenience function to get the value of the `Overlay:pass-through`
child property for `widget`.

Feature: `v3_18`

## `widget`
an overlay child of `Overlay`

# Returns

whether the widget is a pass through child.
<!-- trait OverlayExt::fn reorder_overlay -->
Moves `child` to a new `index` in the list of `self` children.
The list contains overlays in the order that these were
added to `self` by default. See also `Overlay:index`.

A widget’s index in the `self` children list determines which order
the children are drawn if they overlap. The first child is drawn at
the bottom. It also affects the default focus chain order.

Feature: `v3_18`

## `child`
the overlaid `Widget` to move
## `index_`
the new index for `child` in the list of overlay children
 of `self`, starting from 0. If negative, indicates the end of
 the list
<!-- trait OverlayExt::fn set_overlay_pass_through -->
Convenience function to set the value of the `Overlay:pass-through`
child property for `widget`.

Feature: `v3_18`

## `widget`
an overlay child of `Overlay`
## `pass_through`
whether the child should pass the input through
<!-- trait OverlayExt::fn connect_get_child_position -->
The ::get-child-position signal is emitted to determine
the position and size of any overlay child widgets. A
handler for this signal should fill `allocation` with
the desired position and size for `widget`, relative to
the 'main' child of `overlay`.

The default handler for this signal uses the `widget`'s
halign and valign properties to determine the position
and gives the widget its natural size (except that an
alignment of `Align::Fill` will cause the overlay to
be full-width/height). If the main child is a
`ScrolledWindow`, the overlays are placed relative
to its contents.
## `widget`
the child widget to position
## `allocation`
return
 location for the allocation

# Returns

`true` if the `allocation` has been filled
<!-- enum PackDirection -->
Determines how widgets should be packed inside menubars
and menuitems contained in menubars.
<!-- enum PackDirection::variant Ltr -->
Widgets are packed left-to-right
<!-- enum PackDirection::variant Rtl -->
Widgets are packed right-to-left
<!-- enum PackDirection::variant Ttb -->
Widgets are packed top-to-bottom
<!-- enum PackDirection::variant Btt -->
Widgets are packed bottom-to-top
<!-- enum PackType -->
Represents the packing location `Box` children. (See: `VBox`,
`HBox`, and `ButtonBox`).
<!-- enum PackType::variant Start -->
The child is packed into the start of the box
<!-- enum PackType::variant End -->
The child is packed into the end of the box
<!-- enum PadActionType -->
The type of a pad action.
<!-- enum PadActionType::variant Button -->
Action is triggered by a pad button
<!-- enum PadActionType::variant Ring -->
Action is triggered by a pad ring
<!-- enum PadActionType::variant Strip -->
Action is triggered by a pad strip

Feature: `v3_22`

<!-- struct PadController -->
`PadController` is an event controller for the pads found in drawing
tablets (The collection of buttons and tactile sensors often found around
the stylus-sensitive area).

These buttons and sensors have no implicit meaning, and by default they
perform no action, this event controller is provided to map those to
`gio::Action` objects, thus letting the application give those a more semantic
meaning.

Buttons and sensors are not constrained to triggering a single action, some
`gdk::InputSource::TabletPad` devices feature multiple "modes", all these input
elements have one current mode, which may determine the final action
being triggered. Pad devices often divide buttons and sensors into groups,
all elements in a group share the same current mode, but different groups
may have different modes. See `gdk::DevicePad::get_n_groups` and
`gdk::DevicePad::get_group_n_modes`.

Each of the actions that a given button/strip/ring performs for a given
mode is defined by `PadActionEntry`, it contains an action name that
will be looked up in the given `gio::ActionGroup` and activated whenever the
specified input element and mode are triggered.

A simple example of `PadController` usage, assigning button 1 in all
modes and pad devices to an "invert-selection" action:

```text
  GtkPadActionEntry *pad_actions[] = {
    { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
    …
  };

  …
  action_group = g_simple_action_group_new ();
  action = g_simple_action_new ("pad-actions.invert-selection", NULL);
  g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
  g_action_map_add_action (G_ACTION_MAP (action_group), action);
  …
  pad_controller = gtk_pad_controller_new (window, action_group, NULL);
```

The actions belonging to rings/strips will be activated with a parameter
of type `G_VARIANT_TYPE_DOUBLE` bearing the value of the given axis, it
is required that those are made stateful and accepting this `glib::VariantType`.

Feature: `v3_22`

# Implements

[`EventControllerExt`](trait.EventControllerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl PadController::fn new -->
Creates a new `PadController` that will associate events from `pad` to
actions. A `None` pad may be provided so the controller manages all pad devices
generically, it is discouraged to mix `PadController` objects with `None`
and non-`None` `pad` argument on the same `window`, as execution order is not
guaranteed.

The `PadController` is created with no mapped actions. In order to map pad
events to actions, use `PadController::set_action_entries` or
`PadController::set_action`.

Feature: `v3_22`

## `window`
a `Window`
## `group`
`gio::ActionGroup` to trigger actions from
## `pad`
A `gdk::InputSource::TabletPad` device, or `None` to handle all pads

# Returns

A newly created `PadController`
<!-- impl PadController::fn set_action -->
Adds an individual action to `self`. This action will only be activated
if the given button/ring/strip number in `index` is interacted while
the current mode is `mode`. -1 may be used for simple cases, so the action
is triggered on all modes.

The given `label` should be considered user-visible, so internationalization
rules apply. Some windowing systems may be able to use those for user
feedback.

Feature: `v3_22`

## `type_`
the type of pad feature that will trigger this action
## `index`
the 0-indexed button/ring/strip number that will trigger this action
## `mode`
the mode that will trigger this action, or -1 for all modes.
## `label`
Human readable description of this action, this string should
 be deemed user-visible.
## `action_name`
action name that will be activated in the `gio::ActionGroup`
<!-- impl PadController::fn set_action_entries -->
This is a convenience function to add a group of action entries on
`self`. See `PadActionEntry` and `PadController::set_action`.

Feature: `v3_22`

## `entries`
the action entries to set on `self`
## `n_entries`
the number of elements in `entries`
<!-- enum PageOrientation -->
See also `PrintSettings::set_orientation`.
<!-- enum PageOrientation::variant Portrait -->
Portrait mode.
<!-- enum PageOrientation::variant Landscape -->
Landscape mode.
<!-- enum PageOrientation::variant ReversePortrait -->
Reverse portrait mode.
<!-- enum PageOrientation::variant ReverseLandscape -->
Reverse landscape mode.
<!-- enum PageSet -->
See also `gtk_print_job_set_page_set`.
<!-- enum PageSet::variant All -->
All pages.
<!-- enum PageSet::variant Even -->
Even pages.
<!-- enum PageSet::variant Odd -->
Odd pages.
<!-- struct PageSetup -->
A `PageSetup` object stores the page size, orientation and margins.
The idea is that you can get one of these from the page setup dialog
and then pass it to the `PrintOperation` when printing.
The benefit of splitting this out of the `PrintSettings` is that
these affect the actual layout of the page, and thus need to be set
long before user prints.

## Margins ## {`print`-margins}
The margins specified in this object are the “print margins”, i.e. the
parts of the page that the printer cannot print on. These are different
from the layout margins that a word processor uses; they are typically
used to determine the minimal size for the layout
margins.

To obtain a `PageSetup` use `PageSetup::new` to get the defaults,
or use `gtk_print_run_page_setup_dialog` to show the page setup dialog
and receive the resulting page setup.

## A page setup dialog


```C
static GtkPrintSettings *settings = NULL;
static GtkPageSetup *page_setup = NULL;

static void
do_page_setup (void)
{
  GtkPageSetup *new_page_setup;

  if (settings == NULL)
    settings = gtk_print_settings_new ();

  new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window),
                                                    page_setup, settings);

  if (page_setup)
    g_object_unref (page_setup);

  page_setup = new_page_setup;
}
```

Printing support was added in GTK+ 2.10.

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl PageSetup::fn new -->
Creates a new `PageSetup`.

# Returns

a new `PageSetup`.
<!-- impl PageSetup::fn new_from_file -->
Reads the page setup from the file `file_name`. Returns a
new `PageSetup` object with the restored page setup,
or `None` if an error occurred. See `PageSetup::to_file`.
## `file_name`
the filename to read the page setup from

# Returns

the restored `PageSetup`
<!-- impl PageSetup::fn new_from_gvariant -->
Desrialize a page setup from an a{sv} variant in
the format produced by `PageSetup::to_gvariant`.

Feature: `v3_22`

## `variant`
an a{sv} `glib::Variant`

# Returns

a new `PageSetup` object
<!-- impl PageSetup::fn new_from_key_file -->
Reads the page setup from the group `group_name` in the key file
`key_file`. Returns a new `PageSetup` object with the restored
page setup, or `None` if an error occurred.
## `key_file`
the `glib::KeyFile` to retrieve the page_setup from
## `group_name`
the name of the group in the key_file to read, or `None`
 to use the default name “Page Setup”

# Returns

the restored `PageSetup`
<!-- impl PageSetup::fn copy -->
Copies a `PageSetup`.

# Returns

a copy of `self`
<!-- impl PageSetup::fn get_bottom_margin -->
Gets the bottom margin in units of `unit`.
## `unit`
the unit for the return value

# Returns

the bottom margin
<!-- impl PageSetup::fn get_left_margin -->
Gets the left margin in units of `unit`.
## `unit`
the unit for the return value

# Returns

the left margin
<!-- impl PageSetup::fn get_orientation -->
Gets the page orientation of the `PageSetup`.

# Returns

the page orientation
<!-- impl PageSetup::fn get_page_height -->
Returns the page height in units of `unit`.

Note that this function takes orientation and
margins into consideration.
See `PageSetup::get_paper_height`.
## `unit`
the unit for the return value

# Returns

the page height.
<!-- impl PageSetup::fn get_page_width -->
Returns the page width in units of `unit`.

Note that this function takes orientation and
margins into consideration.
See `PageSetup::get_paper_width`.
## `unit`
the unit for the return value

# Returns

the page width.
<!-- impl PageSetup::fn get_paper_height -->
Returns the paper height in units of `unit`.

Note that this function takes orientation, but
not margins into consideration.
See `PageSetup::get_page_height`.
## `unit`
the unit for the return value

# Returns

the paper height.
<!-- impl PageSetup::fn get_paper_size -->
Gets the paper size of the `PageSetup`.

# Returns

the paper size
<!-- impl PageSetup::fn get_paper_width -->
Returns the paper width in units of `unit`.

Note that this function takes orientation, but
not margins into consideration.
See `PageSetup::get_page_width`.
## `unit`
the unit for the return value

# Returns

the paper width.
<!-- impl PageSetup::fn get_right_margin -->
Gets the right margin in units of `unit`.
## `unit`
the unit for the return value

# Returns

the right margin
<!-- impl PageSetup::fn get_top_margin -->
Gets the top margin in units of `unit`.
## `unit`
the unit for the return value

# Returns

the top margin
<!-- impl PageSetup::fn load_file -->
Reads the page setup from the file `file_name`.
See `PageSetup::to_file`.
## `file_name`
the filename to read the page setup from

# Returns

`true` on success
<!-- impl PageSetup::fn load_key_file -->
Reads the page setup from the group `group_name` in the key file
`key_file`.
## `key_file`
the `glib::KeyFile` to retrieve the page_setup from
## `group_name`
the name of the group in the key_file to read, or `None`
 to use the default name “Page Setup”

# Returns

`true` on success
<!-- impl PageSetup::fn set_bottom_margin -->
Sets the bottom margin of the `PageSetup`.
## `margin`
the new bottom margin in units of `unit`
## `unit`
the units for `margin`
<!-- impl PageSetup::fn set_left_margin -->
Sets the left margin of the `PageSetup`.
## `margin`
the new left margin in units of `unit`
## `unit`
the units for `margin`
<!-- impl PageSetup::fn set_orientation -->
Sets the page orientation of the `PageSetup`.
## `orientation`
a `PageOrientation` value
<!-- impl PageSetup::fn set_paper_size -->
Sets the paper size of the `PageSetup` without
changing the margins. See
`PageSetup::set_paper_size_and_default_margins`.
## `size`
a `PaperSize`
<!-- impl PageSetup::fn set_paper_size_and_default_margins -->
Sets the paper size of the `PageSetup` and modifies
the margins according to the new paper size.
## `size`
a `PaperSize`
<!-- impl PageSetup::fn set_right_margin -->
Sets the right margin of the `PageSetup`.
## `margin`
the new right margin in units of `unit`
## `unit`
the units for `margin`
<!-- impl PageSetup::fn set_top_margin -->
Sets the top margin of the `PageSetup`.
## `margin`
the new top margin in units of `unit`
## `unit`
the units for `margin`
<!-- impl PageSetup::fn to_file -->
This function saves the information from `self` to `file_name`.
## `file_name`
the file to save to

# Returns

`true` on success
<!-- impl PageSetup::fn to_gvariant -->
Serialize page setup to an a{sv} variant.

Feature: `v3_22`


# Returns

a new, floating, `glib::Variant`
<!-- impl PageSetup::fn to_key_file -->
This function adds the page setup from `self` to `key_file`.
## `key_file`
the `glib::KeyFile` to save the page setup to
## `group_name`
the group to add the settings to in `key_file`,
 or `None` to use the default name “Page Setup”
<!-- enum PanDirection -->
Describes the panning direction of a `GesturePan`
<!-- enum PanDirection::variant Left -->
panned towards the left
<!-- enum PanDirection::variant Right -->
panned towards the right
<!-- enum PanDirection::variant Up -->
panned upwards
<!-- enum PanDirection::variant Down -->
panned downwards
<!-- struct Paned -->
`Paned` has two panes, arranged either
horizontally or vertically. The division between
the two panes is adjustable by the user by dragging
a handle.

Child widgets are
added to the panes of the widget with `PanedExt::pack1` and
`PanedExt::pack2`. The division between the two children is set by default
from the size requests of the children, but it can be adjusted by the
user.

A paned widget draws a separator between the two child widgets and a
small handle that the user can drag to adjust the division. It does not
draw any relief around the children or around the separator. (The space
in which the separator is called the gutter.) Often, it is useful to put
each child inside a `Frame` with the shadow type set to `ShadowType::In`
so that the gutter appears as a ridge. No separator is drawn if one of
the children is missing.

Each child has two options that can be set, `resize` and `shrink`. If
`resize` is true, then when the `Paned` is resized, that child will
expand or shrink along with the paned widget. If `shrink` is true, then
that child can be made smaller than its requisition by the user.
Setting `shrink` to `false` allows the application to set a minimum size.
If `resize` is false for both children, then this is treated as if
`resize` is true for both children.

The application can set the position of the slider as if it were set
by the user, by calling `PanedExt::set_position`.

# CSS nodes


```plain
paned
├── <child>
├── separator[.wide]
╰── <child>
```

`Paned` has a main CSS node with name paned, and a subnode for
the separator with name separator. The subnode gets a .wide style
class when the paned is supposed to be wide.

In horizontal orientation, the nodes of the children are always arranged
from left to right. So :first-child will always select the leftmost child,
regardless of text direction.

## Creating a paned widget with minimum sizes.


```C
GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL);
GtkWidget *frame1 = gtk_frame_new (NULL);
GtkWidget *frame2 = gtk_frame_new (NULL);
gtk_frame_set_shadow_type (GTK_FRAME (frame1), GTK_SHADOW_IN);
gtk_frame_set_shadow_type (GTK_FRAME (frame2), GTK_SHADOW_IN);

gtk_widget_set_size_request (hpaned, 200, -1);

gtk_paned_pack1 (GTK_PANED (hpaned), frame1, TRUE, FALSE);
gtk_widget_set_size_request (frame1, 50, -1);

gtk_paned_pack2 (GTK_PANED (hpaned), frame2, FALSE, FALSE);
gtk_widget_set_size_request (frame2, 50, -1);
```

# Implements

[`PanedExt`](trait.PanedExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait PanedExt -->
Trait containing all `Paned` methods.

# Implementors

[`Paned`](struct.Paned.html)
<!-- impl Paned::fn new -->
Creates a new `Paned` widget.
## `orientation`
the paned’s orientation.

# Returns

a new `Paned`.
<!-- trait PanedExt::fn add1 -->
Adds a child to the top or left pane with default parameters. This is
equivalent to
`gtk_paned_pack1 (paned, child, FALSE, TRUE)`.
## `child`
the child to add
<!-- trait PanedExt::fn add2 -->
Adds a child to the bottom or right pane with default parameters. This
is equivalent to
`gtk_paned_pack2 (paned, child, TRUE, TRUE)`.
## `child`
the child to add
<!-- trait PanedExt::fn get_child1 -->
Obtains the first child of the paned widget.

# Returns

first child, or `None` if it is not set.
<!-- trait PanedExt::fn get_child2 -->
Obtains the second child of the paned widget.

# Returns

second child, or `None` if it is not set.
<!-- trait PanedExt::fn get_handle_window -->
Returns the `gdk::Window` of the handle. This function is
useful when handling button or motion events because it
enables the callback to distinguish between the window
of the paned, a child and the handle.

# Returns

the paned’s handle window.
<!-- trait PanedExt::fn get_position -->
Obtains the position of the divider between the two panes.

# Returns

position of the divider
<!-- trait PanedExt::fn get_wide_handle -->
Gets the `Paned:wide-handle` property.

Feature: `v3_16`


# Returns

`true` if the paned should have a wide handle
<!-- trait PanedExt::fn pack1 -->
Adds a child to the top or left pane.
## `child`
the child to add
## `resize`
should this child expand when the paned widget is resized.
## `shrink`
can this child be made smaller than its requisition.
<!-- trait PanedExt::fn pack2 -->
Adds a child to the bottom or right pane.
## `child`
the child to add
## `resize`
should this child expand when the paned widget is resized.
## `shrink`
can this child be made smaller than its requisition.
<!-- trait PanedExt::fn set_position -->
Sets the position of the divider between the two panes.
## `position`
pixel position of divider, a negative value means that the position
 is unset.
<!-- trait PanedExt::fn set_wide_handle -->
Sets the `Paned:wide-handle` property.

Feature: `v3_16`

## `wide`
the new value for the `Paned:wide-handle` property
<!-- trait PanedExt::fn connect_accept_position -->
The ::accept-position signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to accept the current position of the handle when
moving it using key bindings.

The default binding for this signal is Return or Space.
<!-- trait PanedExt::fn connect_cancel_position -->
The ::cancel-position signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to cancel moving the position of the handle using key
bindings. The position of the handle will be reset to the value prior to
moving it.

The default binding for this signal is Escape.
<!-- trait PanedExt::fn connect_cycle_child_focus -->
The ::cycle-child-focus signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to cycle the focus between the children of the paned.

The default binding is f6.
## `reversed`
whether cycling backward or forward
<!-- trait PanedExt::fn connect_cycle_handle_focus -->
The ::cycle-handle-focus signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to cycle whether the paned should grab focus to allow
the user to change position of the handle by using key bindings.

The default binding for this signal is f8.
## `reversed`
whether cycling backward or forward
<!-- trait PanedExt::fn connect_move_handle -->
The ::move-handle signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to move the handle when the user is using key bindings
to move it.
## `scroll_type`
a `ScrollType`
<!-- trait PanedExt::fn connect_toggle_handle_focus -->
The ::toggle-handle-focus is a
[keybinding signal][`BindingSignal`]
which gets emitted to accept the current position of the handle and then
move focus to the next widget in the focus chain.

The default binding is Tab.
<!-- trait PanedExt::fn get_property_max_position -->
The largest possible value for the position property.
This property is derived from the size and shrinkability
of the widget's children.
<!-- trait PanedExt::fn get_property_min_position -->
The smallest possible value for the position property.
This property is derived from the size and shrinkability
of the widget's children.
<!-- trait PanedExt::fn get_property_wide_handle -->
Setting this property to `true` indicates that the paned needs
to provide stronger visual separation (e.g. because it separates
between two notebooks, whose tab rows would otherwise merge visually).

Feature: `v3_16`

<!-- trait PanedExt::fn set_property_wide_handle -->
Setting this property to `true` indicates that the paned needs
to provide stronger visual separation (e.g. because it separates
between two notebooks, whose tab rows would otherwise merge visually).

Feature: `v3_16`

<!-- struct PaperSize -->
`PaperSize` handles paper sizes. It uses the standard called
[PWG 5101.1-2002 PWG: Standard for Media Standardized Names](http://www.pwg.org/standards.html)
to name the paper sizes (and to get the data for the page sizes).
In addition to standard paper sizes, `PaperSize` allows to
construct custom paper sizes with arbitrary dimensions.

The `PaperSize` object stores not only the dimensions (width
and height) of a paper size and its name, it also provides
default [print margins][print-margins].

Printing support has been added in GTK+ 2.10.
<!-- impl PaperSize::fn new -->
Creates a new `PaperSize` object by parsing a
[PWG 5101.1-2002](ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf)
paper name.

If `name` is `None`, the default paper size is returned,
see `PaperSize::get_default`.
## `name`
a paper size name, or `None`

# Returns

a new `PaperSize`, use `PaperSize::free`
to free it
<!-- impl PaperSize::fn new_custom -->
Creates a new `PaperSize` object with the
given parameters.
## `name`
the paper name
## `display_name`
the human-readable name
## `width`
the paper width, in units of `unit`
## `height`
the paper height, in units of `unit`
## `unit`
the unit for `width` and `height`. not `Unit::None`.

# Returns

a new `PaperSize` object, use `PaperSize::free`
to free it
<!-- impl PaperSize::fn new_from_gvariant -->
Deserialize a paper size from an a{sv} variant in
the format produced by `PaperSize::to_gvariant`.

Feature: `v3_22`

## `variant`
an a{sv} `glib::Variant`

# Returns

a new `PaperSize` object
<!-- impl PaperSize::fn new_from_ipp -->
Creates a new `PaperSize` object by using
IPP information.

If `ipp_name` is not a recognized paper name,
`width` and `height` are used to
construct a custom `PaperSize` object.

Feature: `v3_16`

## `ipp_name`
an IPP paper name
## `width`
the paper width, in points
## `height`
the paper height in points

# Returns

a new `PaperSize`, use `PaperSize::free`
to free it
<!-- impl PaperSize::fn new_from_key_file -->
Reads a paper size from the group `group_name` in the key file
`key_file`.
## `key_file`
the `glib::KeyFile` to retrieve the papersize from
## `group_name`
the name of the group in the key file to read,
 or `None` to read the first group

# Returns

a new `PaperSize` object with the restored
 paper size, or `None` if an error occurred
<!-- impl PaperSize::fn new_from_ppd -->
Creates a new `PaperSize` object by using
PPD information.

If `ppd_name` is not a recognized PPD paper name,
`ppd_display_name`, `width` and `height` are used to
construct a custom `PaperSize` object.
## `ppd_name`
a PPD paper name
## `ppd_display_name`
the corresponding human-readable name
## `width`
the paper width, in points
## `height`
the paper height in points

# Returns

a new `PaperSize`, use `PaperSize::free`
to free it
<!-- impl PaperSize::fn copy -->
Copies an existing `PaperSize`.

# Returns

a copy of `self`
<!-- impl PaperSize::fn free -->
Free the given `PaperSize` object.
<!-- impl PaperSize::fn get_default_bottom_margin -->
Gets the default bottom margin for the `PaperSize`.
## `unit`
the unit for the return value, not `Unit::None`

# Returns

the default bottom margin
<!-- impl PaperSize::fn get_default_left_margin -->
Gets the default left margin for the `PaperSize`.
## `unit`
the unit for the return value, not `Unit::None`

# Returns

the default left margin
<!-- impl PaperSize::fn get_default_right_margin -->
Gets the default right margin for the `PaperSize`.
## `unit`
the unit for the return value, not `Unit::None`

# Returns

the default right margin
<!-- impl PaperSize::fn get_default_top_margin -->
Gets the default top margin for the `PaperSize`.
## `unit`
the unit for the return value, not `Unit::None`

# Returns

the default top margin
<!-- impl PaperSize::fn get_display_name -->
Gets the human-readable name of the `PaperSize`.

# Returns

the human-readable name of `self`
<!-- impl PaperSize::fn get_height -->
Gets the paper height of the `PaperSize`, in
units of `unit`.
## `unit`
the unit for the return value, not `Unit::None`

# Returns

the paper height
<!-- impl PaperSize::fn get_name -->
Gets the name of the `PaperSize`.

# Returns

the name of `self`
<!-- impl PaperSize::fn get_ppd_name -->
Gets the PPD name of the `PaperSize`, which
may be `None`.

# Returns

the PPD name of `self`
<!-- impl PaperSize::fn get_width -->
Gets the paper width of the `PaperSize`, in
units of `unit`.
## `unit`
the unit for the return value, not `Unit::None`

# Returns

the paper width
<!-- impl PaperSize::fn is_custom -->
Returns `true` if `self` is not a standard paper size.

# Returns

whether `self` is a custom paper size.
<!-- impl PaperSize::fn is_equal -->
Compares two `PaperSize` objects.
## `size2`
another `PaperSize` object

# Returns

`true`, if `self` and `size2`
represent the same paper size
<!-- impl PaperSize::fn is_ipp -->
Returns `true` if `self` is an IPP standard paper size.

# Returns

whether `self` is not an IPP custom paper size.
<!-- impl PaperSize::fn set_size -->
Changes the dimensions of a `self` to `width` x `height`.
## `width`
the new width in units of `unit`
## `height`
the new height in units of `unit`
## `unit`
the unit for `width` and `height`
<!-- impl PaperSize::fn to_gvariant -->
Serialize a paper size to an a{sv} variant.

Feature: `v3_22`


# Returns

a new, floating, `glib::Variant`
<!-- impl PaperSize::fn to_key_file -->
This function adds the paper size from `self` to `key_file`.
## `key_file`
the `glib::KeyFile` to save the paper size to
## `group_name`
the group to add the settings to in `key_file`
<!-- impl PaperSize::fn get_default -->
Returns the name of the default paper size, which
depends on the current locale.

# Returns

the name of the default paper size. The string
is owned by GTK+ and should not be modified.
<!-- impl PaperSize::fn get_paper_sizes -->
Creates a list of known paper sizes.
## `include_custom`
whether to include custom paper sizes
 as defined in the page setup dialog

# Returns

a newly allocated list of newly
 allocated `PaperSize` objects
<!-- struct PlacesOpenFlags -->
These flags serve two purposes. First, the application can call `PlacesSidebar::set_open_flags`
using these flags as a bitmask. This tells the sidebar that the application is able to open
folders selected from the sidebar in various ways, for example, in new tabs or in new windows in
addition to the normal mode.

Second, when one of these values gets passed back to the application in the
`PlacesSidebar::open-location` signal, it means that the application should
open the selected location in the normal way, in a new tab, or in a new
window. The sidebar takes care of determining the desired way to open the location,
based on the modifier keys that the user is pressing at the time the selection is made.

If the application never calls `PlacesSidebar::set_open_flags`, then the sidebar will only
use `PlacesOpenFlags::Normal` in the `PlacesSidebar::open-location` signal. This is the
default mode of operation.
<!-- struct PlacesOpenFlags::const NORMAL -->
This is the default mode that `PlacesSidebar` uses if no other flags
 are specified. It indicates that the calling application should open the selected location
 in the normal way, for example, in the folder view beside the sidebar.
<!-- struct PlacesOpenFlags::const NEW_TAB -->
When passed to `PlacesSidebar::set_open_flags`, this indicates
 that the application can open folders selected from the sidebar in new tabs. This value
 will be passed to the `PlacesSidebar::open-location` signal when the user selects
 that a location be opened in a new tab instead of in the standard fashion.
<!-- struct PlacesOpenFlags::const NEW_WINDOW -->
Similar to `PlacesOpenFlags::NewTab`, but indicates that the application
 can open folders in new windows.
<!-- struct PlacesSidebar -->
`PlacesSidebar` is a widget that displays a list of frequently-used places in the
file system: the user’s home directory, the user’s bookmarks, and volumes and drives.
This widget is used as a sidebar in `FileChooser` and may be used by file managers
and similar programs.

The places sidebar displays drives and volumes, and will automatically mount
or unmount them when the user selects them.

Applications can hook to various signals in the places sidebar to customize
its behavior. For example, they can add extra commands to the context menu
of the sidebar.

While bookmarks are completely in control of the user, the places sidebar also
allows individual applications to provide extra shortcut folders that are unique
to each application. For example, a Paint program may want to add a shortcut
for a Clipart folder. You can do this with `PlacesSidebar::add_shortcut`.

To make use of the places sidebar, an application at least needs to connect
to the `PlacesSidebar::open-location` signal. This is emitted when the
user selects in the sidebar a location to open. The application should also
call `PlacesSidebar::set_location` when it changes the currently-viewed
location.

# CSS nodes

`PlacesSidebar` uses a single CSS node with name placessidebar and style
class .sidebar.

Among the children of the places sidebar, the following style classes can
be used:
- .sidebar-new-bookmark-row for the 'Add new bookmark' row
- .sidebar-placeholder-row for a row that is a placeholder
- .has-open-popup when a popup is open for a row

# Implements

[`ScrolledWindowExt`](trait.ScrolledWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl PlacesSidebar::fn new -->
Creates a new `PlacesSidebar` widget.

The application should connect to at least the
`PlacesSidebar::open-location` signal to be notified
when the user makes a selection in the sidebar.

# Returns

a newly created `PlacesSidebar`
<!-- impl PlacesSidebar::fn add_shortcut -->
Applications may want to present some folders in the places sidebar if
they could be immediately useful to users. For example, a drawing
program could add a “/usr/share/clipart” location when the sidebar is
being used in an “Insert Clipart” dialog box.

This function adds the specified `location` to a special place for immutable
shortcuts. The shortcuts are application-specific; they are not shared
across applications, and they are not persistent. If this function
is called multiple times with different locations, then they are added
to the sidebar’s list in the same order as the function is called.
## `location`
location to add as an application-specific shortcut
<!-- impl PlacesSidebar::fn get_local_only -->
Returns the value previously set with `PlacesSidebar::set_local_only`.

# Returns

`true` if the sidebar will only show local files.
<!-- impl PlacesSidebar::fn get_location -->
Gets the currently selected location in the `self`. This can be `None` when
nothing is selected, for example, when `PlacesSidebar::set_location` has
been called with a location that is not among the sidebar’s list of places to
show.

You can use this function to get the selection in the `self`. Also, if you
connect to the `PlacesSidebar::populate-popup` signal, you can use this
function to get the location that is being referred to during the callbacks
for your menu items.

# Returns

a `gio::File` with the selected location, or
`None` if nothing is visually selected.
<!-- impl PlacesSidebar::fn get_nth_bookmark -->
This function queries the bookmarks added by the user to the places sidebar,
and returns one of them. This function is used by `FileChooser` to implement
the “Alt-1”, “Alt-2”, etc. shortcuts, which activate the cooresponding bookmark.
## `n`
index of the bookmark to query

# Returns

The bookmark specified by the index `n`, or
`None` if no such index exist. Note that the indices start at 0, even though
the file chooser starts them with the keyboard shortcut "Alt-1".
<!-- impl PlacesSidebar::fn get_open_flags -->
Gets the open flags.

# Returns

the `PlacesOpenFlags` of `self`
<!-- impl PlacesSidebar::fn get_show_connect_to_server -->
Returns the value previously set with `PlacesSidebar::set_show_connect_to_server`

# Deprecated since 3.18

It is recommended to group this functionality with the drives
 and network location under the new 'Other Location' item

# Returns

`true` if the sidebar will display a “Connect to Server” item.
<!-- impl PlacesSidebar::fn get_show_desktop -->
Returns the value previously set with `PlacesSidebar::set_show_desktop`

# Returns

`true` if the sidebar will display a builtin shortcut to the desktop folder.
<!-- impl PlacesSidebar::fn get_show_enter_location -->
Returns the value previously set with `PlacesSidebar::set_show_enter_location`

# Returns

`true` if the sidebar will display an “Enter Location” item.
<!-- impl PlacesSidebar::fn get_show_other_locations -->
Returns the value previously set with `PlacesSidebar::set_show_other_locations`

Feature: `v3_18`


# Returns

`true` if the sidebar will display an “Other Locations” item.
<!-- impl PlacesSidebar::fn get_show_recent -->
Returns the value previously set with `PlacesSidebar::set_show_recent`

Feature: `v3_18`


# Returns

`true` if the sidebar will display a builtin shortcut for recent files
<!-- impl PlacesSidebar::fn get_show_starred_location -->
Returns the value previously set with `PlacesSidebar::set_show_starred_location`

Feature: `v3_22_26`


# Returns

`true` if the sidebar will display a Starred item.
<!-- impl PlacesSidebar::fn get_show_trash -->
Returns the value previously set with `PlacesSidebar::set_show_trash`

Feature: `v3_18`


# Returns

`true` if the sidebar will display a “Trash” item.
<!-- impl PlacesSidebar::fn list_shortcuts -->
Gets the list of shortcuts.

# Returns


 A `glib::SList` of `gio::File` of the locations that have been added as
 application-specific shortcuts with `PlacesSidebar::add_shortcut`.
 To free this list, you can use

```C
g_slist_free_full (list, (GDestroyNotify) g_object_unref);
```
<!-- impl PlacesSidebar::fn remove_shortcut -->
Removes an application-specific shortcut that has been previously been
inserted with `PlacesSidebar::add_shortcut`. If the `location` is not a
shortcut in the sidebar, then nothing is done.
## `location`
location to remove
<!-- impl PlacesSidebar::fn set_drop_targets_visible -->
Make the `PlacesSidebar` show drop targets, so it can show the available
drop targets and a "new bookmark" row. This improves the Drag-and-Drop
experience of the user and allows applications to show all available
drop targets at once.

This needs to be called when the application is aware of an ongoing drag
that might target the sidebar. The drop-targets-visible state will be unset
automatically if the drag finishes in the `PlacesSidebar`. You only need
to unset the state when the drag ends on some other widget on your application.

Feature: `v3_18`

## `visible`
whether to show the valid targets or not.
## `context`
drag context used to ask the source about the action that wants to
 perform, so hints are more accurate.
<!-- impl PlacesSidebar::fn set_local_only -->
Sets whether the `self` should only show local files.
## `local_only`
whether to show only local files
<!-- impl PlacesSidebar::fn set_location -->
Sets the location that is being shown in the widgets surrounding the
`self`, for example, in a folder view in a file manager. In turn, the
`self` will highlight that location if it is being shown in the list of
places, or it will unhighlight everything if the `location` is not among the
places in the list.
## `location`
location to select, or `None` for no current path
<!-- impl PlacesSidebar::fn set_open_flags -->
Sets the way in which the calling application can open new locations from
the places sidebar. For example, some applications only open locations
“directly” into their main view, while others may support opening locations
in a new notebook tab or a new window.

This function is used to tell the places `self` about the ways in which the
application can open new locations, so that the sidebar can display (or not)
the “Open in new tab” and “Open in new window” menu items as appropriate.

When the `PlacesSidebar::open-location` signal is emitted, its flags
argument will be set to one of the `flags` that was passed in
`PlacesSidebar::set_open_flags`.

Passing 0 for `flags` will cause `PlacesOpenFlags::Normal` to always be sent
to callbacks for the “open-location” signal.
## `flags`
Bitmask of modes in which the calling application can open locations
<!-- impl PlacesSidebar::fn set_show_connect_to_server -->
Sets whether the `self` should show an item for connecting to a network server;
this is off by default. An application may want to turn this on if it implements
a way for the user to connect to network servers directly.

If you enable this, you should connect to the
`PlacesSidebar::show-connect-to-server` signal.

# Deprecated since 3.18

It is recommended to group this functionality with the drives
 and network location under the new 'Other Location' item
## `show_connect_to_server`
whether to show an item for the Connect to Server command
<!-- impl PlacesSidebar::fn set_show_desktop -->
Sets whether the `self` should show an item for the Desktop folder.
The default value for this option is determined by the desktop
environment and the user’s configuration, but this function can be
used to override it on a per-application basis.
## `show_desktop`
whether to show an item for the Desktop folder
<!-- impl PlacesSidebar::fn set_show_enter_location -->
Sets whether the `self` should show an item for entering a location;
this is off by default. An application may want to turn this on if manually
entering URLs is an expected user action.

If you enable this, you should connect to the
`PlacesSidebar::show-enter-location` signal.
## `show_enter_location`
whether to show an item to enter a location
<!-- impl PlacesSidebar::fn set_show_other_locations -->
Sets whether the `self` should show an item for the application to show
an Other Locations view; this is off by default. When set to `true`, persistent
devices such as hard drives are hidden, otherwise they are shown in the sidebar.
An application may want to turn this on if it implements a way for the user to
see and interact with drives and network servers directly.

If you enable this, you should connect to the
`PlacesSidebar::show-other-locations` signal.

Feature: `v3_18`

## `show_other_locations`
whether to show an item for the Other Locations view
<!-- impl PlacesSidebar::fn set_show_recent -->
Sets whether the `self` should show an item for recent files.
The default value for this option is determined by the desktop
environment, but this function can be used to override it on a
per-application basis.

Feature: `v3_18`

## `show_recent`
whether to show an item for recent files
<!-- impl PlacesSidebar::fn set_show_starred_location -->
If you enable this, you should connect to the
`PlacesSidebar::show-starred-location` signal.

Feature: `v3_22_26`

## `show_starred_location`
whether to show an item for Starred files
<!-- impl PlacesSidebar::fn set_show_trash -->
Sets whether the `self` should show an item for the Trash location.

Feature: `v3_18`

## `show_trash`
whether to show an item for the Trash location
<!-- impl PlacesSidebar::fn connect_drag_action_ask -->
The places sidebar emits this signal when it needs to ask the application
to pop up a menu to ask the user for which drag action to perform.
## `actions`
Possible drag actions that need to be asked for.

# Returns

the final drag action that the sidebar should pass to the drag side
of the drag-and-drop operation.
<!-- impl PlacesSidebar::fn connect_drag_action_requested -->
When the user starts a drag-and-drop operation and the sidebar needs
to ask the application for which drag action to perform, then the
sidebar will emit this signal.

The application can evaluate the `context` for customary actions, or
it can check the type of the files indicated by `source_file_list` against the
possible actions for the destination `dest_file`.

The drag action to use must be the return value of the signal handler.
## `context`
`gdk::DragContext` with information about the drag operation
## `dest_file`
`gio::File` with the tentative location that is being hovered for a drop
## `source_file_list`

 List of `gio::File` that are being dragged

# Returns

The drag action to use, for example, `gdk::DragAction::Copy`
or `gdk::DragAction::Move`, or 0 if no action is allowed here (i.e. drops
are not allowed in the specified `dest_file`).
<!-- impl PlacesSidebar::fn connect_drag_perform_drop -->
The places sidebar emits this signal when the user completes a
drag-and-drop operation and one of the sidebar's items is the
destination. This item is in the `dest_file`, and the
`source_file_list` has the list of files that are dropped into it and
which should be copied/moved/etc. based on the specified `action`.
## `dest_file`
Destination `gio::File`.
## `source_file_list`

 `glib::List` of `gio::File` that got dropped.
## `action`
Drop action to perform.
<!-- impl PlacesSidebar::fn connect_mount -->
The places sidebar emits this signal when it starts a new operation
because the user clicked on some location that needs mounting.
In this way the application using the `PlacesSidebar` can track the
progress of the operation and, for example, show a notification.

Feature: `v3_20`

## `mount_operation`
the `gio::MountOperation` that is going to start.
<!-- impl PlacesSidebar::fn connect_open_location -->
The places sidebar emits this signal when the user selects a location
in it. The calling application should display the contents of that
location; for example, a file manager should show a list of files in
the specified location.
## `location`
`gio::File` to which the caller should switch.
## `open_flags`
a single value from `PlacesOpenFlags` specifying how the `location` should be opened.
<!-- impl PlacesSidebar::fn connect_populate_popup -->
The places sidebar emits this signal when the user invokes a contextual
popup on one of its items. In the signal handler, the application may
add extra items to the menu as appropriate. For example, a file manager
may want to add a "Properties" command to the menu.

It is not necessary to store the `selected_item` for each menu item;
during their callbacks, the application can use `PlacesSidebar::get_location`
to get the file to which the item refers.

The `selected_item` argument may be `None` in case the selection refers to
a volume. In this case, `selected_volume` will be non-`None`. In this case,
the calling application will have to `gobject::ObjectExt::ref` the `selected_volume` and
keep it around to use it in the callback.

The `container` and all its contents are destroyed after the user
dismisses the popup. The popup is re-created (and thus, this signal is
emitted) every time the user activates the contextual menu.

Before 3.18, the `container` always was a `Menu`, and you were expected
to add your items as ``GtkMenuItems``. Since 3.18, the popup may be implemented
as a `Popover`, in which case `container` will be something else, e.g. a
`Box`, to which you may add ``GtkModelButtons`` or other widgets, such as
``GtkEntries``, ``GtkSpinButtons``, etc. If your application can deal with this
situation, you can set `PlacesSidebar::populate-all` to `true` to request
that this signal is emitted for populating popovers as well.
## `container`
a `Menu` or another `Container`
## `selected_item`
`gio::File` with the item to which
 the popup should refer, or `None` in the case of a `selected_volume`.
## `selected_volume`
`gio::Volume` if the selected
 item is a volume, or `None` if it is a file.
<!-- impl PlacesSidebar::fn connect_show_connect_to_server -->
The places sidebar emits this signal when it needs the calling
application to present an way to connect directly to a network server.
For example, the application may bring up a dialog box asking for
a URL like "sftp://ftp.example.com". It is up to the application to create
the corresponding mount by using, for example, `gio::File::mount_enclosing_volume`.

# Deprecated since 3.18

use the `PlacesSidebar::show-other-locations` signal
 to connect to network servers.
<!-- impl PlacesSidebar::fn connect_show_enter_location -->
The places sidebar emits this signal when it needs the calling
application to present an way to directly enter a location.
For example, the application may bring up a dialog box asking for
a URL like "http://http.example.com".
<!-- impl PlacesSidebar::fn connect_show_error_message -->
The places sidebar emits this signal when it needs the calling
application to present an error message. Most of these messages
refer to mounting or unmounting media, for example, when a drive
cannot be started for some reason.
## `primary`
primary message with a summary of the error to show.
## `secondary`
secondary message with details of the error to show.
<!-- impl PlacesSidebar::fn connect_show_other_locations -->
The places sidebar emits this signal when it needs the calling
application to present a way to show other locations e.g. drives
and network access points.
For example, the application may bring up a page showing persistent
volumes and discovered network addresses.

Feature: `v3_18`


# Deprecated since 3.20

use the `PlacesSidebar::show-other-locations-with-flags`
which includes the open flags in order to allow the user to specify to open
in a new tab or window, in a similar way than `PlacesSidebar::open-location`
<!-- impl PlacesSidebar::fn connect_show_other_locations_with_flags -->
The places sidebar emits this signal when it needs the calling
application to present a way to show other locations e.g. drives
and network access points.
For example, the application may bring up a page showing persistent
volumes and discovered network addresses.

Feature: `v3_20`

## `open_flags`
a single value from `PlacesOpenFlags` specifying how it should be opened.
<!-- impl PlacesSidebar::fn connect_show_starred_location -->
The places sidebar emits this signal when it needs the calling
application to present a way to show the starred files. In GNOME,
starred files are implemented by setting the nao:predefined-tag-favorite
tag in the tracker database.

Feature: `v3_22_26`

## `open_flags`
a single value from `PlacesOpenFlags` specifying how the
 starred file should be opened.
<!-- impl PlacesSidebar::fn connect_unmount -->
The places sidebar emits this signal when it starts a new operation
because the user for example ejected some drive or unmounted a mount.
In this way the application using the `PlacesSidebar` can track the
progress of the operation and, for example, show a notification.

Feature: `v3_20`

## `mount_operation`
the `gio::MountOperation` that is going to start.
<!-- impl PlacesSidebar::fn get_property_populate_all -->
If :populate-all is `true`, the `PlacesSidebar::populate-popup` signal
is also emitted for popovers.

Feature: `v3_18`

<!-- impl PlacesSidebar::fn set_property_populate_all -->
If :populate-all is `true`, the `PlacesSidebar::populate-popup` signal
is also emitted for popovers.

Feature: `v3_18`

<!-- struct Plug -->
Together with `Socket`, `Plug` provides the ability to embed
widgets from one process into another process in a fashion that is
transparent to the user. One process creates a `Socket` widget
and passes the ID of that widget’s window to the other process,
which then creates a `Plug` with that window ID. Any widgets
contained in the `Plug` then will appear inside the first
application’s window.

The communication between a `Socket` and a `Plug` follows the
[XEmbed Protocol](http://www.freedesktop.org/Standards/xembed-spec).
This protocol has also been implemented in other toolkits, e.g. Qt,
allowing the same level of integration when embedding a Qt widget
in GTK+ or vice versa.

The `Plug` and `Socket` widgets are only available when GTK+
is compiled for the X11 platform and `GDK_WINDOWING_X11` is defined.
They can only be used on a ``GdkX11Display``. To use `Plug` and
`Socket`, you need to include the `gtk/gtkx.h` header.

# Implements

[`PlugExt`](trait.PlugExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait PlugExt -->
Trait containing all `Plug` methods.

# Implementors

[`Plug`](struct.Plug.html)
<!-- impl Plug::fn new -->
Creates a new plug widget inside the `Socket` identified
by `socket_id`. If `socket_id` is 0, the plug is left “unplugged” and
can later be plugged into a `Socket` by `GtkSocketExt::add_id`.
## `socket_id`
the window ID of the socket, or 0.

# Returns

the new `Plug` widget.
<!-- impl Plug::fn new_for_display -->
Create a new plug widget inside the `Socket` identified by socket_id.
## `display`
the `gdk::Display` on which `socket_id` is displayed
## `socket_id`
the XID of the socket’s window.

# Returns

the new `Plug` widget.
<!-- trait PlugExt::fn construct -->
Finish the initialization of `self` for a given `Socket` identified by
`socket_id`. This function will generally only be used by classes deriving from `Plug`.
## `socket_id`
the XID of the socket’s window.
<!-- trait PlugExt::fn construct_for_display -->
Finish the initialization of `self` for a given `Socket` identified by
`socket_id` which is currently displayed on `display`.
This function will generally only be used by classes deriving from `Plug`.
## `display`
the `gdk::Display` associated with `socket_id`’s
 `Socket`.
## `socket_id`
the XID of the socket’s window.
<!-- trait PlugExt::fn get_embedded -->
Determines whether the plug is embedded in a socket.

# Returns

`true` if the plug is embedded in a socket
<!-- trait PlugExt::fn get_id -->
Gets the window ID of a `Plug` widget, which can then
be used to embed this window inside another window, for
instance with `GtkSocketExt::add_id`.

# Returns

the window ID for the plug
<!-- trait PlugExt::fn get_socket_window -->
Retrieves the socket the plug is embedded in.

# Returns

the window of the socket, or `None`
<!-- trait PlugExt::fn connect_embedded -->
Gets emitted when the plug becomes embedded in a socket.
<!-- trait PlugExt::fn get_property_embedded -->
`true` if the plug is embedded in a socket.
<!-- trait PlugExt::fn get_property_socket_window -->
The window of the socket the plug is embedded in.
<!-- enum PolicyType -->
Determines how the size should be computed to achieve the one of the
visibility mode for the scrollbars.
<!-- enum PolicyType::variant Always -->
The scrollbar is always visible. The view size is
 independent of the content.
<!-- enum PolicyType::variant Automatic -->
The scrollbar will appear and disappear as necessary.
 For example, when all of a `TreeView` can not be seen.
<!-- enum PolicyType::variant Never -->
The scrollbar should never appear. In this mode the
 content determines the size.
<!-- enum PolicyType::variant External -->
Don't show a scrollbar, but don't force the
 size to follow the content. This can be used e.g. to make multiple
 scrolled windows share a scrollbar. Since: 3.16
<!-- struct Popover -->
`Popover` is a bubble-like context window, primarily meant to
provide context-dependent information or options. Popovers are
attached to a widget, passed at construction time on `Popover::new`,
or updated afterwards through `PopoverExt::set_relative_to`, by
default they will point to the whole widget area, although this
behavior can be changed through `PopoverExt::set_pointing_to`.

The position of a popover relative to the widget it is attached to
can also be changed through `PopoverExt::set_position`.

By default, `Popover` performs a GTK+ grab, in order to ensure
input events get redirected to it while it is shown, and also so
the popover is dismissed in the expected situations (clicks outside
the popover, or the Esc key being pressed). If no such modal behavior
is desired on a popover, `PopoverExt::set_modal` may be called on it
to tweak its behavior.

## `Popover` as menu replacement

`Popover` is often used to replace menus. To facilitate this, it
supports being populated from a `gio::MenuModel`, using
`Popover::new_from_model`. In addition to all the regular menu
model features, this function supports rendering sections in the
model in a more compact form, as a row of icon buttons instead of
menu items.

To use this rendering, set the ”display-hint” attribute of the
section to ”horizontal-buttons” and set the icons of your items
with the ”verb-icon” attribute.


```text
<section>
  <attribute name="display-hint">horizontal-buttons</attribute>
  <item>
    <attribute name="label">Cut</attribute>
    <attribute name="action">app.cut</attribute>
    <attribute name="verb-icon">edit-cut-symbolic</attribute>
  </item>
  <item>
    <attribute name="label">Copy</attribute>
    <attribute name="action">app.copy</attribute>
    <attribute name="verb-icon">edit-copy-symbolic</attribute>
  </item>
  <item>
    <attribute name="label">Paste</attribute>
    <attribute name="action">app.paste</attribute>
    <attribute name="verb-icon">edit-paste-symbolic</attribute>
  </item>
</section>
```

# CSS nodes

`Popover` has a single css node called popover. It always gets the
.background style class and it gets the .menu style class if it is
menu-like (e.g. `PopoverMenu` or created using `Popover::new_from_model`.

Particular uses of `Popover`, such as touch selection popups
or magnifiers in `Entry` or `TextView` get style classes
like .touch-selection or .magnifier to differentiate from
plain popovers.

# Implements

[`PopoverExt`](trait.PopoverExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait PopoverExt -->
Trait containing all `Popover` methods.

# Implementors

[`PopoverMenu`](struct.PopoverMenu.html), [`Popover`](struct.Popover.html)
<!-- impl Popover::fn new -->
Creates a new popover to point to `relative_to`
## `relative_to`
`Widget` the popover is related to

# Returns

a new `Popover`
<!-- impl Popover::fn new_from_model -->
Creates a `Popover` and populates it according to
`model`. The popover is pointed to the `relative_to` widget.

The created buttons are connected to actions found in the
`ApplicationWindow` to which the popover belongs - typically
by means of being attached to a widget that is contained within
the ``GtkApplicationWindows`` widget hierarchy.

Actions can also be added using `WidgetExt::insert_action_group`
on the menus attach widget or on any of its parent widgets.
## `relative_to`
`Widget` the popover is related to
## `model`
a `gio::MenuModel`

# Returns

the new `Popover`
<!-- trait PopoverExt::fn bind_model -->
Establishes a binding between a `Popover` and a `gio::MenuModel`.

The contents of `self` are removed and then refilled with menu items
according to `model`. When `model` changes, `self` is updated.
Calling this function twice on `self` with different `model` will
cause the first binding to be replaced with a binding to the new
model. If `model` is `None` then any previous binding is undone and
all children are removed.

If `action_namespace` is non-`None` then the effect is as if all
actions mentioned in the `model` have their names prefixed with the
namespace, plus a dot. For example, if the action “quit” is
mentioned and `action_namespace` is “app” then the effective action
name is “app.quit”.

This function uses `Actionable` to define the action name and
target values on the created menu items. If you want to use an
action group other than “app” and “win”, or if you want to use a
`MenuShell` outside of a `ApplicationWindow`, then you will need
to attach your own action group to the widget hierarchy using
`WidgetExt::insert_action_group`. As an example, if you created a
group with a “quit” action and inserted it with the name “mygroup”
then you would use the action name “mygroup.quit” in your
`gio::MenuModel`.
## `model`
the `gio::MenuModel` to bind to or `None` to remove
 binding
## `action_namespace`
the namespace for actions in `model`
<!-- trait PopoverExt::fn get_constrain_to -->
Returns the constraint for placing this popover.
See `PopoverExt::set_constrain_to`.

Feature: `v3_20`


# Returns

the constraint for placing this popover.
<!-- trait PopoverExt::fn get_default_widget -->
Gets the widget that should be set as the default while
the popover is shown.

Feature: `v3_18`


# Returns

the default widget,
or `None` if there is none
<!-- trait PopoverExt::fn get_modal -->
Returns whether the popover is modal, see gtk_popover_set_modal to
see the implications of this.

# Returns

`true` if `self` is modal
<!-- trait PopoverExt::fn get_pointing_to -->
If a rectangle to point to has been set, this function will
return `true` and fill in `rect` with such rectangle, otherwise
it will return `false` and fill in `rect` with the attached
widget coordinates.
## `rect`
location to store the rectangle

# Returns

`true` if a rectangle to point to was set.
<!-- trait PopoverExt::fn get_position -->
Returns the preferred position of `self`.

# Returns

The preferred position.
<!-- trait PopoverExt::fn get_relative_to -->
Returns the widget `self` is currently attached to

# Returns

a `Widget`
<!-- trait PopoverExt::fn get_transitions_enabled -->
Returns whether show/hide transitions are enabled on this popover.

Feature: `v3_16`


# Deprecated since 3.22

You can show or hide the popover without transitions
 using `WidgetExt::show` and `WidgetExt::hide` while `PopoverExt::popup`
 and `PopoverExt::popdown` will use transitions.

# Returns

`true` if the show and hide transitions of the given
 popover are enabled, `false` otherwise.
<!-- trait PopoverExt::fn popdown -->
Pops `self` down.This is different than a `WidgetExt::hide` call
in that it shows the popover with a transition. If you want to hide
the popover without a transition, use `WidgetExt::hide`.

Feature: `v3_22`

<!-- trait PopoverExt::fn popup -->
Pops `self` up. This is different than a `WidgetExt::show` call
in that it shows the popover with a transition. If you want to show
the popover without a transition, use `WidgetExt::show`.

Feature: `v3_22`

<!-- trait PopoverExt::fn set_constrain_to -->
Sets a constraint for positioning this popover.

Note that not all platforms support placing popovers freely,
and may already impose constraints.

Feature: `v3_20`

## `constraint`
the new constraint
<!-- trait PopoverExt::fn set_default_widget -->
Sets the widget that should be set as default widget while
the popover is shown (see `GtkWindowExt::set_default`). `Popover`
remembers the previous default widget and reestablishes it
when the popover is dismissed.

Feature: `v3_18`

## `widget`
the new default widget, or `None`
<!-- trait PopoverExt::fn set_modal -->
Sets whether `self` is modal, a modal popover will grab all input
within the toplevel and grab the keyboard focus on it when being
displayed. Clicking outside the popover area or pressing Esc will
dismiss the popover and ungrab input.
## `modal`
`true` to make popover claim all input within the toplevel
<!-- trait PopoverExt::fn set_pointing_to -->
Sets the rectangle that `self` will point to, in the
coordinate space of the widget `self` is attached to,
see `PopoverExt::set_relative_to`.
## `rect`
rectangle to point to
<!-- trait PopoverExt::fn set_position -->
Sets the preferred position for `self` to appear. If the `self`
is currently visible, it will be immediately updated.

This preference will be respected where possible, although
on lack of space (eg. if close to the window edges), the
`Popover` may choose to appear on the opposite side
## `position`
preferred popover position
<!-- trait PopoverExt::fn set_relative_to -->
Sets a new widget to be attached to `self`. If `self` is
visible, the position will be updated.

Note: the ownership of popovers is always given to their `relative_to`
widget, so if `relative_to` is set to `None` on an attached `self`, it
will be detached from its previous widget, and consequently destroyed
unless extra references are kept.
## `relative_to`
a `Widget`
<!-- trait PopoverExt::fn set_transitions_enabled -->
Sets whether show/hide transitions are enabled on this popover

Feature: `v3_16`


# Deprecated since 3.22

You can show or hide the popover without transitions
 using `WidgetExt::show` and `WidgetExt::hide` while `PopoverExt::popup`
 and `PopoverExt::popdown` will use transitions.
## `transitions_enabled`
Whether transitions are enabled
<!-- trait PopoverExt::fn connect_closed -->
This signal is emitted when the popover is dismissed either through
API or user interaction.
<!-- trait PopoverExt::fn get_property_constrain_to -->
Sets a constraint for the popover position.

Feature: `v3_20`

<!-- trait PopoverExt::fn set_property_constrain_to -->
Sets a constraint for the popover position.

Feature: `v3_20`

<!-- trait PopoverExt::fn get_property_modal -->
Sets whether the popover is modal (so other elements in the window do not
receive input while the popover is visible).
<!-- trait PopoverExt::fn set_property_modal -->
Sets whether the popover is modal (so other elements in the window do not
receive input while the popover is visible).
<!-- trait PopoverExt::fn get_property_pointing_to -->
Marks a specific rectangle to be pointed.
<!-- trait PopoverExt::fn set_property_pointing_to -->
Marks a specific rectangle to be pointed.
<!-- trait PopoverExt::fn get_property_position -->
Sets the preferred position of the popover.
<!-- trait PopoverExt::fn set_property_position -->
Sets the preferred position of the popover.
<!-- trait PopoverExt::fn get_property_relative_to -->
Sets the attached widget.
<!-- trait PopoverExt::fn set_property_relative_to -->
Sets the attached widget.
<!-- trait PopoverExt::fn get_property_transitions_enabled -->
Whether show/hide transitions are enabled for this popover.

Feature: `v3_16`


# Deprecated since 3.22

You can show or hide the popover without transitions
 using `WidgetExt::show` and `WidgetExt::hide` while `PopoverExt::popup`
 and `PopoverExt::popdown` will use transitions.
<!-- trait PopoverExt::fn set_property_transitions_enabled -->
Whether show/hide transitions are enabled for this popover.

Feature: `v3_16`


# Deprecated since 3.22

You can show or hide the popover without transitions
 using `WidgetExt::show` and `WidgetExt::hide` while `PopoverExt::popup`
 and `PopoverExt::popdown` will use transitions.
<!-- enum PopoverConstraint -->
Describes constraints to positioning of popovers. More values
may be added to this enumeration in the future.
<!-- enum PopoverConstraint::variant None -->
Don't constrain the popover position
 beyond what is imposed by the implementation
<!-- enum PopoverConstraint::variant Window -->
Constrain the popover to the boundaries
 of the window that it is attached to

Feature: `v3_20`

<!-- struct PopoverMenu -->
`PopoverMenu` is a subclass of `Popover` that treats its
children like menus and allows switching between them. It is
meant to be used primarily together with `ModelButton`, but
any widget can be used, such as `SpinButton` or `Scale`.
In this respect, `PopoverMenu` is more flexible than popovers
that are created from a `gio::MenuModel` with `Popover::new_from_model`.

To add a child as a submenu, set the `PopoverMenu:submenu`
child property to the name of the submenu. To let the user open
this submenu, add a `ModelButton` whose `ModelButton:menu-name`
property is set to the name you've given to the submenu.

By convention, the first child of a submenu should be a `ModelButton`
to switch back to the parent menu. Such a button should use the
`ModelButton:inverted` and `ModelButton:centered` properties
to achieve a title-like appearance and place the submenu indicator
at the opposite side. To switch back to the main menu, use "main"
as the menu name.

# Example


```text
<object class="GtkPopoverMenu">
  <child>
    <object class="GtkBox">
      <property name="visible">True</property>
      <property name="margin">10</property>
      <child>
        <object class="GtkModelButton">
          <property name="visible">True</property>
          <property name="action-name">win.frob</property>
          <property name="text" translatable="yes">Frob</property>
        </object>
      </child>
      <child>
        <object class="GtkModelButton">
          <property name="visible">True</property>
          <property name="menu-name">more</property>
          <property name="text" translatable="yes">More</property>
        </object>
      </child>
    </object>
  </child>
  <child>
    <object class="GtkBox">
      <property name="visible">True</property>
      <property name="margin">10</property>
      <child>
        <object class="GtkModelButton">
          <property name="visible">True</property>
          <property name="action-name">win.foo</property>
          <property name="text" translatable="yes">Foo</property>
        </object>
      </child>
      <child>
        <object class="GtkModelButton">
          <property name="visible">True</property>
          <property name="action-name">win.bar</property>
          <property name="text" translatable="yes">Bar</property>
        </object>
      </child>
    </object>
    <packing>
      <property name="submenu">more</property>
    </packing>
  </child>
</object>
```

Just like normal popovers created using gtk_popover_new_from_model,
`PopoverMenu` instances have a single css node called "popover"
and get the .menu style class.

Feature: `v3_16`

# Implements

[`PopoverMenuExt`](trait.PopoverMenuExt.html), [`PopoverExt`](trait.PopoverExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait PopoverMenuExt -->
Trait containing all `PopoverMenu` methods.

Feature: `v3_16`

# Implementors

[`PopoverMenu`](struct.PopoverMenu.html)
<!-- impl PopoverMenu::fn new -->
Creates a new popover menu.

Feature: `v3_16`


# Returns

a new `PopoverMenu`
<!-- trait PopoverMenuExt::fn open_submenu -->
Opens a submenu of the `self`. The `name`
must be one of the names given to the submenus
of `self` with `PopoverMenu:submenu`, or
"main" to switch back to the main menu.

`ModelButton` will open submenus automatically
when the `ModelButton:menu-name` property is set,
so this function is only needed when you are using
other kinds of widgets to initiate menu changes.

Feature: `v3_16`

## `name`
the name of the menu to switch to
<!-- enum PositionType -->
Describes which edge of a widget a certain feature is positioned at, e.g. the
tabs of a `Notebook`, the handle of a `HandleBox` or the label of a
`Scale`.
<!-- enum PositionType::variant Left -->
The feature is at the left edge.
<!-- enum PositionType::variant Right -->
The feature is at the right edge.
<!-- enum PositionType::variant Top -->
The feature is at the top edge.
<!-- enum PositionType::variant Bottom -->
The feature is at the bottom edge.
<!-- struct PrintContext -->
A `PrintContext` encapsulates context information that is required when
drawing pages for printing, such as the cairo context and important
parameters like page size and resolution. It also lets you easily
create `pango::Layout` and `pango::Context` objects that match the font metrics
of the cairo surface.

`PrintContext` objects gets passed to the `PrintOperation::begin-print`,
`PrintOperation::end-print`, `PrintOperation::request-page-setup` and
`PrintOperation::draw-page` signals on the `PrintOperation`.

## Using `PrintContext` in a `PrintOperation::draw-page` callback


```C
static void
draw_page (GtkPrintOperation *operation,
       GtkPrintContext   *context,
       int                page_nr)
{
  cairo_t *cr;
  PangoLayout *layout;
  PangoFontDescription *desc;

  cr = gtk_print_context_get_cairo_context (context);

  // Draw a red rectangle, as wide as the paper (inside the margins)
  cairo_set_source_rgb (cr, 1.0, 0, 0);
  cairo_rectangle (cr, 0, 0, gtk_print_context_get_width (context), 50);

  cairo_fill (cr);

  // Draw some lines
  cairo_move_to (cr, 20, 10);
  cairo_line_to (cr, 40, 20);
  cairo_arc (cr, 60, 60, 20, 0, M_PI);
  cairo_line_to (cr, 80, 20);

  cairo_set_source_rgb (cr, 0, 0, 0);
  cairo_set_line_width (cr, 5);
  cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND);
  cairo_set_line_join (cr, CAIRO_LINE_JOIN_ROUND);

  cairo_stroke (cr);

  // Draw some text
  layout = gtk_print_context_create_pango_layout (context);
  pango_layout_set_text (layout, "Hello World! Printing is easy", -1);
  desc = pango_font_description_from_string ("sans 28");
  pango_layout_set_font_description (layout, desc);
  pango_font_description_free (desc);

  cairo_move_to (cr, 30, 20);
  pango_cairo_layout_path (cr, layout);

  // Font Outline
  cairo_set_source_rgb (cr, 0.93, 1.0, 0.47);
  cairo_set_line_width (cr, 0.5);
  cairo_stroke_preserve (cr);

  // Font Fill
  cairo_set_source_rgb (cr, 0, 0.0, 1.0);
  cairo_fill (cr);

  g_object_unref (layout);
}
```

Printing support was added in GTK+ 2.10.

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl PrintContext::fn create_pango_context -->
Creates a new `pango::Context` that can be used with the
`PrintContext`.

# Returns

a new Pango context for `self`
<!-- impl PrintContext::fn create_pango_layout -->
Creates a new `pango::Layout` that is suitable for use
with the `PrintContext`.

# Returns

a new Pango layout for `self`
<!-- impl PrintContext::fn get_cairo_context -->
Obtains the cairo context that is associated with the
`PrintContext`.

# Returns

the cairo context of `self`
<!-- impl PrintContext::fn get_dpi_x -->
Obtains the horizontal resolution of the `PrintContext`,
in dots per inch.

# Returns

the horizontal resolution of `self`
<!-- impl PrintContext::fn get_dpi_y -->
Obtains the vertical resolution of the `PrintContext`,
in dots per inch.

# Returns

the vertical resolution of `self`
<!-- impl PrintContext::fn get_hard_margins -->
Obtains the hardware printer margins of the `PrintContext`, in units.
## `top`
top hardware printer margin
## `bottom`
bottom hardware printer margin
## `left`
left hardware printer margin
## `right`
right hardware printer margin

# Returns

`true` if the hard margins were retrieved
<!-- impl PrintContext::fn get_height -->
Obtains the height of the `PrintContext`, in pixels.

# Returns

the height of `self`
<!-- impl PrintContext::fn get_page_setup -->
Obtains the `PageSetup` that determines the page
dimensions of the `PrintContext`.

# Returns

the page setup of `self`
<!-- impl PrintContext::fn get_pango_fontmap -->
Returns a `pango::FontMap` that is suitable for use
with the `PrintContext`.

# Returns

the font map of `self`
<!-- impl PrintContext::fn get_width -->
Obtains the width of the `PrintContext`, in pixels.

# Returns

the width of `self`
<!-- impl PrintContext::fn set_cairo_context -->
Sets a new cairo context on a print context.

This function is intended to be used when implementing
an internal print preview, it is not needed for printing,
since GTK+ itself creates a suitable cairo context in that
case.
## `cr`
the cairo context
## `dpi_x`
the horizontal resolution to use with `cr`
## `dpi_y`
the vertical resolution to use with `cr`
<!-- enum PrintDuplex -->
See also `PrintSettings::set_duplex`.
<!-- enum PrintDuplex::variant Simplex -->
No duplex.
<!-- enum PrintDuplex::variant Horizontal -->
Horizontal duplex.
<!-- enum PrintDuplex::variant Vertical -->
Vertical duplex.
<!-- enum PrintError -->
Error codes that identify various errors that can occur while
using the GTK+ printing support.
<!-- enum PrintError::variant General -->
An unspecified error occurred.
<!-- enum PrintError::variant InternalError -->
An internal error occurred.
<!-- enum PrintError::variant Nomem -->
A memory allocation failed.
<!-- enum PrintError::variant InvalidFile -->
An error occurred while loading a page setup
 or paper size from a key file.
<!-- struct PrintOperation -->
`PrintOperation` is the high-level, portable printing API.
It looks a bit different than other GTK+ dialogs such as the
`FileChooser`, since some platforms don’t expose enough
infrastructure to implement a good print dialog. On such
platforms, `PrintOperation` uses the native print dialog.
On platforms which do not provide a native print dialog, GTK+
uses its own, see ``GtkPrintUnixDialog``.

The typical way to use the high-level printing API is to create
a `PrintOperation` object with `PrintOperation::new` when
the user selects to print. Then you set some properties on it,
e.g. the page size, any `PrintSettings` from previous print
operations, the number of pages, the current page, etc.

Then you start the print operation by calling `PrintOperationExt::run`.
It will then show a dialog, let the user select a printer and
options. When the user finished the dialog various signals will
be emitted on the `PrintOperation`, the main one being
`PrintOperation::draw-page`, which you are supposed to catch
and render the page on the provided `PrintContext` using Cairo.

# The high-level printing API


```C
static GtkPrintSettings *settings = NULL;

static void
do_print (void)
{
  GtkPrintOperation *print;
  GtkPrintOperationResult res;

  print = gtk_print_operation_new ();

  if (settings != NULL)
    gtk_print_operation_set_print_settings (print, settings);

  g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL);
  g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL);

  res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
                                 GTK_WINDOW (main_window), NULL);

  if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
    {
      if (settings != NULL)
        g_object_unref (settings);
      settings = g_object_ref (gtk_print_operation_get_print_settings (print));
    }

  g_object_unref (print);
}
```

By default `PrintOperation` uses an external application to do
print preview. To implement a custom print preview, an application
must connect to the preview signal. The functions
`PrintOperationPreview::render_page`,
`PrintOperationPreview::end_preview` and
`PrintOperationPreview::is_selected`
are useful when implementing a print preview.

# Implements

[`PrintOperationExt`](trait.PrintOperationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PrintOperationPreviewExt`](trait.PrintOperationPreviewExt.html)
<!-- trait PrintOperationExt -->
Trait containing all `PrintOperation` methods.

# Implementors

[`PrintOperation`](struct.PrintOperation.html)
<!-- impl PrintOperation::fn new -->
Creates a new `PrintOperation`.

# Returns

a new `PrintOperation`
<!-- trait PrintOperationExt::fn cancel -->
Cancels a running print operation. This function may
be called from a `PrintOperation::begin-print`,
`PrintOperation::paginate` or `PrintOperation::draw-page`
signal handler to stop the currently running print
operation.
<!-- trait PrintOperationExt::fn draw_page_finish -->
Signalize that drawing of particular page is complete.

It is called after completion of page drawing (e.g. drawing in another
thread).
If `PrintOperationExt::set_defer_drawing` was called before, then this function
has to be called by application. In another case it is called by the library
itself.
<!-- trait PrintOperationExt::fn get_default_page_setup -->
Returns the default page setup, see
`PrintOperationExt::set_default_page_setup`.

# Returns

the default page setup
<!-- trait PrintOperationExt::fn get_embed_page_setup -->
Gets the value of `PrintOperation:embed-page-setup` property.

# Returns

whether page setup selection combos are embedded
<!-- trait PrintOperationExt::fn get_error -->
Call this when the result of a print operation is
`PrintOperationResult::Error`, either as returned by
`PrintOperationExt::run`, or in the `PrintOperation::done` signal
handler. The returned `glib::Error` will contain more details on what went wrong.
<!-- trait PrintOperationExt::fn get_has_selection -->
Gets the value of `PrintOperation:has-selection` property.

# Returns

whether there is a selection
<!-- trait PrintOperationExt::fn get_n_pages_to_print -->
Returns the number of pages that will be printed.

Note that this value is set during print preparation phase
(`PrintStatus::Preparing`), so this function should never be
called before the data generation phase (`PrintStatus::GeneratingData`).
You can connect to the `PrintOperation::status-changed` signal
and call `PrintOperationExt::get_n_pages_to_print` when
print status is `PrintStatus::GeneratingData`.
This is typically used to track the progress of print operation.

# Returns

the number of pages that will be printed
<!-- trait PrintOperationExt::fn get_print_settings -->
Returns the current print settings.

Note that the return value is `None` until either
`PrintOperationExt::set_print_settings` or
`PrintOperationExt::run` have been called.

# Returns

the current print settings of `self`.
<!-- trait PrintOperationExt::fn get_status -->
Returns the status of the print operation.
Also see `PrintOperationExt::get_status_string`.

# Returns

the status of the print operation
<!-- trait PrintOperationExt::fn get_status_string -->
Returns a string representation of the status of the
print operation. The string is translated and suitable
for displaying the print status e.g. in a `Statusbar`.

Use `PrintOperationExt::get_status` to obtain a status
value that is suitable for programmatic use.

# Returns

a string representation of the status
 of the print operation
<!-- trait PrintOperationExt::fn get_support_selection -->
Gets the value of `PrintOperation:support-selection` property.

# Returns

whether the application supports print of selection
<!-- trait PrintOperationExt::fn is_finished -->
A convenience function to find out if the print operation
is finished, either successfully (`PrintStatus::Finished`)
or unsuccessfully (`PrintStatus::FinishedAborted`).

Note: when you enable print status tracking the print operation
can be in a non-finished state even after done has been called, as
the operation status then tracks the print job status on the printer.

# Returns

`true`, if the print operation is finished.
<!-- trait PrintOperationExt::fn run -->
Runs the print operation, by first letting the user modify
print settings in the print dialog, and then print the document.

Normally that this function does not return until the rendering of all
pages is complete. You can connect to the
`PrintOperation::status-changed` signal on `self` to obtain some
information about the progress of the print operation.
Furthermore, it may use a recursive mainloop to show the print dialog.

If you call `PrintOperationExt::set_allow_async` or set the
`PrintOperation:allow-async` property the operation will run
asynchronously if this is supported on the platform. The
`PrintOperation::done` signal will be emitted with the result of the
operation when the it is done (i.e. when the dialog is canceled, or when
the print succeeds or fails).

```C
if (settings != NULL)
  gtk_print_operation_set_print_settings (print, settings);
  
if (page_setup != NULL)
  gtk_print_operation_set_default_page_setup (print, page_setup);
  
g_signal_connect (print, "begin-print",
                  G_CALLBACK (begin_print), &data);
g_signal_connect (print, "draw-page",
                  G_CALLBACK (draw_page), &data);
 
res = gtk_print_operation_run (print,
                               GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
                               parent,
                               &error);
 
if (res == GTK_PRINT_OPERATION_RESULT_ERROR)
 {
   error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent),
                                   GTK_DIALOG_DESTROY_WITH_PARENT,
                         GTK_MESSAGE_ERROR,
                         GTK_BUTTONS_CLOSE,
                         "Error printing file:\n%s",
                         error->message);
   g_signal_connect (error_dialog, "response",
                     G_CALLBACK (gtk_widget_destroy), NULL);
   gtk_widget_show (error_dialog);
   g_error_free (error);
 }
else if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
 {
   if (settings != NULL)
g_object_unref (settings);
   settings = g_object_ref (gtk_print_operation_get_print_settings (print));
 }
```

Note that `PrintOperationExt::run` can only be called once on a
given `PrintOperation`.
## `action`
the action to start
## `parent`
Transient parent of the dialog

# Returns

the result of the print operation. A return value of
 `PrintOperationResult::Apply` indicates that the printing was
 completed successfully. In this case, it is a good idea to obtain
 the used print settings with `PrintOperationExt::get_print_settings`
 and store them for reuse with the next print operation. A value of
 `PrintOperationResult::InProgress` means the operation is running
 asynchronously, and will emit the `PrintOperation::done` signal when
 done.
<!-- trait PrintOperationExt::fn set_allow_async -->
Sets whether the `PrintOperationExt::run` may return
before the print operation is completed. Note that
some platforms may not allow asynchronous operation.
## `allow_async`
`true` to allow asynchronous operation
<!-- trait PrintOperationExt::fn set_current_page -->
Sets the current page.

If this is called before `PrintOperationExt::run`,
the user will be able to select to print only the current page.

Note that this only makes sense for pre-paginated documents.
## `current_page`
the current page, 0-based
<!-- trait PrintOperationExt::fn set_custom_tab_label -->
Sets the label for the tab holding custom widgets.
## `label`
the label to use, or `None` to use the default label
<!-- trait PrintOperationExt::fn set_default_page_setup -->
Makes `default_page_setup` the default page setup for `self`.

This page setup will be used by `PrintOperationExt::run`,
but it can be overridden on a per-page basis by connecting
to the `PrintOperation::request-page-setup` signal.
## `default_page_setup`
a `PageSetup`, or `None`
<!-- trait PrintOperationExt::fn set_defer_drawing -->
Sets up the `PrintOperation` to wait for calling of
`PrintOperationExt::draw_page_finish` from application. It can
be used for drawing page in another thread.

This function must be called in the callback of “draw-page” signal.
<!-- trait PrintOperationExt::fn set_embed_page_setup -->
Embed page size combo box and orientation combo box into page setup page.
Selected page setup is stored as default page setup in `PrintOperation`.
## `embed`
`true` to embed page setup selection in the ``GtkPrintUnixDialog``
<!-- trait PrintOperationExt::fn set_export_filename -->
Sets up the `PrintOperation` to generate a file instead
of showing the print dialog. The indended use of this function
is for implementing “Export to PDF” actions. Currently, PDF
is the only supported format.

“Print to PDF” support is independent of this and is done
by letting the user pick the “Print to PDF” item from the list
of printers in the print dialog.
## `filename`
the filename for the exported file
<!-- trait PrintOperationExt::fn set_has_selection -->
Sets whether there is a selection to print.

Application has to set number of pages to which the selection
will draw by `PrintOperationExt::set_n_pages` in a callback of
`PrintOperation::begin-print`.
## `has_selection`
`true` indicates that a selection exists
<!-- trait PrintOperationExt::fn set_job_name -->
Sets the name of the print job. The name is used to identify
the job (e.g. in monitoring applications like eggcups).

If you don’t set a job name, GTK+ picks a default one by
numbering successive print jobs.
## `job_name`
a string that identifies the print job
<!-- trait PrintOperationExt::fn set_n_pages -->
Sets the number of pages in the document.

This must be set to a positive number
before the rendering starts. It may be set in a
`PrintOperation::begin-print` signal hander.

Note that the page numbers passed to the
`PrintOperation::request-page-setup`
and `PrintOperation::draw-page` signals are 0-based, i.e. if
the user chooses to print all pages, the last ::draw-page signal
will be for page `n_pages` - 1.
## `n_pages`
the number of pages
<!-- trait PrintOperationExt::fn set_print_settings -->
Sets the print settings for `self`. This is typically used to
re-establish print settings from a previous print operation,
see `PrintOperationExt::run`.
## `print_settings`
`PrintSettings`
<!-- trait PrintOperationExt::fn set_show_progress -->
If `show_progress` is `true`, the print operation will show a
progress dialog during the print operation.
## `show_progress`
`true` to show a progress dialog
<!-- trait PrintOperationExt::fn set_support_selection -->
Sets whether selection is supported by `PrintOperation`.
## `support_selection`
`true` to support selection
<!-- trait PrintOperationExt::fn set_track_print_status -->
If track_status is `true`, the print operation will try to continue report
on the status of the print job in the printer queues and printer. This
can allow your application to show things like “out of paper” issues,
and when the print job actually reaches the printer.

This function is often implemented using some form of polling, so it should
not be enabled unless needed.
## `track_status`
`true` to track status after printing
<!-- trait PrintOperationExt::fn set_unit -->
Sets up the transformation for the cairo context obtained from
`PrintContext` in such a way that distances are measured in
units of `unit`.
## `unit`
the unit to use
<!-- trait PrintOperationExt::fn set_use_full_page -->
If `full_page` is `true`, the transformation for the cairo context
obtained from `PrintContext` puts the origin at the top left
corner of the page (which may not be the top left corner of the
sheet, depending on page orientation and the number of pages per
sheet). Otherwise, the origin is at the top left corner of the
imageable area (i.e. inside the margins).
## `full_page`
`true` to set up the `PrintContext` for the full page
<!-- trait PrintOperationExt::fn connect_begin_print -->
Emitted after the user has finished changing print settings
in the dialog, before the actual rendering starts.

A typical use for ::begin-print is to use the parameters from the
`PrintContext` and paginate the document accordingly, and then
set the number of pages with `PrintOperationExt::set_n_pages`.
## `context`
the `PrintContext` for the current operation
<!-- trait PrintOperationExt::fn connect_create_custom_widget -->
Emitted when displaying the print dialog. If you return a
widget in a handler for this signal it will be added to a custom
tab in the print dialog. You typically return a container widget
with multiple widgets in it.

The print dialog owns the returned widget, and its lifetime is not
controlled by the application. However, the widget is guaranteed
to stay around until the `PrintOperation::custom-widget-apply`
signal is emitted on the operation. Then you can read out any
information you need from the widgets.

# Returns

A custom widget that gets embedded in
 the print dialog, or `None`
<!-- trait PrintOperationExt::fn connect_custom_widget_apply -->
Emitted right before `PrintOperation::begin-print` if you added
a custom widget in the `PrintOperation::create-custom-widget` handler.
When you get this signal you should read the information from the
custom widgets, as the widgets are not guaraneed to be around at a
later time.
## `widget`
the custom widget added in create-custom-widget
<!-- trait PrintOperationExt::fn connect_done -->
Emitted when the print operation run has finished doing
everything required for printing.

`result` gives you information about what happened during the run.
If `result` is `PrintOperationResult::Error` then you can call
`PrintOperationExt::get_error` for more information.

If you enabled print status tracking then
`PrintOperationExt::is_finished` may still return `false`
after `PrintOperation::done` was emitted.
## `result`
the result of the print operation
<!-- trait PrintOperationExt::fn connect_draw_page -->
Emitted for every page that is printed. The signal handler
must render the `page_nr`'s page onto the cairo context obtained
from `context` using `PrintContext::get_cairo_context`.

```C
static void
draw_page (GtkPrintOperation *operation,
           GtkPrintContext   *context,
           gint               page_nr,
           gpointer           user_data)
{
  cairo_t *cr;
  PangoLayout *layout;
  gdouble width, text_height;
  gint layout_height;
  PangoFontDescription *desc;
  
  cr = gtk_print_context_get_cairo_context (context);
  width = gtk_print_context_get_width (context);
  
  cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT);
  
  cairo_set_source_rgb (cr, 0.8, 0.8, 0.8);
  cairo_fill (cr);
  
  layout = gtk_print_context_create_pango_layout (context);
  
  desc = pango_font_description_from_string ("sans 14");
  pango_layout_set_font_description (layout, desc);
  pango_font_description_free (desc);
  
  pango_layout_set_text (layout, "some text", -1);
  pango_layout_set_width (layout, width * PANGO_SCALE);
  pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER);
                   
  pango_layout_get_size (layout, NULL, &layout_height);
  text_height = (gdouble)layout_height / PANGO_SCALE;
  
  cairo_move_to (cr, width / 2,  (HEADER_HEIGHT - text_height) / 2);
  pango_cairo_show_layout (cr, layout);
  
  g_object_unref (layout);
}
```

Use `PrintOperationExt::set_use_full_page` and
`PrintOperationExt::set_unit` before starting the print operation
to set up the transformation of the cairo context according to your
needs.
## `context`
the `PrintContext` for the current operation
## `page_nr`
the number of the currently printed page (0-based)
<!-- trait PrintOperationExt::fn connect_end_print -->
Emitted after all pages have been rendered.
A handler for this signal can clean up any resources that have
been allocated in the `PrintOperation::begin-print` handler.
## `context`
the `PrintContext` for the current operation
<!-- trait PrintOperationExt::fn connect_paginate -->
Emitted after the `PrintOperation::begin-print` signal, but before
the actual rendering starts. It keeps getting emitted until a connected
signal handler returns `true`.

The ::paginate signal is intended to be used for paginating a document
in small chunks, to avoid blocking the user interface for a long
time. The signal handler should update the number of pages using
`PrintOperationExt::set_n_pages`, and return `true` if the document
has been completely paginated.

If you don't need to do pagination in chunks, you can simply do
it all in the ::begin-print handler, and set the number of pages
from there.
## `context`
the `PrintContext` for the current operation

# Returns

`true` if pagination is complete
<!-- trait PrintOperationExt::fn connect_preview -->
Gets emitted when a preview is requested from the native dialog.

The default handler for this signal uses an external viewer
application to preview.

To implement a custom print preview, an application must return
`true` from its handler for this signal. In order to use the
provided `context` for the preview implementation, it must be
given a suitable cairo context with `PrintContext::set_cairo_context`.

The custom preview implementation can use
`PrintOperationPreview::is_selected` and
`PrintOperationPreview::render_page` to find pages which
are selected for print and render them. The preview must be
finished by calling `PrintOperationPreview::end_preview`
(typically in response to the user clicking a close button).
## `preview`
the `PrintOperationPreview` for the current operation
## `context`
the `PrintContext` that will be used
## `parent`
the `Window` to use as window parent, or `None`

# Returns

`true` if the listener wants to take over control of the preview
<!-- trait PrintOperationExt::fn connect_request_page_setup -->
Emitted once for every page that is printed, to give
the application a chance to modify the page setup. Any changes
done to `setup` will be in force only for printing this page.
## `context`
the `PrintContext` for the current operation
## `page_nr`
the number of the currently printed page (0-based)
## `setup`
the `PageSetup`
<!-- trait PrintOperationExt::fn connect_status_changed -->
Emitted at between the various phases of the print operation.
See `PrintStatus` for the phases that are being discriminated.
Use `PrintOperationExt::get_status` to find out the current
status.
<!-- trait PrintOperationExt::fn connect_update_custom_widget -->
Emitted after change of selected printer. The actual page setup and
print settings are passed to the custom widget, which can actualize
itself according to this change.
## `widget`
the custom widget added in create-custom-widget
## `setup`
actual page setup
## `settings`
actual print settings
<!-- trait PrintOperationExt::fn get_property_allow_async -->
Determines whether the print operation may run asynchronously or not.

Some systems don't support asynchronous printing, but those that do
will return `PrintOperationResult::InProgress` as the status, and
emit the `PrintOperation::done` signal when the operation is actually
done.

The Windows port does not support asynchronous operation at all (this
is unlikely to change). On other platforms, all actions except for
`PrintOperationAction::Export` support asynchronous operation.
<!-- trait PrintOperationExt::fn set_property_allow_async -->
Determines whether the print operation may run asynchronously or not.

Some systems don't support asynchronous printing, but those that do
will return `PrintOperationResult::InProgress` as the status, and
emit the `PrintOperation::done` signal when the operation is actually
done.

The Windows port does not support asynchronous operation at all (this
is unlikely to change). On other platforms, all actions except for
`PrintOperationAction::Export` support asynchronous operation.
<!-- trait PrintOperationExt::fn get_property_current_page -->
The current page in the document.

If this is set before `PrintOperationExt::run`,
the user will be able to select to print only the current page.

Note that this only makes sense for pre-paginated documents.
<!-- trait PrintOperationExt::fn set_property_current_page -->
The current page in the document.

If this is set before `PrintOperationExt::run`,
the user will be able to select to print only the current page.

Note that this only makes sense for pre-paginated documents.
<!-- trait PrintOperationExt::fn get_property_custom_tab_label -->
Used as the label of the tab containing custom widgets.
Note that this property may be ignored on some platforms.

If this is `None`, GTK+ uses a default label.
<!-- trait PrintOperationExt::fn set_property_custom_tab_label -->
Used as the label of the tab containing custom widgets.
Note that this property may be ignored on some platforms.

If this is `None`, GTK+ uses a default label.
<!-- trait PrintOperationExt::fn get_property_default_page_setup -->
The `PageSetup` used by default.

This page setup will be used by `PrintOperationExt::run`,
but it can be overridden on a per-page basis by connecting
to the `PrintOperation::request-page-setup` signal.
<!-- trait PrintOperationExt::fn set_property_default_page_setup -->
The `PageSetup` used by default.

This page setup will be used by `PrintOperationExt::run`,
but it can be overridden on a per-page basis by connecting
to the `PrintOperation::request-page-setup` signal.
<!-- trait PrintOperationExt::fn get_property_embed_page_setup -->
If `true`, page size combo box and orientation combo box are embedded into page setup page.
<!-- trait PrintOperationExt::fn set_property_embed_page_setup -->
If `true`, page size combo box and orientation combo box are embedded into page setup page.
<!-- trait PrintOperationExt::fn get_property_export_filename -->
The name of a file to generate instead of showing the print dialog.
Currently, PDF is the only supported format.

The intended use of this property is for implementing
“Export to PDF” actions.

“Print to PDF” support is independent of this and is done
by letting the user pick the “Print to PDF” item from the
list of printers in the print dialog.
<!-- trait PrintOperationExt::fn set_property_export_filename -->
The name of a file to generate instead of showing the print dialog.
Currently, PDF is the only supported format.

The intended use of this property is for implementing
“Export to PDF” actions.

“Print to PDF” support is independent of this and is done
by letting the user pick the “Print to PDF” item from the
list of printers in the print dialog.
<!-- trait PrintOperationExt::fn get_property_has_selection -->
Determines whether there is a selection in your application.
This can allow your application to print the selection.
This is typically used to make a "Selection" button sensitive.
<!-- trait PrintOperationExt::fn set_property_has_selection -->
Determines whether there is a selection in your application.
This can allow your application to print the selection.
This is typically used to make a "Selection" button sensitive.
<!-- trait PrintOperationExt::fn get_property_job_name -->
A string used to identify the job (e.g. in monitoring
applications like eggcups).

If you don't set a job name, GTK+ picks a default one
by numbering successive print jobs.
<!-- trait PrintOperationExt::fn set_property_job_name -->
A string used to identify the job (e.g. in monitoring
applications like eggcups).

If you don't set a job name, GTK+ picks a default one
by numbering successive print jobs.
<!-- trait PrintOperationExt::fn get_property_n_pages -->
The number of pages in the document.

This must be set to a positive number
before the rendering starts. It may be set in a
`PrintOperation::begin-print` signal hander.

Note that the page numbers passed to the
`PrintOperation::request-page-setup` and
`PrintOperation::draw-page` signals are 0-based, i.e. if
the user chooses to print all pages, the last ::draw-page signal
will be for page `n_pages` - 1.
<!-- trait PrintOperationExt::fn set_property_n_pages -->
The number of pages in the document.

This must be set to a positive number
before the rendering starts. It may be set in a
`PrintOperation::begin-print` signal hander.

Note that the page numbers passed to the
`PrintOperation::request-page-setup` and
`PrintOperation::draw-page` signals are 0-based, i.e. if
the user chooses to print all pages, the last ::draw-page signal
will be for page `n_pages` - 1.
<!-- trait PrintOperationExt::fn get_property_n_pages_to_print -->
The number of pages that will be printed.

Note that this value is set during print preparation phase
(`PrintStatus::Preparing`), so this value should never be
get before the data generation phase (`PrintStatus::GeneratingData`).
You can connect to the `PrintOperation::status-changed` signal
and call `PrintOperationExt::get_n_pages_to_print` when
print status is `PrintStatus::GeneratingData`.
This is typically used to track the progress of print operation.
<!-- trait PrintOperationExt::fn get_property_print_settings -->
The `PrintSettings` used for initializing the dialog.

Setting this property is typically used to re-establish
print settings from a previous print operation, see
`PrintOperationExt::run`.
<!-- trait PrintOperationExt::fn set_property_print_settings -->
The `PrintSettings` used for initializing the dialog.

Setting this property is typically used to re-establish
print settings from a previous print operation, see
`PrintOperationExt::run`.
<!-- trait PrintOperationExt::fn get_property_show_progress -->
Determines whether to show a progress dialog during the
print operation.
<!-- trait PrintOperationExt::fn set_property_show_progress -->
Determines whether to show a progress dialog during the
print operation.
<!-- trait PrintOperationExt::fn get_property_status -->
The status of the print operation.
<!-- trait PrintOperationExt::fn get_property_status_string -->
A string representation of the status of the print operation.
The string is translated and suitable for displaying the print
status e.g. in a `Statusbar`.

See the `PrintOperation:status` property for a status value that
is suitable for programmatic use.
<!-- trait PrintOperationExt::fn get_property_support_selection -->
If `true`, the print operation will support print of selection.
This allows the print dialog to show a "Selection" button.
<!-- trait PrintOperationExt::fn set_property_support_selection -->
If `true`, the print operation will support print of selection.
This allows the print dialog to show a "Selection" button.
<!-- trait PrintOperationExt::fn get_property_track_print_status -->
If `true`, the print operation will try to continue report on
the status of the print job in the printer queues and printer.
This can allow your application to show things like “out of paper”
issues, and when the print job actually reaches the printer.
However, this is often implemented using polling, and should
not be enabled unless needed.
<!-- trait PrintOperationExt::fn set_property_track_print_status -->
If `true`, the print operation will try to continue report on
the status of the print job in the printer queues and printer.
This can allow your application to show things like “out of paper”
issues, and when the print job actually reaches the printer.
However, this is often implemented using polling, and should
not be enabled unless needed.
<!-- trait PrintOperationExt::fn get_property_unit -->
The transformation for the cairo context obtained from
`PrintContext` is set up in such a way that distances
are measured in units of `unit`.
<!-- trait PrintOperationExt::fn set_property_unit -->
The transformation for the cairo context obtained from
`PrintContext` is set up in such a way that distances
are measured in units of `unit`.
<!-- trait PrintOperationExt::fn get_property_use_full_page -->
If `true`, the transformation for the cairo context obtained
from `PrintContext` puts the origin at the top left corner
of the page (which may not be the top left corner of the sheet,
depending on page orientation and the number of pages per sheet).
Otherwise, the origin is at the top left corner of the imageable
area (i.e. inside the margins).
<!-- trait PrintOperationExt::fn set_property_use_full_page -->
If `true`, the transformation for the cairo context obtained
from `PrintContext` puts the origin at the top left corner
of the page (which may not be the top left corner of the sheet,
depending on page orientation and the number of pages per sheet).
Otherwise, the origin is at the top left corner of the imageable
area (i.e. inside the margins).
<!-- enum PrintOperationAction -->
The `action` parameter to `PrintOperationExt::run`
determines what action the print operation should perform.
<!-- enum PrintOperationAction::variant PrintDialog -->
Show the print dialog.
<!-- enum PrintOperationAction::variant Print -->
Start to print without showing
 the print dialog, based on the current print settings.
<!-- enum PrintOperationAction::variant Preview -->
Show the print preview.
<!-- enum PrintOperationAction::variant Export -->
Export to a file. This requires
 the export-filename property to be set.
<!-- struct PrintOperationPreview -->


# Implements

[`PrintOperationPreviewExt`](trait.PrintOperationPreviewExt.html)
<!-- trait PrintOperationPreviewExt -->
Trait containing all `PrintOperationPreview` methods.

# Implementors

[`PrintOperationPreview`](struct.PrintOperationPreview.html), [`PrintOperation`](struct.PrintOperation.html)
<!-- trait PrintOperationPreviewExt::fn end_preview -->
Ends a preview.

This function must be called to finish a custom print preview.
<!-- trait PrintOperationPreviewExt::fn is_selected -->
Returns whether the given page is included in the set of pages that
have been selected for printing.
## `page_nr`
a page number

# Returns

`true` if the page has been selected for printing
<!-- trait PrintOperationPreviewExt::fn render_page -->
Renders a page to the preview, using the print context that
was passed to the `PrintOperation::preview` handler together
with `self`.

A custom iprint preview should use this function in its ::expose
handler to render the currently selected page.

Note that this function requires a suitable cairo context to
be associated with the print context.
## `page_nr`
the page to render
<!-- trait PrintOperationPreviewExt::fn connect_got_page_size -->
The ::got-page-size signal is emitted once for each page
that gets rendered to the preview.

A handler for this signal should update the `context`
according to `page_setup` and set up a suitable cairo
context, using `PrintContext::set_cairo_context`.
## `context`
the current `PrintContext`
## `page_setup`
the `PageSetup` for the current page
<!-- trait PrintOperationPreviewExt::fn connect_ready -->
The ::ready signal gets emitted once per preview operation,
before the first page is rendered.

A handler for this signal can be used for setup tasks.
## `context`
the current `PrintContext`
<!-- enum PrintOperationResult -->
A value of this type is returned by `PrintOperationExt::run`.
<!-- enum PrintOperationResult::variant Error -->
An error has occurred.
<!-- enum PrintOperationResult::variant Apply -->
The print settings should be stored.
<!-- enum PrintOperationResult::variant Cancel -->
The print operation has been canceled,
 the print settings should not be stored.
<!-- enum PrintOperationResult::variant InProgress -->
The print operation is not complete
 yet. This value will only be returned when running asynchronously.
<!-- enum PrintPages -->
See also `gtk_print_job_set_pages`
<!-- enum PrintPages::variant All -->
All pages.
<!-- enum PrintPages::variant Current -->
Current page.
<!-- enum PrintPages::variant Ranges -->
Range of pages.
<!-- enum PrintPages::variant Selection -->
Selected pages.
<!-- enum PrintQuality -->
See also `PrintSettings::set_quality`.
<!-- enum PrintQuality::variant Low -->
Low quality.
<!-- enum PrintQuality::variant Normal -->
Normal quality.
<!-- enum PrintQuality::variant High -->
High quality.
<!-- enum PrintQuality::variant Draft -->
Draft quality.
<!-- struct PrintSettings -->
A `PrintSettings` object represents the settings of a print dialog in
a system-independent way. The main use for this object is that once
you’ve printed you can get a settings object that represents the settings
the user chose, and the next time you print you can pass that object in so
that the user doesn’t have to re-set all his settings.

Its also possible to enumerate the settings so that you can easily save
the settings for the next time your app runs, or even store them in a
document. The predefined keys try to use shared values as much as possible
so that moving such a document between systems still works.

Printing support was added in GTK+ 2.10.

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl PrintSettings::fn new -->
Creates a new `PrintSettings` object.

# Returns

a new `PrintSettings` object
<!-- impl PrintSettings::fn new_from_file -->
Reads the print settings from `file_name`. Returns a new `PrintSettings`
object with the restored settings, or `None` if an error occurred. If the
file could not be loaded then error is set to either a `glib::FileError` or
`glib::KeyFileError`. See `PrintSettings::to_file`.
## `file_name`
the filename to read the settings from

# Returns

the restored `PrintSettings`
<!-- impl PrintSettings::fn new_from_gvariant -->
Deserialize print settings from an a{sv} variant in
the format produced by `PrintSettings::to_gvariant`.

Feature: `v3_22`

## `variant`
an a{sv} `glib::Variant`

# Returns

a new `PrintSettings` object
<!-- impl PrintSettings::fn new_from_key_file -->
Reads the print settings from the group `group_name` in `key_file`. Returns a
new `PrintSettings` object with the restored settings, or `None` if an
error occurred. If the file could not be loaded then error is set to either
a `glib::FileError` or `glib::KeyFileError`.
## `key_file`
the `glib::KeyFile` to retrieve the settings from
## `group_name`
the name of the group to use, or `None` to use
 the default “Print Settings”

# Returns

the restored `PrintSettings`
<!-- impl PrintSettings::fn copy -->
Copies a `PrintSettings` object.

# Returns

a newly allocated copy of `self`
<!-- impl PrintSettings::fn foreach -->
Calls `func` for each key-value pair of `self`.
## `func`
the function to call
## `user_data`
user data for `func`
<!-- impl PrintSettings::fn get -->
Looks up the string value associated with `key`.
## `key`
a key

# Returns

the string value for `key`
<!-- impl PrintSettings::fn get_bool -->
Returns the boolean represented by the value
that is associated with `key`.

The string “true” represents `true`, any other
string `false`.
## `key`
a key

# Returns

`true`, if `key` maps to a true value.
<!-- impl PrintSettings::fn get_collate -->
Gets the value of `GTK_PRINT_SETTINGS_COLLATE`.

# Returns

whether to collate the printed pages
<!-- impl PrintSettings::fn get_default_source -->
Gets the value of `GTK_PRINT_SETTINGS_DEFAULT_SOURCE`.

# Returns

the default source
<!-- impl PrintSettings::fn get_dither -->
Gets the value of `GTK_PRINT_SETTINGS_DITHER`.

# Returns

the dithering that is used
<!-- impl PrintSettings::fn get_double -->
Returns the double value associated with `key`, or 0.
## `key`
a key

# Returns

the double value of `key`
<!-- impl PrintSettings::fn get_double_with_default -->
Returns the floating point number represented by
the value that is associated with `key`, or `default_val`
if the value does not represent a floating point number.

Floating point numbers are parsed with `g_ascii_strtod`.
## `key`
a key
## `def`
the default value

# Returns

the floating point number associated with `key`
<!-- impl PrintSettings::fn get_duplex -->
Gets the value of `GTK_PRINT_SETTINGS_DUPLEX`.

# Returns

whether to print the output in duplex.
<!-- impl PrintSettings::fn get_finishings -->
Gets the value of `GTK_PRINT_SETTINGS_FINISHINGS`.

# Returns

the finishings
<!-- impl PrintSettings::fn get_int -->
Returns the integer value of `key`, or 0.
## `key`
a key

# Returns

the integer value of `key`
<!-- impl PrintSettings::fn get_int_with_default -->
Returns the value of `key`, interpreted as
an integer, or the default value.
## `key`
a key
## `def`
the default value

# Returns

the integer value of `key`
<!-- impl PrintSettings::fn get_length -->
Returns the value associated with `key`, interpreted
as a length. The returned value is converted to `units`.
## `key`
a key
## `unit`
the unit of the return value

# Returns

the length value of `key`, converted to `unit`
<!-- impl PrintSettings::fn get_media_type -->
Gets the value of `GTK_PRINT_SETTINGS_MEDIA_TYPE`.

The set of media types is defined in PWG 5101.1-2002 PWG.

# Returns

the media type
<!-- impl PrintSettings::fn get_n_copies -->
Gets the value of `GTK_PRINT_SETTINGS_N_COPIES`.

# Returns

the number of copies to print
<!-- impl PrintSettings::fn get_number_up -->
Gets the value of `GTK_PRINT_SETTINGS_NUMBER_UP`.

# Returns

the number of pages per sheet
<!-- impl PrintSettings::fn get_number_up_layout -->
Gets the value of `GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT`.

# Returns

layout of page in number-up mode
<!-- impl PrintSettings::fn get_orientation -->
Get the value of `GTK_PRINT_SETTINGS_ORIENTATION`,
converted to a `PageOrientation`.

# Returns

the orientation
<!-- impl PrintSettings::fn get_output_bin -->
Gets the value of `GTK_PRINT_SETTINGS_OUTPUT_BIN`.

# Returns

the output bin
<!-- impl PrintSettings::fn get_page_ranges -->
Gets the value of `GTK_PRINT_SETTINGS_PAGE_RANGES`.
## `num_ranges`
return location for the length of the returned array

# Returns

an array
 of ``GtkPageRanges``. Use `g_free` to free the array when
 it is no longer needed.
<!-- impl PrintSettings::fn get_page_set -->
Gets the value of `GTK_PRINT_SETTINGS_PAGE_SET`.

# Returns

the set of pages to print
<!-- impl PrintSettings::fn get_paper_height -->
Gets the value of `GTK_PRINT_SETTINGS_PAPER_HEIGHT`,
converted to `unit`.
## `unit`
the unit for the return value

# Returns

the paper height, in units of `unit`
<!-- impl PrintSettings::fn get_paper_size -->
Gets the value of `GTK_PRINT_SETTINGS_PAPER_FORMAT`,
converted to a `PaperSize`.

# Returns

the paper size
<!-- impl PrintSettings::fn get_paper_width -->
Gets the value of `GTK_PRINT_SETTINGS_PAPER_WIDTH`,
converted to `unit`.
## `unit`
the unit for the return value

# Returns

the paper width, in units of `unit`
<!-- impl PrintSettings::fn get_print_pages -->
Gets the value of `GTK_PRINT_SETTINGS_PRINT_PAGES`.

# Returns

which pages to print
<!-- impl PrintSettings::fn get_printer -->
Convenience function to obtain the value of
`GTK_PRINT_SETTINGS_PRINTER`.

# Returns

the printer name
<!-- impl PrintSettings::fn get_printer_lpi -->
Gets the value of `GTK_PRINT_SETTINGS_PRINTER_LPI`.

# Returns

the resolution in lpi (lines per inch)
<!-- impl PrintSettings::fn get_quality -->
Gets the value of `GTK_PRINT_SETTINGS_QUALITY`.

# Returns

the print quality
<!-- impl PrintSettings::fn get_resolution -->
Gets the value of `GTK_PRINT_SETTINGS_RESOLUTION`.

# Returns

the resolution in dpi
<!-- impl PrintSettings::fn get_resolution_x -->
Gets the value of `GTK_PRINT_SETTINGS_RESOLUTION_X`.

# Returns

the horizontal resolution in dpi
<!-- impl PrintSettings::fn get_resolution_y -->
Gets the value of `GTK_PRINT_SETTINGS_RESOLUTION_Y`.

# Returns

the vertical resolution in dpi
<!-- impl PrintSettings::fn get_reverse -->
Gets the value of `GTK_PRINT_SETTINGS_REVERSE`.

# Returns

whether to reverse the order of the printed pages
<!-- impl PrintSettings::fn get_scale -->
Gets the value of `GTK_PRINT_SETTINGS_SCALE`.

# Returns

the scale in percent
<!-- impl PrintSettings::fn get_use_color -->
Gets the value of `GTK_PRINT_SETTINGS_USE_COLOR`.

# Returns

whether to use color
<!-- impl PrintSettings::fn has_key -->
Returns `true`, if a value is associated with `key`.
## `key`
a key

# Returns

`true`, if `key` has a value
<!-- impl PrintSettings::fn load_file -->
Reads the print settings from `file_name`. If the file could not be loaded
then error is set to either a `glib::FileError` or `glib::KeyFileError`.
See `PrintSettings::to_file`.
## `file_name`
the filename to read the settings from

# Returns

`true` on success
<!-- impl PrintSettings::fn load_key_file -->
Reads the print settings from the group `group_name` in `key_file`. If the
file could not be loaded then error is set to either a `glib::FileError` or
`glib::KeyFileError`.
## `key_file`
the `glib::KeyFile` to retrieve the settings from
## `group_name`
the name of the group to use, or `None` to use the default
 “Print Settings”

# Returns

`true` on success
<!-- impl PrintSettings::fn set -->
Associates `value` with `key`.
## `key`
a key
## `value`
a string value, or `None`
<!-- impl PrintSettings::fn set_bool -->
Sets `key` to a boolean value.
## `key`
a key
## `value`
a boolean
<!-- impl PrintSettings::fn set_collate -->
Sets the value of `GTK_PRINT_SETTINGS_COLLATE`.
## `collate`
whether to collate the output
<!-- impl PrintSettings::fn set_default_source -->
Sets the value of `GTK_PRINT_SETTINGS_DEFAULT_SOURCE`.
## `default_source`
the default source
<!-- impl PrintSettings::fn set_dither -->
Sets the value of `GTK_PRINT_SETTINGS_DITHER`.
## `dither`
the dithering that is used
<!-- impl PrintSettings::fn set_double -->
Sets `key` to a double value.
## `key`
a key
## `value`
a double value
<!-- impl PrintSettings::fn set_duplex -->
Sets the value of `GTK_PRINT_SETTINGS_DUPLEX`.
## `duplex`
a `PrintDuplex` value
<!-- impl PrintSettings::fn set_finishings -->
Sets the value of `GTK_PRINT_SETTINGS_FINISHINGS`.
## `finishings`
the finishings
<!-- impl PrintSettings::fn set_int -->
Sets `key` to an integer value.
## `key`
a key
## `value`
an integer
<!-- impl PrintSettings::fn set_length -->
Associates a length in units of `unit` with `key`.
## `key`
a key
## `value`
a length
## `unit`
the unit of `length`
<!-- impl PrintSettings::fn set_media_type -->
Sets the value of `GTK_PRINT_SETTINGS_MEDIA_TYPE`.

The set of media types is defined in PWG 5101.1-2002 PWG.
## `media_type`
the media type
<!-- impl PrintSettings::fn set_n_copies -->
Sets the value of `GTK_PRINT_SETTINGS_N_COPIES`.
## `num_copies`
the number of copies
<!-- impl PrintSettings::fn set_number_up -->
Sets the value of `GTK_PRINT_SETTINGS_NUMBER_UP`.
## `number_up`
the number of pages per sheet
<!-- impl PrintSettings::fn set_number_up_layout -->
Sets the value of `GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT`.
## `number_up_layout`
a `NumberUpLayout` value
<!-- impl PrintSettings::fn set_orientation -->
Sets the value of `GTK_PRINT_SETTINGS_ORIENTATION`.
## `orientation`
a page orientation
<!-- impl PrintSettings::fn set_output_bin -->
Sets the value of `GTK_PRINT_SETTINGS_OUTPUT_BIN`.
## `output_bin`
the output bin
<!-- impl PrintSettings::fn set_page_ranges -->
Sets the value of `GTK_PRINT_SETTINGS_PAGE_RANGES`.
## `page_ranges`
an array of ``GtkPageRanges``
## `num_ranges`
the length of `page_ranges`
<!-- impl PrintSettings::fn set_page_set -->
Sets the value of `GTK_PRINT_SETTINGS_PAGE_SET`.
## `page_set`
a `PageSet` value
<!-- impl PrintSettings::fn set_paper_height -->
Sets the value of `GTK_PRINT_SETTINGS_PAPER_HEIGHT`.
## `height`
the paper height
## `unit`
the units of `height`
<!-- impl PrintSettings::fn set_paper_size -->
Sets the value of `GTK_PRINT_SETTINGS_PAPER_FORMAT`,
`GTK_PRINT_SETTINGS_PAPER_WIDTH` and
`GTK_PRINT_SETTINGS_PAPER_HEIGHT`.
## `paper_size`
a paper size
<!-- impl PrintSettings::fn set_paper_width -->
Sets the value of `GTK_PRINT_SETTINGS_PAPER_WIDTH`.
## `width`
the paper width
## `unit`
the units of `width`
<!-- impl PrintSettings::fn set_print_pages -->
Sets the value of `GTK_PRINT_SETTINGS_PRINT_PAGES`.
## `pages`
a `PrintPages` value
<!-- impl PrintSettings::fn set_printer -->
Convenience function to set `GTK_PRINT_SETTINGS_PRINTER`
to `printer`.
## `printer`
the printer name
<!-- impl PrintSettings::fn set_printer_lpi -->
Sets the value of `GTK_PRINT_SETTINGS_PRINTER_LPI`.
## `lpi`
the resolution in lpi (lines per inch)
<!-- impl PrintSettings::fn set_quality -->
Sets the value of `GTK_PRINT_SETTINGS_QUALITY`.
## `quality`
a `PrintQuality` value
<!-- impl PrintSettings::fn set_resolution -->
Sets the values of `GTK_PRINT_SETTINGS_RESOLUTION`,
`GTK_PRINT_SETTINGS_RESOLUTION_X` and
`GTK_PRINT_SETTINGS_RESOLUTION_Y`.
## `resolution`
the resolution in dpi
<!-- impl PrintSettings::fn set_resolution_xy -->
Sets the values of `GTK_PRINT_SETTINGS_RESOLUTION`,
`GTK_PRINT_SETTINGS_RESOLUTION_X` and
`GTK_PRINT_SETTINGS_RESOLUTION_Y`.
## `resolution_x`
the horizontal resolution in dpi
## `resolution_y`
the vertical resolution in dpi
<!-- impl PrintSettings::fn set_reverse -->
Sets the value of `GTK_PRINT_SETTINGS_REVERSE`.
## `reverse`
whether to reverse the output
<!-- impl PrintSettings::fn set_scale -->
Sets the value of `GTK_PRINT_SETTINGS_SCALE`.
## `scale`
the scale in percent
<!-- impl PrintSettings::fn set_use_color -->
Sets the value of `GTK_PRINT_SETTINGS_USE_COLOR`.
## `use_color`
whether to use color
<!-- impl PrintSettings::fn to_file -->
This function saves the print settings from `self` to `file_name`. If the
file could not be loaded then error is set to either a `glib::FileError` or
`glib::KeyFileError`.
## `file_name`
the file to save to

# Returns

`true` on success
<!-- impl PrintSettings::fn to_gvariant -->
Serialize print settings to an a{sv} variant.

Feature: `v3_22`


# Returns

a new, floating, `glib::Variant`
<!-- impl PrintSettings::fn to_key_file -->
This function adds the print settings from `self` to `key_file`.
## `key_file`
the `glib::KeyFile` to save the print settings to
## `group_name`
the group to add the settings to in `key_file`, or
 `None` to use the default “Print Settings”
<!-- impl PrintSettings::fn unset -->
Removes any value associated with `key`.
This has the same effect as setting the value to `None`.
## `key`
a key
<!-- enum PrintStatus -->
The status gives a rough indication of the completion of a running
print operation.
<!-- enum PrintStatus::variant Initial -->
The printing has not started yet; this
 status is set initially, and while the print dialog is shown.
<!-- enum PrintStatus::variant Preparing -->
This status is set while the begin-print
 signal is emitted and during pagination.
<!-- enum PrintStatus::variant GeneratingData -->
This status is set while the
 pages are being rendered.
<!-- enum PrintStatus::variant SendingData -->
The print job is being sent off to the
 printer.
<!-- enum PrintStatus::variant Pending -->
The print job has been sent to the printer,
 but is not printed for some reason, e.g. the printer may be stopped.
<!-- enum PrintStatus::variant PendingIssue -->
Some problem has occurred during
 printing, e.g. a paper jam.
<!-- enum PrintStatus::variant Printing -->
The printer is processing the print job.
<!-- enum PrintStatus::variant Finished -->
The printing has been completed successfully.
<!-- enum PrintStatus::variant FinishedAborted -->
The printing has been aborted.
<!-- struct ProgressBar -->
The `ProgressBar` is typically used to display the progress of a long
running operation. It provides a visual clue that processing is underway.
The `ProgressBar` can be used in two different modes: percentage mode
and activity mode.

When an application can determine how much work needs to take place
(e.g. read a fixed number of bytes from a file) and can monitor its
progress, it can use the `ProgressBar` in percentage mode and the
user sees a growing bar indicating the percentage of the work that
has been completed. In this mode, the application is required to call
`ProgressBarExt::set_fraction` periodically to update the progress bar.

When an application has no accurate way of knowing the amount of work
to do, it can use the `ProgressBar` in activity mode, which shows
activity by a block moving back and forth within the progress area. In
this mode, the application is required to call `ProgressBarExt::pulse`
periodically to update the progress bar.

There is quite a bit of flexibility provided to control the appearance
of the `ProgressBar`. Functions are provided to control the orientation
of the bar, optional text can be displayed along with the bar, and the
step size used in activity mode can be set.

# CSS nodes


```plain
progressbar[.osd]
├── [text]
╰── trough[.empty][.full]
    ╰── progress[.pulse]
```

`ProgressBar` has a main CSS node with name progressbar and subnodes with
names text and trough, of which the latter has a subnode named progress. The
text subnode is only present if text is shown. The progress subnode has the
style class .pulse when in activity mode. It gets the style classes .left,
.right, .top or .bottom added when the progress 'touches' the corresponding
end of the `ProgressBar`. The .osd class on the progressbar node is for use
in overlays like the one Epiphany has for page loading progress.

# Implements

[`ProgressBarExt`](trait.ProgressBarExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ProgressBarExt -->
Trait containing all `ProgressBar` methods.

# Implementors

[`ProgressBar`](struct.ProgressBar.html)
<!-- impl ProgressBar::fn new -->
Creates a new `ProgressBar`.

# Returns

a `ProgressBar`.
<!-- trait ProgressBarExt::fn get_ellipsize -->
Returns the ellipsizing position of the progress bar.
See `ProgressBarExt::set_ellipsize`.

# Returns

`pango::EllipsizeMode`
<!-- trait ProgressBarExt::fn get_fraction -->
Returns the current fraction of the task that’s been completed.

# Returns

a fraction from 0.0 to 1.0
<!-- trait ProgressBarExt::fn get_inverted -->
Gets the value set by `ProgressBarExt::set_inverted`.

# Returns

`true` if the progress bar is inverted
<!-- trait ProgressBarExt::fn get_pulse_step -->
Retrieves the pulse step set with `ProgressBarExt::set_pulse_step`.

# Returns

a fraction from 0.0 to 1.0
<!-- trait ProgressBarExt::fn get_show_text -->
Gets the value of the `ProgressBar:show-text` property.
See `ProgressBarExt::set_show_text`.

# Returns

`true` if text is shown in the progress bar
<!-- trait ProgressBarExt::fn get_text -->
Retrieves the text that is displayed with the progress bar,
if any, otherwise `None`. The return value is a reference
to the text, not a copy of it, so will become invalid
if you change the text in the progress bar.

# Returns

text, or `None`; this string is owned by the widget
and should not be modified or freed.
<!-- trait ProgressBarExt::fn pulse -->
Indicates that some progress has been made, but you don’t know how much.
Causes the progress bar to enter “activity mode,” where a block
bounces back and forth. Each call to `ProgressBarExt::pulse`
causes the block to move by a little bit (the amount of movement
per pulse is determined by `ProgressBarExt::set_pulse_step`).
<!-- trait ProgressBarExt::fn set_ellipsize -->
Sets the mode used to ellipsize (add an ellipsis: "...") the
text if there is not enough space to render the entire string.
## `mode`
a `pango::EllipsizeMode`
<!-- trait ProgressBarExt::fn set_fraction -->
Causes the progress bar to “fill in” the given fraction
of the bar. The fraction should be between 0.0 and 1.0,
inclusive.
## `fraction`
fraction of the task that’s been completed
<!-- trait ProgressBarExt::fn set_inverted -->
Progress bars normally grow from top to bottom or left to right.
Inverted progress bars grow in the opposite direction.
## `inverted`
`true` to invert the progress bar
<!-- trait ProgressBarExt::fn set_pulse_step -->
Sets the fraction of total progress bar length to move the
bouncing block for each call to `ProgressBarExt::pulse`.
## `fraction`
fraction between 0.0 and 1.0
<!-- trait ProgressBarExt::fn set_show_text -->
Sets whether the progress bar will show text next to the bar.
The shown text is either the value of the `ProgressBar:text`
property or, if that is `None`, the `ProgressBar:fraction` value,
as a percentage.

To make a progress bar that is styled and sized suitably for containing
text (even if the actual text is blank), set `ProgressBar:show-text` to
`true` and `ProgressBar:text` to the empty string (not `None`).
## `show_text`
whether to show text
<!-- trait ProgressBarExt::fn set_text -->
Causes the given `text` to appear next to the progress bar.

If `text` is `None` and `ProgressBar:show-text` is `true`, the current
value of `ProgressBar:fraction` will be displayed as a percentage.

If `text` is non-`None` and `ProgressBar:show-text` is `true`, the text
will be displayed. In this case, it will not display the progress
percentage. If `text` is the empty string, the progress bar will still
be styled and sized suitably for containing text, as long as
`ProgressBar:show-text` is `true`.
## `text`
a UTF-8 string, or `None`
<!-- trait ProgressBarExt::fn get_property_ellipsize -->
The preferred place to ellipsize the string, if the progress bar does
not have enough room to display the entire string, specified as a
`pango::EllipsizeMode`.

Note that setting this property to a value other than
`pango::EllipsizeMode::None` has the side-effect that the progress bar requests
only enough space to display the ellipsis ("..."). Another means to set a
progress bar's width is `WidgetExt::set_size_request`.
<!-- trait ProgressBarExt::fn set_property_ellipsize -->
The preferred place to ellipsize the string, if the progress bar does
not have enough room to display the entire string, specified as a
`pango::EllipsizeMode`.

Note that setting this property to a value other than
`pango::EllipsizeMode::None` has the side-effect that the progress bar requests
only enough space to display the ellipsis ("..."). Another means to set a
progress bar's width is `WidgetExt::set_size_request`.
<!-- trait ProgressBarExt::fn get_property_show_text -->
Sets whether the progress bar will show a text in addition
to the bar itself. The shown text is either the value of
the `ProgressBar:text` property or, if that is `None`,
the `ProgressBar:fraction` value, as a percentage.

To make a progress bar that is styled and sized suitably for
showing text (even if the actual text is blank), set
`ProgressBar:show-text` to `true` and `ProgressBar:text`
to the empty string (not `None`).
<!-- trait ProgressBarExt::fn set_property_show_text -->
Sets whether the progress bar will show a text in addition
to the bar itself. The shown text is either the value of
the `ProgressBar:text` property or, if that is `None`,
the `ProgressBar:fraction` value, as a percentage.

To make a progress bar that is styled and sized suitably for
showing text (even if the actual text is blank), set
`ProgressBar:show-text` to `true` and `ProgressBar:text`
to the empty string (not `None`).
<!-- enum PropagationPhase -->
Describes the stage at which events are fed into a `EventController`.
<!-- enum PropagationPhase::variant None -->
Events are not delivered automatically. Those can be
 manually fed through `EventControllerExt::handle_event`. This should
 only be used when full control about when, or whether the controller
 handles the event is needed.
<!-- enum PropagationPhase::variant Capture -->
Events are delivered in the capture phase. The
 capture phase happens before the bubble phase, runs from the toplevel down
 to the event widget. This option should only be used on containers that
 might possibly handle events before their children do.
<!-- enum PropagationPhase::variant Bubble -->
Events are delivered in the bubble phase. The bubble
 phase happens after the capture phase, and before the default handlers
 are run. This phase runs from the event widget, up to the toplevel.
<!-- enum PropagationPhase::variant Target -->
Events are delivered in the default widget event handlers,
 note that widget implementations must chain up on button, motion, touch and
 grab broken handlers for controllers in this phase to be run.
<!-- struct RadioButton -->
A single radio button performs the same basic function as a `CheckButton`,
as its position in the object hierarchy reflects. It is only when multiple
radio buttons are grouped together that they become a different user
interface component in their own right.

Every radio button is a member of some group of radio buttons. When one is
selected, all other radio buttons in the same group are deselected. A
`RadioButton` is one way of giving the user a choice from many options.

Radio button widgets are created with `RadioButton::new`, passing `None`
as the argument if this is the first radio button in a group. In subsequent
calls, the group you wish to add this button to should be passed as an
argument. Optionally, `RadioButton::new_with_label` can be used if you
want a text label on the radio button.

Alternatively, when adding widgets to an existing group of radio buttons,
use `RadioButton::new_from_widget` with a `RadioButton` that already
has a group assigned to it. The convenience function
`RadioButton::new_with_label_from_widget` is also provided.

To retrieve the group a `RadioButton` is assigned to, use
`RadioButtonExt::get_group`.

To remove a `RadioButton` from one group and make it part of a new one,
use `RadioButton::set_group`.

The group list does not need to be freed, as each `RadioButton` will remove
itself and its list item when it is destroyed.

# CSS nodes


```plain
radiobutton
├── radio
╰── <child>
```

A `RadioButton` with indicator (see `ToggleButtonExt::set_mode`) has a
main CSS node with name radiobutton and a subnode with name radio.


```plain
button.radio
├── radio
╰── <child>
```

A `RadioButton` without indicator changes the name of its main node
to button and adds a .radio style class to it. The subnode is invisible
in this case.

## How to create a group of two radio buttons.


```C
void create_radio_buttons (void) {

   GtkWidget *window, *radio1, *radio2, *box, *entry;
   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
   box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 2);
   gtk_box_set_homogeneous (GTK_BOX (box), TRUE);

   // Create a radio button with a GtkEntry widget
   radio1 = gtk_radio_button_new (NULL);
   entry = gtk_entry_new ();
   gtk_container_add (GTK_CONTAINER (radio1), entry);


   // Create a radio button with a label
   radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radio1),
                                                         "I’m the second radio button.");

   // Pack them into a box, then show all the widgets
   gtk_box_pack_start (GTK_BOX (box), radio1);
   gtk_box_pack_start (GTK_BOX (box), radio2);
   gtk_container_add (GTK_CONTAINER (window), box);
   gtk_widget_show_all (window);
   return;
}
```

When an unselected button in the group is clicked the clicked button
receives the `ToggleButton::toggled` signal, as does the previously
selected button.
Inside the `ToggleButton::toggled` handler, `ToggleButtonExt::get_active`
can be used to determine if the button has been selected or deselected.

# Implements

[`RadioButtonExt`](trait.RadioButtonExt.html), [`CheckButtonExt`](trait.CheckButtonExt.html), [`ToggleButtonExt`](trait.ToggleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait RadioButtonExt -->
Trait containing all `RadioButton` methods.

# Implementors

[`RadioButton`](struct.RadioButton.html)
<!-- impl RadioButton::fn new -->
Creates a new `RadioButton`. To be of any practical value, a widget should
then be packed into the radio button.
## `group`
an existing
 radio button group, or `None` if you are creating a new group.

# Returns

a new radio button
<!-- impl RadioButton::fn new_from_widget -->
Creates a new `RadioButton`, adding it to the same group as
`radio_group_member`. As with `RadioButton::new`, a widget
should be packed into the radio button.
## `radio_group_member`
an existing `RadioButton`.

# Returns

a new radio button.
<!-- impl RadioButton::fn new_with_label -->
Creates a new `RadioButton` with a text label.
## `group`
an existing
 radio button group, or `None` if you are creating a new group.
## `label`
the text label to display next to the radio button.

# Returns

a new radio button.
<!-- impl RadioButton::fn new_with_label_from_widget -->
Creates a new `RadioButton` with a text label, adding it to
the same group as `radio_group_member`.
## `radio_group_member`
widget to get radio group from or `None`
## `label`
a text string to display next to the radio button.

# Returns

a new radio button.
<!-- impl RadioButton::fn new_with_mnemonic -->
Creates a new `RadioButton` containing a label, adding it to the same
group as `group`. The label will be created using
`Label::new_with_mnemonic`, so underscores in `label` indicate the
mnemonic for the button.
## `group`
the radio button
 group, or `None`
## `label`
the text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `RadioButton`
<!-- impl RadioButton::fn new_with_mnemonic_from_widget -->
Creates a new `RadioButton` containing a label. The label
will be created using `Label::new_with_mnemonic`, so underscores
in `label` indicate the mnemonic for the button.
## `radio_group_member`
widget to get radio group from or `None`
## `label`
the text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `RadioButton`
<!-- trait RadioButtonExt::fn get_group -->
Retrieves the group assigned to a radio button.

# Returns

a linked list
containing all the radio buttons in the same group
as `self`. The returned list is owned by the radio button
and must not be modified or freed.
<!-- trait RadioButtonExt::fn join_group -->
Joins a `RadioButton` object to the group of another `RadioButton` object

Use this in language bindings instead of the `RadioButtonExt::get_group`
and `RadioButton::set_group` methods

A common way to set up a group of radio buttons is the following:

```C
  GtkRadioButton *radio_button;
  GtkRadioButton *last_button;

  while (some_condition)
    {
       radio_button = gtk_radio_button_new (NULL);

       gtk_radio_button_join_group (radio_button, last_button);
       last_button = radio_button;
    }
```
## `group_source`
a radio button object whos group we are
 joining, or `None` to remove the radio button from its group
<!-- trait RadioButtonExt::fn set_group -->
Sets a `RadioButton`’s group. It should be noted that this does not change
the layout of your interface in any way, so if you are changing the group,
it is likely you will need to re-arrange the user interface to reflect these
changes.
## `group`
an existing radio
 button group, such as one returned from `RadioButtonExt::get_group`, or `None`.
<!-- trait RadioButtonExt::fn connect_group_changed -->
Emitted when the group of radio buttons that a radio button belongs
to changes. This is emitted when a radio button switches from
being alone to being part of a group of 2 or more buttons, or
vice-versa, and when a button is moved from one group of 2 or
more buttons to a different one, but not when the composition
of the group that a button belongs to changes.
<!-- trait RadioButtonExt::fn set_property_group -->
Sets a new group for a radio button.
<!-- struct RadioMenuItem -->
A radio menu item is a check menu item that belongs to a group. At each
instant exactly one of the radio menu items from a group is selected.

The group list does not need to be freed, as each `RadioMenuItem` will
remove itself and its list item when it is destroyed.

The correct way to create a group of radio menu items is approximatively
this:

## How to create a group of radio menu items.


```C
GSList *group = NULL;
GtkWidget *item;
gint i;

for (i = 0; i < 5; i++)
{
  item = gtk_radio_menu_item_new_with_label (group, "This is an example");
  group = gtk_radio_menu_item_get_group (GTK_RADIO_MENU_ITEM (item));
  if (i == 1)
    gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (item), TRUE);
}
```

# CSS nodes


```plain
menuitem
├── radio.left
╰── <child>
```

`RadioMenuItem` has a main CSS node with name menuitem, and a subnode
with name radio, which gets the .left or .right style class.

# Implements

[`RadioMenuItemExt`](trait.RadioMenuItemExt.html), [`CheckMenuItemExt`](trait.CheckMenuItemExt.html), [`GtkMenuItemExt`](trait.GtkMenuItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait RadioMenuItemExt -->
Trait containing all `RadioMenuItem` methods.

# Implementors

[`RadioMenuItem`](struct.RadioMenuItem.html)
<!-- impl RadioMenuItem::fn new -->
Creates a new `RadioMenuItem`.
## `group`
the group to which the
 radio menu item is to be attached, or `None`

# Returns

a new `RadioMenuItem`
<!-- impl RadioMenuItem::fn new_from_widget -->
Creates a new `RadioMenuItem` adding it to the same group as `group`.
## `group`
An existing `RadioMenuItem`

# Returns

The new `RadioMenuItem`
<!-- impl RadioMenuItem::fn new_with_label -->
Creates a new `RadioMenuItem` whose child is a simple `Label`.
## `group`

 group the radio menu item is inside, or `None`
## `label`
the text for the label

# Returns

A new `RadioMenuItem`
<!-- impl RadioMenuItem::fn new_with_label_from_widget -->
Creates a new `RadioMenuItem` whose child is a simple `Label`.
The new `RadioMenuItem` is added to the same group as `group`.
## `group`
an existing `RadioMenuItem`
## `label`
the text for the label

# Returns

The new `RadioMenuItem`
<!-- impl RadioMenuItem::fn new_with_mnemonic -->
Creates a new `RadioMenuItem` containing a label. The label
will be created using `Label::new_with_mnemonic`, so underscores
in `label` indicate the mnemonic for the menu item.
## `group`

 group the radio menu item is inside, or `None`
## `label`
the text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `RadioMenuItem`
<!-- impl RadioMenuItem::fn new_with_mnemonic_from_widget -->
Creates a new `RadioMenuItem` containing a label. The label will be
created using `Label::new_with_mnemonic`, so underscores in label
indicate the mnemonic for the menu item.

The new `RadioMenuItem` is added to the same group as `group`.
## `group`
An existing `RadioMenuItem`
## `label`
the text of the button, with an underscore in front of the
 mnemonic character

# Returns

The new `RadioMenuItem`
<!-- trait RadioMenuItemExt::fn get_group -->
Returns the group to which the radio menu item belongs, as a `glib::List` of
`RadioMenuItem`. The list belongs to GTK+ and should not be freed.

# Returns

the group
 of `self`
<!-- trait RadioMenuItemExt::fn join_group -->
Joins a `RadioMenuItem` object to the group of another `RadioMenuItem`
object.

This function should be used by language bindings to avoid the memory
manangement of the opaque `glib::SList` of `RadioMenuItemExt::get_group`
and `RadioMenuItem::set_group`.

A common way to set up a group of `RadioMenuItem` instances is:


```text
  GtkRadioMenuItem *last_item = NULL;

  while ( ...more items to add... )
    {
      GtkRadioMenuItem *radio_item;

      radio_item = gtk_radio_menu_item_new (...);

      gtk_radio_menu_item_join_group (radio_item, last_item);
      last_item = radio_item;
    }
```

Feature: `v3_18`

## `group_source`
a `RadioMenuItem` whose group we are
 joining, or `None` to remove the `self` from its current
 group
<!-- trait RadioMenuItemExt::fn set_group -->
Sets the group of a radio menu item, or changes it.
## `group`
the new group, or `None`.
<!-- trait RadioMenuItemExt::fn set_property_group -->
The radio menu item whose group this widget belongs to.
<!-- struct RadioToolButton -->
A `RadioToolButton` is a `ToolItem` that contains a radio button,
that is, a button that is part of a group of toggle buttons where only
one button can be active at a time.

Use `RadioToolButton::new` to create a new `RadioToolButton`. Use
`RadioToolButton::new_from_widget` to create a new `RadioToolButton`
that is part of the same group as an existing `RadioToolButton`.

# CSS nodes

`RadioToolButton` has a single CSS node with name toolbutton.

# Implements

[`RadioToolButtonExt`](trait.RadioToolButtonExt.html), [`ToggleToolButtonExt`](trait.ToggleToolButtonExt.html), [`ToolButtonExt`](trait.ToolButtonExt.html), [`ToolItemExt`](trait.ToolItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait RadioToolButtonExt -->
Trait containing all `RadioToolButton` methods.

# Implementors

[`RadioToolButton`](struct.RadioToolButton.html)
<!-- impl RadioToolButton::fn new -->
Creates a new `RadioToolButton`, adding it to `group`.
## `group`
An
 existing radio button group, or `None` if you are creating a new group

# Returns

The new `RadioToolButton`
<!-- impl RadioToolButton::fn new_from_widget -->
Creates a new `RadioToolButton` adding it to the same group as `gruup`
## `group`
An existing `RadioToolButton`, or `None`

# Returns

The new `RadioToolButton`
<!-- trait RadioToolButtonExt::fn get_group -->
Returns the radio button group `self` belongs to.

# Returns

The group `self` belongs to.
<!-- trait RadioToolButtonExt::fn set_group -->
Adds `self` to `group`, removing it from the group it belonged to before.
## `group`
an existing radio button group, or `None`
<!-- trait RadioToolButtonExt::fn set_property_group -->
Sets a new group for a radio tool button.
<!-- struct Range -->
`Range` is the common base class for widgets which visualize an
adjustment, e.g `Scale` or `Scrollbar`.

Apart from signals for monitoring the parameters of the adjustment,
`Range` provides properties and methods for influencing the sensitivity
of the “steppers”. It also provides properties and methods for setting a
“fill level” on range widgets. See `RangeExt::set_fill_level`.

# Implements

[`RangeExt`](trait.RangeExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait RangeExt -->
Trait containing all `Range` methods.

# Implementors

[`Range`](struct.Range.html), [`Scale`](struct.Scale.html), [`Scrollbar`](struct.Scrollbar.html)
<!-- trait RangeExt::fn get_adjustment -->
Get the `Adjustment` which is the “model” object for `Range`.
See `RangeExt::set_adjustment` for details.
The return value does not have a reference added, so should not
be unreferenced.

# Returns

a `Adjustment`
<!-- trait RangeExt::fn get_fill_level -->
Gets the current position of the fill level indicator.

# Returns

The current fill level
<!-- trait RangeExt::fn get_flippable -->
Gets the value set by `RangeExt::set_flippable`.

# Returns

`true` if the range is flippable
<!-- trait RangeExt::fn get_inverted -->
Gets the value set by `RangeExt::set_inverted`.

# Returns

`true` if the range is inverted
<!-- trait RangeExt::fn get_lower_stepper_sensitivity -->
Gets the sensitivity policy for the stepper that points to the
'lower' end of the `Range`’s adjustment.

# Returns

The lower stepper’s sensitivity policy.
<!-- trait RangeExt::fn get_min_slider_size -->
This function is useful mainly for `Range` subclasses.

See `RangeExt::set_min_slider_size`.

# Deprecated since 3.20

Use the min-height/min-width CSS properties on the slider
 node.

# Returns

The minimum size of the range’s slider.
<!-- trait RangeExt::fn get_range_rect -->
This function returns the area that contains the range’s trough
and its steppers, in widget->window coordinates.

This function is useful mainly for `Range` subclasses.
## `range_rect`
return location for the range rectangle
<!-- trait RangeExt::fn get_restrict_to_fill_level -->
Gets whether the range is restricted to the fill level.

# Returns

`true` if `self` is restricted to the fill level.
<!-- trait RangeExt::fn get_round_digits -->
Gets the number of digits to round the value to when
it changes. See `Range::change-value`.

# Returns

the number of digits to round to
<!-- trait RangeExt::fn get_show_fill_level -->
Gets whether the range displays the fill level graphically.

# Returns

`true` if `self` shows the fill level.
<!-- trait RangeExt::fn get_slider_range -->
This function returns sliders range along the long dimension,
in widget->window coordinates.

This function is useful mainly for `Range` subclasses.
## `slider_start`
return location for the slider's
 start, or `None`
## `slider_end`
return location for the slider's
 end, or `None`
<!-- trait RangeExt::fn get_slider_size_fixed -->
This function is useful mainly for `Range` subclasses.

See `RangeExt::set_slider_size_fixed`.

# Returns

whether the range’s slider has a fixed size.
<!-- trait RangeExt::fn get_upper_stepper_sensitivity -->
Gets the sensitivity policy for the stepper that points to the
'upper' end of the `Range`’s adjustment.

# Returns

The upper stepper’s sensitivity policy.
<!-- trait RangeExt::fn get_value -->
Gets the current value of the range.

# Returns

current value of the range.
<!-- trait RangeExt::fn set_adjustment -->
Sets the adjustment to be used as the “model” object for this range
widget. The adjustment indicates the current range value, the
minimum and maximum range values, the step/page increments used
for keybindings and scrolling, and the page size. The page size
is normally 0 for `Scale` and nonzero for `Scrollbar`, and
indicates the size of the visible area of the widget being scrolled.
The page size affects the size of the scrollbar slider.
## `adjustment`
a `Adjustment`
<!-- trait RangeExt::fn set_fill_level -->
Set the new position of the fill level indicator.

The “fill level” is probably best described by its most prominent
use case, which is an indicator for the amount of pre-buffering in
a streaming media player. In that use case, the value of the range
would indicate the current play position, and the fill level would
be the position up to which the file/stream has been downloaded.

This amount of prebuffering can be displayed on the range’s trough
and is themeable separately from the trough. To enable fill level
display, use `RangeExt::set_show_fill_level`. The range defaults
to not showing the fill level.

Additionally, it’s possible to restrict the range’s slider position
to values which are smaller than the fill level. This is controller
by `RangeExt::set_restrict_to_fill_level` and is by default
enabled.
## `fill_level`
the new position of the fill level indicator
<!-- trait RangeExt::fn set_flippable -->
If a range is flippable, it will switch its direction if it is
horizontal and its direction is `TextDirection::Rtl`.

See `WidgetExt::get_direction`.
## `flippable`
`true` to make the range flippable
<!-- trait RangeExt::fn set_increments -->
Sets the step and page sizes for the range.
The step size is used when the user clicks the `Scrollbar`
arrows or moves `Scale` via arrow keys. The page size
is used for example when moving via Page Up or Page Down keys.
## `step`
step size
## `page`
page size
<!-- trait RangeExt::fn set_inverted -->
Ranges normally move from lower to higher values as the
slider moves from top to bottom or left to right. Inverted
ranges have higher values at the top or on the right rather than
on the bottom or left.
## `setting`
`true` to invert the range
<!-- trait RangeExt::fn set_lower_stepper_sensitivity -->
Sets the sensitivity policy for the stepper that points to the
'lower' end of the `Range`’s adjustment.
## `sensitivity`
the lower stepper’s sensitivity policy.
<!-- trait RangeExt::fn set_min_slider_size -->
Sets the minimum size of the range’s slider.

This function is useful mainly for `Range` subclasses.

# Deprecated since 3.20

Use the min-height/min-width CSS properties on the slider
 node.
## `min_size`
The slider’s minimum size
<!-- trait RangeExt::fn set_range -->
Sets the allowable values in the `Range`, and clamps the range
value to be between `min` and `max`. (If the range has a non-zero
page size, it is clamped between `min` and `max` - page-size.)
## `min`
minimum range value
## `max`
maximum range value
<!-- trait RangeExt::fn set_restrict_to_fill_level -->
Sets whether the slider is restricted to the fill level. See
`RangeExt::set_fill_level` for a general description of the fill
level concept.
## `restrict_to_fill_level`
Whether the fill level restricts slider movement.
<!-- trait RangeExt::fn set_round_digits -->
Sets the number of digits to round the value to when
it changes. See `Range::change-value`.
## `round_digits`
the precision in digits, or -1
<!-- trait RangeExt::fn set_show_fill_level -->
Sets whether a graphical fill level is show on the trough. See
`RangeExt::set_fill_level` for a general description of the fill
level concept.
## `show_fill_level`
Whether a fill level indicator graphics is shown.
<!-- trait RangeExt::fn set_slider_size_fixed -->
Sets whether the range’s slider has a fixed size, or a size that
depends on its adjustment’s page size.

This function is useful mainly for `Range` subclasses.
## `size_fixed`
`true` to make the slider size constant
<!-- trait RangeExt::fn set_upper_stepper_sensitivity -->
Sets the sensitivity policy for the stepper that points to the
'upper' end of the `Range`’s adjustment.
## `sensitivity`
the upper stepper’s sensitivity policy.
<!-- trait RangeExt::fn set_value -->
Sets the current value of the range; if the value is outside the
minimum or maximum range values, it will be clamped to fit inside
them. The range emits the `Range::value-changed` signal if the
value changes.
## `value`
new value of the range
<!-- trait RangeExt::fn connect_adjust_bounds -->
Emitted before clamping a value, to give the application a
chance to adjust the bounds.
## `value`
the value before we clamp
<!-- trait RangeExt::fn connect_change_value -->
The `Range::change-value` signal is emitted when a scroll action is
performed on a range. It allows an application to determine the
type of scroll event that occurred and the resultant new value.
The application can handle the event itself and return `true` to
prevent further processing. Or, by returning `false`, it can pass
the event to other handlers until the default GTK+ handler is
reached.

The value parameter is unrounded. An application that overrides
the `Range`::change-value signal is responsible for clamping the
value to the desired number of decimal digits; the default GTK+
handler clamps the value based on `Range:round-digits`.
## `scroll`
the type of scroll action that was performed
## `value`
the new value resulting from the scroll action

# Returns

`true` to prevent other handlers from being invoked for
 the signal, `false` to propagate the signal further
<!-- trait RangeExt::fn connect_move_slider -->
Virtual function that moves the slider. Used for keybindings.
## `step`
how to move the slider
<!-- trait RangeExt::fn connect_value_changed -->
Emitted when the range value changes.
<!-- trait RangeExt::fn get_property_fill_level -->
The fill level (e.g. prebuffering of a network stream).
See `RangeExt::set_fill_level`.
<!-- trait RangeExt::fn set_property_fill_level -->
The fill level (e.g. prebuffering of a network stream).
See `RangeExt::set_fill_level`.
<!-- trait RangeExt::fn get_property_restrict_to_fill_level -->
The restrict-to-fill-level property controls whether slider
movement is restricted to an upper boundary set by the
fill level. See `RangeExt::set_restrict_to_fill_level`.
<!-- trait RangeExt::fn set_property_restrict_to_fill_level -->
The restrict-to-fill-level property controls whether slider
movement is restricted to an upper boundary set by the
fill level. See `RangeExt::set_restrict_to_fill_level`.
<!-- trait RangeExt::fn get_property_round_digits -->
The number of digits to round the value to when
it changes, or -1. See `Range::change-value`.
<!-- trait RangeExt::fn set_property_round_digits -->
The number of digits to round the value to when
it changes, or -1. See `Range::change-value`.
<!-- trait RangeExt::fn get_property_show_fill_level -->
The show-fill-level property controls whether fill level indicator
graphics are displayed on the trough. See
`RangeExt::set_show_fill_level`.
<!-- trait RangeExt::fn set_property_show_fill_level -->
The show-fill-level property controls whether fill level indicator
graphics are displayed on the trough. See
`RangeExt::set_show_fill_level`.
<!-- struct RecentChooser -->
`RecentChooser` is an interface that can be implemented by widgets
displaying the list of recently used files. In GTK+, the main objects
that implement this interface are `RecentChooserWidget`,
`RecentChooserDialog` and `RecentChooserMenu`.

Recently used files are supported since GTK+ 2.10.

# Implements

[`RecentChooserExt`](trait.RecentChooserExt.html)
<!-- trait RecentChooserExt -->
Trait containing all `RecentChooser` methods.

# Implementors

[`RecentChooserDialog`](struct.RecentChooserDialog.html), [`RecentChooserMenu`](struct.RecentChooserMenu.html), [`RecentChooserWidget`](struct.RecentChooserWidget.html), [`RecentChooser`](struct.RecentChooser.html)
<!-- trait RecentChooserExt::fn add_filter -->
Adds `filter` to the list of `RecentFilter` objects held by `self`.

If no previous filter objects were defined, this function will call
`RecentChooser::set_filter`.
## `filter`
a `RecentFilter`
<!-- trait RecentChooserExt::fn get_current_item -->
Gets the `RecentInfo` currently selected by `self`.

# Returns

a `RecentInfo`. Use `RecentInfo::unref` when
 when you have finished using it.
<!-- trait RecentChooserExt::fn get_current_uri -->
Gets the URI currently selected by `self`.

# Returns

a newly allocated string holding a URI.
<!-- trait RecentChooserExt::fn get_filter -->
Gets the `RecentFilter` object currently used by `self` to affect
the display of the recently used resources.

# Returns

a `RecentFilter` object.
<!-- trait RecentChooserExt::fn get_items -->
Gets the list of recently used resources in form of `RecentInfo` objects.

The return value of this function is affected by the “sort-type” and
“limit” properties of `self`.

# Returns

A newly allocated
 list of `RecentInfo` objects. You should
 use `RecentInfo::unref` on every item of the list, and then free
 the list itself using `glib::List::free`.
<!-- trait RecentChooserExt::fn get_limit -->
Gets the number of items returned by `RecentChooser::get_items`
and `RecentChooser::get_uris`.

# Returns

A positive integer, or -1 meaning that all items are
 returned.
<!-- trait RecentChooserExt::fn get_local_only -->
Gets whether only local resources should be shown in the recently used
resources selector. See `RecentChooser::set_local_only`

# Returns

`true` if only local resources should be shown.
<!-- trait RecentChooserExt::fn get_select_multiple -->
Gets whether `self` can select multiple items.

# Returns

`true` if `self` can select more than one item.
<!-- trait RecentChooserExt::fn get_show_icons -->
Retrieves whether `self` should show an icon near the resource.

# Returns

`true` if the icons should be displayed, `false` otherwise.
<!-- trait RecentChooserExt::fn get_show_not_found -->
Retrieves whether `self` should show the recently used resources that
were not found.

# Returns

`true` if the resources not found should be displayed, and
 `false` otheriwse.
<!-- trait RecentChooserExt::fn get_show_private -->
Returns whether `self` should display recently used resources
registered as private.

# Returns

`true` if the recent chooser should show private items,
 `false` otherwise.
<!-- trait RecentChooserExt::fn get_show_tips -->
Gets whether `self` should display tooltips containing the full path
of a recently user resource.

# Returns

`true` if the recent chooser should show tooltips,
 `false` otherwise.
<!-- trait RecentChooserExt::fn get_sort_type -->
Gets the value set by `RecentChooser::set_sort_type`.

# Returns

the sorting order of the `self`.
<!-- trait RecentChooserExt::fn get_uris -->
Gets the URI of the recently used resources.

The return value of this function is affected by the “sort-type” and “limit”
properties of `self`.

Since the returned array is `None` terminated, `length` may be `None`.
## `length`
return location for a the length of the
 URI list, or `None`

# Returns


 A newly allocated, `None`-terminated array of strings. Use
 `g_strfreev` to free it.
<!-- trait RecentChooserExt::fn list_filters -->
Gets the `RecentFilter` objects held by `self`.

# Returns

A singly linked list
 of `RecentFilter` objects. You
 should just free the returned list using `glib::SList::free`.
<!-- trait RecentChooserExt::fn remove_filter -->
Removes `filter` from the list of `RecentFilter` objects held by `self`.
## `filter`
a `RecentFilter`
<!-- trait RecentChooserExt::fn select_all -->
Selects all the items inside `self`, if the `self` supports
multiple selection.
<!-- trait RecentChooserExt::fn select_uri -->
Selects `uri` inside `self`.
## `uri`
a URI

# Returns

`true` if `uri` was found.
<!-- trait RecentChooserExt::fn set_current_uri -->
Sets `uri` as the current URI for `self`.
## `uri`
a URI

# Returns

`true` if the URI was found.
<!-- trait RecentChooserExt::fn set_filter -->
Sets `filter` as the current `RecentFilter` object used by `self`
to affect the displayed recently used resources.
## `filter`
a `RecentFilter`
<!-- trait RecentChooserExt::fn set_limit -->
Sets the number of items that should be returned by
`RecentChooser::get_items` and `RecentChooser::get_uris`.
## `limit`
a positive integer, or -1 for all items
<!-- trait RecentChooserExt::fn set_local_only -->
Sets whether only local resources, that is resources using the file:// URI
scheme, should be shown in the recently used resources selector. If
`local_only` is `true` (the default) then the shown resources are guaranteed
to be accessible through the operating system native file system.
## `local_only`
`true` if only local files can be shown
<!-- trait RecentChooserExt::fn set_select_multiple -->
Sets whether `self` can select multiple items.
## `select_multiple`
`true` if `self` can select more than one item
<!-- trait RecentChooserExt::fn set_show_icons -->
Sets whether `self` should show an icon near the resource when
displaying it.
## `show_icons`
whether to show an icon near the resource
<!-- trait RecentChooserExt::fn set_show_not_found -->
Sets whether `self` should display the recently used resources that
it didn’t find. This only applies to local resources.
## `show_not_found`
whether to show the local items we didn’t find
<!-- trait RecentChooserExt::fn set_show_private -->
Whether to show recently used resources marked registered as private.
## `show_private`
`true` to show private items, `false` otherwise
<!-- trait RecentChooserExt::fn set_show_tips -->
Sets whether to show a tooltips containing the full path of each
recently used resource in a `RecentChooser` widget.
## `show_tips`
`true` if tooltips should be shown
<!-- trait RecentChooserExt::fn set_sort_func -->
Sets the comparison function used when sorting to be `sort_func`. If
the `self` has the sort type set to `RecentSortType::Custom` then
the chooser will sort using this function.

To the comparison function will be passed two `RecentInfo` structs and
`sort_data`; `sort_func` should return a positive integer if the first
item comes before the second, zero if the two items are equal and
a negative integer if the first item comes after the second.
## `sort_func`
the comparison function
## `sort_data`
user data to pass to `sort_func`, or `None`
## `data_destroy`
destroy notifier for `sort_data`, or `None`
<!-- trait RecentChooserExt::fn set_sort_type -->
Changes the sorting order of the recently used resources list displayed by
`self`.
## `sort_type`
sort order that the chooser should use
<!-- trait RecentChooserExt::fn unselect_all -->
Unselects all the items inside `self`.
<!-- trait RecentChooserExt::fn unselect_uri -->
Unselects `uri` inside `self`.
## `uri`
a URI
<!-- trait RecentChooserExt::fn connect_item_activated -->
This signal is emitted when the user "activates" a recent item
in the recent chooser. This can happen by double-clicking on an item
in the recently used resources list, or by pressing
`Enter`.
<!-- trait RecentChooserExt::fn connect_selection_changed -->
This signal is emitted when there is a change in the set of
selected recently used resources. This can happen when a user
modifies the selection with the mouse or the keyboard, or when
explicitly calling functions to change the selection.
<!-- trait RecentChooserExt::fn get_property_filter -->
The `RecentFilter` object to be used when displaying
the recently used resources.
<!-- trait RecentChooserExt::fn set_property_filter -->
The `RecentFilter` object to be used when displaying
the recently used resources.
<!-- trait RecentChooserExt::fn get_property_limit -->
The maximum number of recently used resources to be displayed,
or -1 to display all items.
<!-- trait RecentChooserExt::fn set_property_limit -->
The maximum number of recently used resources to be displayed,
or -1 to display all items.
<!-- trait RecentChooserExt::fn get_property_local_only -->
Whether this `RecentChooser` should display only local (file:)
resources.
<!-- trait RecentChooserExt::fn set_property_local_only -->
Whether this `RecentChooser` should display only local (file:)
resources.
<!-- trait RecentChooserExt::fn set_property_recent_manager -->
The `RecentManager` instance used by the `RecentChooser` to
display the list of recently used resources.
<!-- trait RecentChooserExt::fn get_property_select_multiple -->
Allow the user to select multiple resources.
<!-- trait RecentChooserExt::fn set_property_select_multiple -->
Allow the user to select multiple resources.
<!-- trait RecentChooserExt::fn get_property_show_icons -->
Whether this `RecentChooser` should display an icon near the item.
<!-- trait RecentChooserExt::fn set_property_show_icons -->
Whether this `RecentChooser` should display an icon near the item.
<!-- trait RecentChooserExt::fn get_property_show_not_found -->
Whether this `RecentChooser` should display the recently used resources
even if not present anymore. Setting this to `false` will perform a
potentially expensive check on every local resource (every remote
resource will always be displayed).
<!-- trait RecentChooserExt::fn set_property_show_not_found -->
Whether this `RecentChooser` should display the recently used resources
even if not present anymore. Setting this to `false` will perform a
potentially expensive check on every local resource (every remote
resource will always be displayed).
<!-- trait RecentChooserExt::fn get_property_show_tips -->
Whether this `RecentChooser` should display a tooltip containing the
full path of the recently used resources.
<!-- trait RecentChooserExt::fn set_property_show_tips -->
Whether this `RecentChooser` should display a tooltip containing the
full path of the recently used resources.
<!-- trait RecentChooserExt::fn get_property_sort_type -->
Sorting order to be used when displaying the recently used resources.
<!-- trait RecentChooserExt::fn set_property_sort_type -->
Sorting order to be used when displaying the recently used resources.
<!-- struct RecentChooserDialog -->
`RecentChooserDialog` is a dialog box suitable for displaying the recently
used documents. This widgets works by putting a `RecentChooserWidget` inside
a `Dialog`. It exposes the `RecentChooserIface` interface, so you can use
all the `RecentChooser` functions on the recent chooser dialog as well as
those for `Dialog`.

Note that `RecentChooserDialog` does not have any methods of its own.
Instead, you should use the functions that work on a `RecentChooser`.

## Typical usage ## {`gtkrecentchooser`-typical-usage}

In the simplest of cases, you can use the following code to use
a `RecentChooserDialog` to select a recently used file:


```C
GtkWidget *dialog;
gint res;

dialog = gtk_recent_chooser_dialog_new ("Recent Documents",
                                        parent_window,
                                        _("_Cancel"),
                                        GTK_RESPONSE_CANCEL,
                                        _("_Open"),
                                        GTK_RESPONSE_ACCEPT,
                                        NULL);

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    GtkRecentInfo *info;
    GtkRecentChooser *chooser = GTK_RECENT_CHOOSER (dialog);

    info = gtk_recent_chooser_get_current_item (chooser);
    open_file (gtk_recent_info_get_uri (info));
    gtk_recent_info_unref (info);
  }

gtk_widget_destroy (dialog);
```

Recently used files are supported since GTK+ 2.10.

# Implements

[`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`RecentChooserExt`](trait.RecentChooserExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl RecentChooserDialog::fn new -->
Creates a new `RecentChooserDialog`. This function is analogous to
`Dialog::new_with_buttons`.
## `title`
Title of the dialog, or `None`
## `parent`
Transient parent of the dialog, or `None`,
## `first_button_text`
stock ID or text to go in the first button, or `None`

# Returns

a new `RecentChooserDialog`
<!-- impl RecentChooserDialog::fn new_for_manager -->
Creates a new `RecentChooserDialog` with a specified recent manager.

This is useful if you have implemented your own recent manager, or if you
have a customized instance of a `RecentManager` object.
## `title`
Title of the dialog, or `None`
## `parent`
Transient parent of the dialog, or `None`,
## `manager`
a `RecentManager`
## `first_button_text`
stock ID or text to go in the first button, or `None`

# Returns

a new `RecentChooserDialog`
<!-- enum RecentChooserError -->
These identify the various errors that can occur while calling
`RecentChooser` functions.
<!-- enum RecentChooserError::variant NotFound -->
Indicates that a file does not exist
<!-- enum RecentChooserError::variant InvalidUri -->
Indicates a malformed URI
<!-- struct RecentChooserMenu -->
`RecentChooserMenu` is a widget suitable for displaying recently used files
inside a menu. It can be used to set a sub-menu of a `MenuItem` using
`GtkMenuItemExt::set_submenu`, or as the menu of a `MenuToolButton`.

Note that `RecentChooserMenu` does not have any methods of its own. Instead,
you should use the functions that work on a `RecentChooser`.

Note also that `RecentChooserMenu` does not support multiple filters, as it
has no way to let the user choose between them as the `RecentChooserWidget`
and `RecentChooserDialog` widgets do. Thus using `RecentChooser::add_filter`
on a `RecentChooserMenu` widget will yield the same effects as using
`RecentChooser::set_filter`, replacing any currently set filter
with the supplied filter; `RecentChooser::remove_filter` will remove
any currently set `RecentFilter` object and will unset the current filter;
`RecentChooser::list_filters` will return a list containing a single
`RecentFilter` object.

Recently used files are supported since GTK+ 2.10.

# Implements

[`RecentChooserMenuExt`](trait.RecentChooserMenuExt.html), [`GtkMenuExt`](trait.GtkMenuExt.html), [`MenuShellExt`](trait.MenuShellExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`RecentChooserExt`](trait.RecentChooserExt.html), [`GtkMenuExtManual`](prelude/trait.GtkMenuExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait RecentChooserMenuExt -->
Trait containing all `RecentChooserMenu` methods.

# Implementors

[`RecentChooserMenu`](struct.RecentChooserMenu.html)
<!-- impl RecentChooserMenu::fn new -->
Creates a new `RecentChooserMenu` widget.

This kind of widget shows the list of recently used resources as
a menu, each item as a menu item. Each item inside the menu might
have an icon, representing its MIME type, and a number, for mnemonic
access.

This widget implements the `RecentChooser` interface.

This widget creates its own `RecentManager` object. See the
`RecentChooserMenu::new_for_manager` function to know how to create
a `RecentChooserMenu` widget bound to another `RecentManager` object.

# Returns

a new `RecentChooserMenu`
<!-- impl RecentChooserMenu::fn new_for_manager -->
Creates a new `RecentChooserMenu` widget using `manager` as
the underlying recently used resources manager.

This is useful if you have implemented your own recent manager,
or if you have a customized instance of a `RecentManager`
object or if you wish to share a common `RecentManager` object
among multiple `RecentChooser` widgets.
## `manager`
a `RecentManager`

# Returns

a new `RecentChooserMenu`, bound to `manager`.
<!-- trait RecentChooserMenuExt::fn get_show_numbers -->
Returns the value set by `RecentChooserMenuExt::set_show_numbers`.

# Returns

`true` if numbers should be shown.
<!-- trait RecentChooserMenuExt::fn set_show_numbers -->
Sets whether a number should be added to the items of `self`. The
numbers are shown to provide a unique character for a mnemonic to
be used inside ten menu item’s label. Only the first the items
get a number to avoid clashes.
## `show_numbers`
whether to show numbers
<!-- trait RecentChooserMenuExt::fn get_property_show_numbers -->
Whether the first ten items in the menu should be prepended by
a number acting as a unique mnemonic.
<!-- trait RecentChooserMenuExt::fn set_property_show_numbers -->
Whether the first ten items in the menu should be prepended by
a number acting as a unique mnemonic.
<!-- struct RecentChooserWidget -->
`RecentChooserWidget` is a widget suitable for selecting recently used
files. It is the main building block of a `RecentChooserDialog`. Most
applications will only need to use the latter; you can use
`RecentChooserWidget` as part of a larger window if you have special needs.

Note that `RecentChooserWidget` does not have any methods of its own.
Instead, you should use the functions that work on a `RecentChooser`.

Recently used files are supported since GTK+ 2.10.

# Implements

[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`RecentChooserExt`](trait.RecentChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl RecentChooserWidget::fn new -->
Creates a new `RecentChooserWidget` object. This is an embeddable widget
used to access the recently used resources list.

# Returns

a new `RecentChooserWidget`
<!-- impl RecentChooserWidget::fn new_for_manager -->
Creates a new `RecentChooserWidget` with a specified recent manager.

This is useful if you have implemented your own recent manager, or if you
have a customized instance of a `RecentManager` object.
## `manager`
a `RecentManager`

# Returns

a new `RecentChooserWidget`
<!-- struct RecentFilter -->
A `RecentFilter` can be used to restrict the files being shown
in a `RecentChooser`. Files can be filtered based on their name
(with `RecentFilter::add_pattern`), on their mime type (with
`FileFilter::add_mime_type`), on the application that has
registered them (with `RecentFilter::add_application`), or by
a custom filter function (with `RecentFilter::add_custom`).

Filtering by mime type handles aliasing and subclassing of mime
types; e.g. a filter for text/plain also matches a file with mime
type application/rtf, since application/rtf is a subclass of text/plain.
Note that `RecentFilter` allows wildcards for the subtype of a
mime type, so you can e.g. filter for image/\*.

Normally, filters are used by adding them to a `RecentChooser`,
see `RecentChooser::add_filter`, but it is also possible to
manually use a filter on a file with `RecentFilter::filter`.

Recently used files are supported since GTK+ 2.10.

## `RecentFilter` as `Buildable`

The `RecentFilter` implementation of the `Buildable` interface
supports adding rules using the `<mime-types>`, `<patterns>` and
`<applications>` elements and listing the rules within. Specifying
a `<mime-type>`, `<pattern>` or `<application>` has the same effect as
calling `RecentFilter::add_mime_type`,
`RecentFilter::add_pattern` or `RecentFilter::add_application`.

An example of a UI definition fragment specifying `RecentFilter` rules:

```text
<object class="GtkRecentFilter">
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/png</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
    <pattern>*.png</pattern>
  </patterns>
  <applications>
    <application>gimp</application>
    <application>gedit</application>
    <application>glade</application>
  </applications>
</object>
```

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl RecentFilter::fn new -->
Creates a new `RecentFilter` with no rules added to it.
Such filter does not accept any recently used resources, so is not
particularly useful until you add rules with
`RecentFilter::add_pattern`, `RecentFilter::add_mime_type`,
`RecentFilter::add_application`, `RecentFilter::add_age`.
To create a filter that accepts any recently used resource, use:

```C
GtkRecentFilter *filter = gtk_recent_filter_new ();
gtk_recent_filter_add_pattern (filter, "*");
```

# Returns

a new `RecentFilter`
<!-- impl RecentFilter::fn add_age -->
Adds a rule that allows resources based on their age - that is, the number
of days elapsed since they were last modified.
## `days`
number of days
<!-- impl RecentFilter::fn add_application -->
Adds a rule that allows resources based on the name of the application
that has registered them.
## `application`
an application name
<!-- impl RecentFilter::fn add_custom -->
Adds a rule to a filter that allows resources based on a custom callback
function. The bitfield `needed` which is passed in provides information
about what sorts of information that the filter function needs;
this allows GTK+ to avoid retrieving expensive information when
it isn’t needed by the filter.
## `needed`
bitfield of flags indicating the information that the custom
 filter function needs.
## `func`
callback function; if the function returns `true`, then
 the file will be displayed.
## `data`
data to pass to `func`
## `data_destroy`
function to call to free `data` when it is no longer needed.
<!-- impl RecentFilter::fn add_group -->
Adds a rule that allows resources based on the name of the group
to which they belong
## `group`
a group name
<!-- impl RecentFilter::fn add_mime_type -->
Adds a rule that allows resources based on their registered MIME type.
## `mime_type`
a MIME type
<!-- impl RecentFilter::fn add_pattern -->
Adds a rule that allows resources based on a pattern matching their
display name.
## `pattern`
a file pattern
<!-- impl RecentFilter::fn add_pixbuf_formats -->
Adds a rule allowing image files in the formats supported
by `gdk_pixbuf::Pixbuf`.
<!-- impl RecentFilter::fn filter -->
Tests whether a file should be displayed according to `self`.
The `RecentFilterInfo` `filter_info` should include
the fields returned from `RecentFilter::get_needed`, and
must set the `RecentFilterInfo.contains` field of `filter_info`
to indicate which fields have been set.

This function will not typically be used by applications; it
is intended principally for use in the implementation of
`RecentChooser`.
## `filter_info`
a `RecentFilterInfo` containing information
 about a recently used resource

# Returns

`true` if the file should be displayed
<!-- impl RecentFilter::fn get_name -->
Gets the human-readable name for the filter.
See `RecentFilter::set_name`.

# Returns

the name of the filter, or `None`. The returned string
 is owned by the filter object and should not be freed.
<!-- impl RecentFilter::fn get_needed -->
Gets the fields that need to be filled in for the `RecentFilterInfo`
passed to `RecentFilter::filter`

This function will not typically be used by applications; it
is intended principally for use in the implementation of
`RecentChooser`.

# Returns

bitfield of flags indicating needed fields when
 calling `RecentFilter::filter`
<!-- impl RecentFilter::fn set_name -->
Sets the human-readable name of the filter; this is the string
that will be displayed in the recently used resources selector
user interface if there is a selectable list of filters.
## `name`
then human readable name of `self`
<!-- struct RecentFilterFlags -->
These flags indicate what parts of a `RecentFilterInfo` struct
are filled or need to be filled.
<!-- struct RecentFilterFlags::const URI -->
the URI of the file being tested
<!-- struct RecentFilterFlags::const DISPLAY_NAME -->
the string that will be used to
 display the file in the recent chooser
<!-- struct RecentFilterFlags::const MIME_TYPE -->
the mime type of the file
<!-- struct RecentFilterFlags::const APPLICATION -->
the list of applications that have
 registered the file
<!-- struct RecentFilterFlags::const GROUP -->
the groups to which the file belongs to
<!-- struct RecentFilterFlags::const AGE -->
the number of days elapsed since the file
 has been registered
<!-- struct RecentInfo -->
`RecentInfo`-struct contains private data only, and should
be accessed using the provided API.

`RecentInfo` constains all the meta-data
associated with an entry in the recently used files list.
<!-- impl RecentInfo::fn create_app_info -->
Creates a `gio::AppInfo` for the specified `RecentInfo`
## `app_name`
the name of the application that should
 be mapped to a `gio::AppInfo`; if `None` is used then the default
 application for the MIME type is used

# Returns

the newly created `gio::AppInfo`, or `None`.
 In case of error, `error` will be set either with a
 `GTK_RECENT_MANAGER_ERROR` or a `G_IO_ERROR`
<!-- impl RecentInfo::fn exists -->
Checks whether the resource pointed by `self` still exists.
At the moment this check is done only on resources pointing
to local files.

# Returns

`true` if the resource exists
<!-- impl RecentInfo::fn get_added -->
Gets the timestamp (seconds from system’s Epoch) when the resource
was added to the recently used resources list.

# Returns

the number of seconds elapsed from system’s Epoch when
 the resource was added to the list, or -1 on failure.
<!-- impl RecentInfo::fn get_age -->
Gets the number of days elapsed since the last update
of the resource pointed by `self`.

# Returns

a positive integer containing the number of days
 elapsed since the time this resource was last modified
<!-- impl RecentInfo::fn get_application_info -->
Gets the data regarding the application that has registered the resource
pointed by `self`.

If the command line contains any escape characters defined inside the
storage specification, they will be expanded.
## `app_name`
the name of the application that has registered this item
## `app_exec`
return location for the string containing
 the command line
## `count`
return location for the number of times this item was registered
## `time_`
return location for the timestamp this item was last registered
 for this application

# Returns

`true` if an application with `app_name` has registered this
 resource inside the recently used list, or `false` otherwise. The
 `app_exec` string is owned by the `RecentInfo` and should not be
 modified or freed
<!-- impl RecentInfo::fn get_applications -->
Retrieves the list of applications that have registered this resource.
## `length`
return location for the length of the returned list

# Returns


 a newly allocated `None`-terminated array of strings.
 Use `g_strfreev` to free it.
<!-- impl RecentInfo::fn get_description -->
Gets the (short) description of the resource.

# Returns

the description of the resource. The returned string
 is owned by the recent manager, and should not be freed.
<!-- impl RecentInfo::fn get_display_name -->
Gets the name of the resource. If none has been defined, the basename
of the resource is obtained.

# Returns

the display name of the resource. The returned string
 is owned by the recent manager, and should not be freed.
<!-- impl RecentInfo::fn get_gicon -->
Retrieves the icon associated to the resource MIME type.

# Returns

a `gio::Icon` containing the icon, or `None`.
 Use `gobject::ObjectExt::unref` when finished using the icon
<!-- impl RecentInfo::fn get_groups -->
Returns all groups registered for the recently used item `self`.
The array of returned group names will be `None` terminated, so
length might optionally be `None`.
## `length`
return location for the number of groups returned

# Returns


 a newly allocated `None` terminated array of strings.
 Use `g_strfreev` to free it.
<!-- impl RecentInfo::fn get_icon -->
Retrieves the icon of size `size` associated to the resource MIME type.
## `size`
the size of the icon in pixels

# Returns

a `gdk_pixbuf::Pixbuf` containing the icon,
 or `None`. Use `gobject::ObjectExt::unref` when finished using the icon.
<!-- impl RecentInfo::fn get_mime_type -->
Gets the MIME type of the resource.

# Returns

the MIME type of the resource. The returned string
 is owned by the recent manager, and should not be freed.
<!-- impl RecentInfo::fn get_modified -->
Gets the timestamp (seconds from system’s Epoch) when the meta-data
for the resource was last modified.

# Returns

the number of seconds elapsed from system’s Epoch when
 the resource was last modified, or -1 on failure.
<!-- impl RecentInfo::fn get_private_hint -->
Gets the value of the “private” flag. Resources in the recently used
list that have this flag set to `true` should only be displayed by the
applications that have registered them.

# Returns

`true` if the private flag was found, `false` otherwise
<!-- impl RecentInfo::fn get_short_name -->
Computes a valid UTF-8 string that can be used as the
name of the item in a menu or list. For example, calling
this function on an item that refers to
“file:///foo/bar.txt” will yield “bar.txt”.

# Returns

A newly-allocated string in UTF-8 encoding
 free it with `g_free`
<!-- impl RecentInfo::fn get_uri -->
Gets the URI of the resource.

# Returns

the URI of the resource. The returned string is
 owned by the recent manager, and should not be freed.
<!-- impl RecentInfo::fn get_uri_display -->
Gets a displayable version of the resource’s URI. If the resource
is local, it returns a local path; if the resource is not local,
it returns the UTF-8 encoded content of `RecentInfo::get_uri`.

# Returns

a newly allocated UTF-8 string containing the
 resource’s URI or `None`. Use `g_free` when done using it.
<!-- impl RecentInfo::fn get_visited -->
Gets the timestamp (seconds from system’s Epoch) when the meta-data
for the resource was last visited.

# Returns

the number of seconds elapsed from system’s Epoch when
 the resource was last visited, or -1 on failure.
<!-- impl RecentInfo::fn has_application -->
Checks whether an application registered this resource using `app_name`.
## `app_name`
a string containing an application name

# Returns

`true` if an application with name `app_name` was found,
 `false` otherwise
<!-- impl RecentInfo::fn has_group -->
Checks whether `group_name` appears inside the groups
registered for the recently used item `self`.
## `group_name`
name of a group

# Returns

`true` if the group was found
<!-- impl RecentInfo::fn is_local -->
Checks whether the resource is local or not by looking at the
scheme of its URI.

# Returns

`true` if the resource is local
<!-- impl RecentInfo::fn last_application -->
Gets the name of the last application that have registered the
recently used resource represented by `self`.

# Returns

an application name. Use `g_free` to free it.
<!-- impl RecentInfo::fn match -->
Checks whether two `RecentInfo`-struct point to the same
resource.
## `info_b`
a `RecentInfo`

# Returns

`true` if both `RecentInfo`-struct point to the same
 resource, `false` otherwise
<!-- impl RecentInfo::fn ref -->
Increases the reference count of `recent_info` by one.

# Returns

the recent info object with its reference count
 increased by one
<!-- impl RecentInfo::fn unref -->
Decreases the reference count of `self` by one. If the reference
count reaches zero, `self` is deallocated, and the memory freed.
<!-- struct RecentManager -->
`RecentManager` provides a facility for adding, removing and
looking up recently used files. Each recently used file is
identified by its URI, and has meta-data associated to it, like
the names and command lines of the applications that have
registered it, the number of time each application has registered
the same file, the mime type of the file and whether the file
should be displayed only by the applications that have
registered it.

The recently used files list is per user.

The `RecentManager` acts like a database of all the recently
used files. You can create new `RecentManager` objects, but
it is more efficient to use the default manager created by GTK+.

Adding a new recently used file is as simple as:


```C
GtkRecentManager *manager;

manager = gtk_recent_manager_get_default ();
gtk_recent_manager_add_item (manager, file_uri);
```

The `RecentManager` will try to gather all the needed information
from the file itself through GIO.

Looking up the meta-data associated with a recently used file
given its URI requires calling `RecentManagerExt::lookup_item`:


```C
GtkRecentManager *manager;
GtkRecentInfo *info;
GError *error = NULL;

manager = gtk_recent_manager_get_default ();
info = gtk_recent_manager_lookup_item (manager, file_uri, &error);
if (error)
  {
    g_warning ("Could not find the file: %s", error->message);
    g_error_free (error);
  }
else
 {
   // Use the info object
   gtk_recent_info_unref (info);
 }
```

In order to retrieve the list of recently used files, you can use
`RecentManagerExt::get_items`, which returns a list of `RecentInfo`-structs.

A `RecentManager` is the model used to populate the contents of
one, or more `RecentChooser` implementations.

Note that the maximum age of the recently used files list is
controllable through the `Settings:gtk-recent-files-max-age`
property.

Recently used files are supported since GTK+ 2.10.

# Implements

[`RecentManagerExt`](trait.RecentManagerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait RecentManagerExt -->
Trait containing all `RecentManager` methods.

# Implementors

[`RecentManager`](struct.RecentManager.html)
<!-- impl RecentManager::fn new -->
Creates a new recent manager object. Recent manager objects are used to
handle the list of recently used resources. A `RecentManager` object
monitors the recently used resources list, and emits the “changed” signal
each time something inside the list changes.

`RecentManager` objects are expensive: be sure to create them only when
needed. You should use `RecentManager::get_default` instead.

# Returns

A newly created `RecentManager` object
<!-- impl RecentManager::fn get_default -->
Gets a unique instance of `RecentManager`, that you can share
in your application without caring about memory management.

# Returns

A unique `RecentManager`. Do not ref or
 unref it.
<!-- trait RecentManagerExt::fn add_full -->
Adds a new resource, pointed by `uri`, into the recently used
resources list, using the metadata specified inside the
`RecentData`-struct passed in `recent_data`.

The passed URI will be used to identify this resource inside the
list.

In order to register the new recently used resource, metadata about
the resource must be passed as well as the URI; the metadata is
stored in a `RecentData`-struct, which must contain the MIME
type of the resource pointed by the URI; the name of the application
that is registering the item, and a command line to be used when
launching the item.

Optionally, a `RecentData`-struct might contain a UTF-8 string
to be used when viewing the item instead of the last component of
the URI; a short description of the item; whether the item should
be considered private - that is, should be displayed only by the
applications that have registered it.
## `uri`
a valid URI
## `recent_data`
metadata of the resource

# Returns

`true` if the new item was successfully added to the
 recently used resources list, `false` otherwise
<!-- trait RecentManagerExt::fn add_item -->
Adds a new resource, pointed by `uri`, into the recently used
resources list.

This function automatically retrieves some of the needed
metadata and setting other metadata to common default values;
it then feeds the data to `RecentManagerExt::add_full`.

See `RecentManagerExt::add_full` if you want to explicitly
define the metadata for the resource pointed by `uri`.
## `uri`
a valid URI

# Returns

`true` if the new item was successfully added
 to the recently used resources list
<!-- trait RecentManagerExt::fn get_items -->
Gets the list of recently used resources.

# Returns

a list of
 newly allocated `RecentInfo` objects. Use
 `RecentInfo::unref` on each item inside the list, and then
 free the list itself using `glib::List::free`.
<!-- trait RecentManagerExt::fn has_item -->
Checks whether there is a recently used resource registered
with `uri` inside the recent manager.
## `uri`
a URI

# Returns

`true` if the resource was found, `false` otherwise
<!-- trait RecentManagerExt::fn lookup_item -->
Searches for a URI inside the recently used resources list, and
returns a `RecentInfo`-struct containing informations about the resource
like its MIME type, or its display name.
## `uri`
a URI

# Returns

a `RecentInfo`-struct containing information
 about the resource pointed by `uri`, or `None` if the URI was
 not registered in the recently used resources list. Free with
 `RecentInfo::unref`.
<!-- trait RecentManagerExt::fn move_item -->
Changes the location of a recently used resource from `uri` to `new_uri`.

Please note that this function will not affect the resource pointed
by the URIs, but only the URI used in the recently used resources list.
## `uri`
the URI of a recently used resource
## `new_uri`
the new URI of the recently used resource, or
 `None` to remove the item pointed by `uri` in the list

# Returns

`true` on success
<!-- trait RecentManagerExt::fn purge_items -->
Purges every item from the recently used resources list.

# Returns

the number of items that have been removed from the
 recently used resources list
<!-- trait RecentManagerExt::fn remove_item -->
Removes a resource pointed by `uri` from the recently used resources
list handled by a recent manager.
## `uri`
the URI of the item you wish to remove

# Returns

`true` if the item pointed by `uri` has been successfully
 removed by the recently used resources list, and `false` otherwise
<!-- trait RecentManagerExt::fn connect_changed -->
Emitted when the current recently used resources manager changes
its contents, either by calling `RecentManagerExt::add_item` or
by another application.
<!-- trait RecentManagerExt::fn get_property_filename -->
The full path to the file to be used to store and read the
recently used resources list
<!-- trait RecentManagerExt::fn set_property_filename -->
The full path to the file to be used to store and read the
recently used resources list
<!-- trait RecentManagerExt::fn get_property_size -->
The size of the recently used resources list.
<!-- enum RecentManagerError -->
Error codes for `RecentManager` operations
<!-- enum RecentManagerError::variant NotFound -->
the URI specified does not exists in
 the recently used resources list.
<!-- enum RecentManagerError::variant InvalidUri -->
the URI specified is not valid.
<!-- enum RecentManagerError::variant InvalidEncoding -->
the supplied string is not
 UTF-8 encoded.
<!-- enum RecentManagerError::variant NotRegistered -->
no application has registered
 the specified item.
<!-- enum RecentManagerError::variant Read -->
failure while reading the recently used
 resources file.
<!-- enum RecentManagerError::variant Write -->
failure while writing the recently used
 resources file.
<!-- enum RecentManagerError::variant Unknown -->
unspecified error.
<!-- enum RecentSortType -->
Used to specify the sorting method to be applyed to the recently
used resource list.
<!-- enum RecentSortType::variant None -->
Do not sort the returned list of recently used
 resources.
<!-- enum RecentSortType::variant Mru -->
Sort the returned list with the most recently used
 items first.
<!-- enum RecentSortType::variant Lru -->
Sort the returned list with the least recently used
 items first.
<!-- enum RecentSortType::variant Custom -->
Sort the returned list using a custom sorting
 function passed using `RecentChooser::set_sort_func`.
<!-- struct RegionFlags -->
Describes a region within a widget.
<!-- struct RegionFlags::const EVEN -->
Region has an even number within a set.
<!-- struct RegionFlags::const ODD -->
Region has an odd number within a set.
<!-- struct RegionFlags::const FIRST -->
Region is the first one within a set.
<!-- struct RegionFlags::const LAST -->
Region is the last one within a set.
<!-- struct RegionFlags::const ONLY -->
Region is the only one within a set.
<!-- struct RegionFlags::const SORTED -->
Region is part of a sorted area.
<!-- enum ReliefStyle -->
Indicated the relief to be drawn around a `Button`.
<!-- enum ReliefStyle::variant Normal -->
Draw a normal relief.
<!-- enum ReliefStyle::variant Half -->
A half relief. Deprecated in 3.14, does the same as `ReliefStyle::Normal`
<!-- enum ReliefStyle::variant None -->
No relief.
<!-- struct Requisition -->
A `Requisition`-struct represents the desired size of a widget. See
[`Widget`’s geometry management section][geometry-management] for
more information.
<!-- impl Requisition::fn new -->
Allocates a new `Requisition`-struct and initializes its elements to zero.

# Returns

a new empty `Requisition`. The newly allocated `Requisition` should
 be freed with `Requisition::free`.
<!-- impl Requisition::fn copy -->
Copies a `Requisition`.

# Returns

a copy of `self`
<!-- impl Requisition::fn free -->
Frees a `Requisition`.
<!-- enum ResizeMode -->
<!-- enum ResizeMode::variant Parent -->
Pass resize request to the parent
<!-- enum ResizeMode::variant Queue -->
Queue resizes on this widget
<!-- enum ResizeMode::variant Immediate -->
Resize immediately. Deprecated.
<!-- enum ResponseType -->
Predefined values for use as response ids in `DialogExt::add_button`.
All predefined values are negative; GTK+ leaves values of 0 or greater for
application-defined response ids.
<!-- enum ResponseType::variant None -->
Returned if an action widget has no response id,
 or if the dialog gets programmatically hidden or destroyed
<!-- enum ResponseType::variant Reject -->
Generic response id, not used by GTK+ dialogs
<!-- enum ResponseType::variant Accept -->
Generic response id, not used by GTK+ dialogs
<!-- enum ResponseType::variant DeleteEvent -->
Returned if the dialog is deleted
<!-- enum ResponseType::variant Ok -->
Returned by OK buttons in GTK+ dialogs
<!-- enum ResponseType::variant Cancel -->
Returned by Cancel buttons in GTK+ dialogs
<!-- enum ResponseType::variant Close -->
Returned by Close buttons in GTK+ dialogs
<!-- enum ResponseType::variant Yes -->
Returned by Yes buttons in GTK+ dialogs
<!-- enum ResponseType::variant No -->
Returned by No buttons in GTK+ dialogs
<!-- enum ResponseType::variant Apply -->
Returned by Apply buttons in GTK+ dialogs
<!-- enum ResponseType::variant Help -->
Returned by Help buttons in GTK+ dialogs
<!-- struct Revealer -->
The `Revealer` widget is a container which animates
the transition of its child from invisible to visible.

The style of transition can be controlled with
`RevealerExt::set_transition_type`.

These animations respect the `Settings:gtk-enable-animations`
setting.

# CSS nodes

`Revealer` has a single CSS node with name revealer.

The `Revealer` widget was added in GTK+ 3.10.

# Implements

[`RevealerExt`](trait.RevealerExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait RevealerExt -->
Trait containing all `Revealer` methods.

# Implementors

[`Revealer`](struct.Revealer.html)
<!-- impl Revealer::fn new -->
Creates a new `Revealer`.

# Returns

a newly created `Revealer`
<!-- trait RevealerExt::fn get_child_revealed -->
Returns whether the child is fully revealed, in other words whether
the transition to the revealed state is completed.

# Returns

`true` if the child is fully revealed
<!-- trait RevealerExt::fn get_reveal_child -->
Returns whether the child is currently
revealed. See `RevealerExt::set_reveal_child`.

This function returns `true` as soon as the transition
is to the revealed state is started. To learn whether
the child is fully revealed (ie the transition is completed),
use `RevealerExt::get_child_revealed`.

# Returns

`true` if the child is revealed.
<!-- trait RevealerExt::fn get_transition_duration -->
Returns the amount of time (in milliseconds) that
transitions will take.

# Returns

the transition duration
<!-- trait RevealerExt::fn get_transition_type -->
Gets the type of animation that will be used
for transitions in `self`.

# Returns

the current transition type of `self`
<!-- trait RevealerExt::fn set_reveal_child -->
Tells the `Revealer` to reveal or conceal its child.

The transition will be animated with the current
transition type of `self`.
## `reveal_child`
`true` to reveal the child
<!-- trait RevealerExt::fn set_transition_duration -->
Sets the duration that transitions will take.
## `duration`
the new duration, in milliseconds
<!-- trait RevealerExt::fn set_transition_type -->
Sets the type of animation that will be used for
transitions in `self`. Available types include
various kinds of fades and slides.
## `transition`
the new transition type
<!-- enum RevealerTransitionType -->
These enumeration values describe the possible transitions
when the child of a `Revealer` widget is shown or hidden.
<!-- enum RevealerTransitionType::variant None -->
No transition
<!-- enum RevealerTransitionType::variant Crossfade -->
Fade in
<!-- enum RevealerTransitionType::variant SlideRight -->
Slide in from the left
<!-- enum RevealerTransitionType::variant SlideLeft -->
Slide in from the right
<!-- enum RevealerTransitionType::variant SlideUp -->
Slide in from the bottom
<!-- enum RevealerTransitionType::variant SlideDown -->
Slide in from the top
<!-- struct Scale -->
A `Scale` is a slider control used to select a numeric value.
To use it, you’ll probably want to investigate the methods on
its base class, `Range`, in addition to the methods for `Scale` itself.
To set the value of a scale, you would normally use `RangeExt::set_value`.
To detect changes to the value, you would normally use the
`Range::value-changed` signal.

Note that using the same upper and lower bounds for the `Scale` (through
the `Range` methods) will hide the slider itself. This is useful for
applications that want to show an undeterminate value on the scale, without
changing the layout of the application (such as movie or music players).

# `Scale` as `Buildable`

`Scale` supports a custom `<marks>` element, which can contain multiple
`<mark>` elements. The “value” and “position” attributes have the same
meaning as `ScaleExt::add_mark` parameters of the same name. If the
element is not empty, its content is taken as the markup to show at
the mark. It can be translated with the usual ”translatable” and
“context” attributes.

# CSS nodes


```plain
scale[.fine-tune][.marks-before][.marks-after]
├── marks.top
│   ├── mark
│   ┊    ├── [label]
│   ┊    ╰── indicator
┊   ┊
│   ╰── mark
├── [value]
├── contents
│   ╰── trough
│       ├── slider
│       ├── [highlight]
│       ╰── [fill]
╰── marks.bottom
    ├── mark
    ┊    ├── indicator
    ┊    ╰── [label]
    ╰── mark
```

`Scale` has a main CSS node with name scale and a subnode for its contents,
with subnodes named trough and slider.

The main node gets the style class .fine-tune added when the scale is in
'fine-tuning' mode.

If the scale has an origin (see `ScaleExt::set_has_origin`), there is a
subnode with name highlight below the trough node that is used for rendering
the highlighted part of the trough.

If the scale is showing a fill level (see `RangeExt::set_show_fill_level`),
there is a subnode with name fill below the trough node that is used for
rendering the filled in part of the trough.

If marks are present, there is a marks subnode before or after the contents
node, below which each mark gets a node with name mark. The marks nodes get
either the .top or .bottom style class.

The mark node has a subnode named indicator. If the mark has text, it also
has a subnode named label. When the mark is either above or left of the
scale, the label subnode is the first when present. Otherwise, the indicator
subnode is the first.

The main CSS node gets the 'marks-before' and/or 'marks-after' style classes
added depending on what marks are present.

If the scale is displaying the value (see `Scale:draw-value`), there is
subnode with name value.

# Implements

[`ScaleExt`](trait.ScaleExt.html), [`RangeExt`](trait.RangeExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ScaleExt -->
Trait containing all `Scale` methods.

# Implementors

[`Scale`](struct.Scale.html)
<!-- impl Scale::fn new -->
Creates a new `Scale`.
## `orientation`
the scale’s orientation.
## `adjustment`
the `Adjustment` which sets the range
 of the scale, or `None` to create a new adjustment.

# Returns

a new `Scale`
<!-- impl Scale::fn new_with_range -->
Creates a new scale widget with the given orientation that lets the
user input a number between `min` and `max` (including `min` and `max`)
with the increment `step`. `step` must be nonzero; it’s the distance
the slider moves when using the arrow keys to adjust the scale
value.

Note that the way in which the precision is derived works best if `step`
is a power of ten. If the resulting precision is not suitable for your
needs, use `ScaleExt::set_digits` to correct it.
## `orientation`
the scale’s orientation.
## `min`
minimum value
## `max`
maximum value
## `step`
step increment (tick size) used with keyboard shortcuts

# Returns

a new `Scale`
<!-- trait ScaleExt::fn add_mark -->
Adds a mark at `value`.

A mark is indicated visually by drawing a tick mark next to the scale,
and GTK+ makes it easy for the user to position the scale exactly at the
marks value.

If `markup` is not `None`, text is shown next to the tick mark.

To remove marks from a scale, use `ScaleExt::clear_marks`.
## `value`
the value at which the mark is placed, must be between
 the lower and upper limits of the scales’ adjustment
## `position`
where to draw the mark. For a horizontal scale, `PositionType::Top`
 and `PositionType::Left` are drawn above the scale, anything else below.
 For a vertical scale, `PositionType::Left` and `PositionType::Top` are drawn to
 the left of the scale, anything else to the right.
## `markup`
Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or `None`
<!-- trait ScaleExt::fn clear_marks -->
Removes any marks that have been added with `ScaleExt::add_mark`.
<!-- trait ScaleExt::fn get_digits -->
Gets the number of decimal places that are displayed in the value.

# Returns

the number of decimal places that are displayed
<!-- trait ScaleExt::fn get_draw_value -->
Returns whether the current value is displayed as a string
next to the slider.

# Returns

whether the current value is displayed as a string
<!-- trait ScaleExt::fn get_has_origin -->
Returns whether the scale has an origin.

# Returns

`true` if the scale has an origin.
<!-- trait ScaleExt::fn get_layout -->
Gets the `pango::Layout` used to display the scale. The returned
object is owned by the scale so does not need to be freed by
the caller.

# Returns

the `pango::Layout` for this scale,
 or `None` if the `Scale:draw-value` property is `false`.
<!-- trait ScaleExt::fn get_layout_offsets -->
Obtains the coordinates where the scale will draw the
`pango::Layout` representing the text in the scale. Remember
when using the `pango::Layout` function you need to convert to
and from pixels using PANGO_PIXELS() or `PANGO_SCALE`.

If the `Scale:draw-value` property is `false`, the return
values are undefined.
## `x`
location to store X offset of layout, or `None`
## `y`
location to store Y offset of layout, or `None`
<!-- trait ScaleExt::fn get_value_pos -->
Gets the position in which the current value is displayed.

# Returns

the position in which the current value is displayed
<!-- trait ScaleExt::fn set_digits -->
Sets the number of decimal places that are displayed in the value. Also
causes the value of the adjustment to be rounded to this number of digits,
so the retrieved value matches the displayed one, if `Scale:draw-value` is
`true` when the value changes. If you want to enforce rounding the value when
`Scale:draw-value` is `false`, you can set `Range:round-digits` instead.

Note that rounding to a small number of digits can interfere with
the smooth autoscrolling that is built into `Scale`. As an alternative,
you can use the `Scale::format-value` signal to format the displayed
value yourself.
## `digits`
the number of decimal places to display,
 e.g. use 1 to display 1.0, 2 to display 1.00, etc
<!-- trait ScaleExt::fn set_draw_value -->
Specifies whether the current value is displayed as a string next
to the slider.
## `draw_value`
`true` to draw the value
<!-- trait ScaleExt::fn set_has_origin -->
If `Scale:has-origin` is set to `true` (the default), the scale will
highlight the part of the trough between the origin (bottom or left side)
and the current value.
## `has_origin`
`true` if the scale has an origin
<!-- trait ScaleExt::fn set_value_pos -->
Sets the position in which the current value is displayed.
## `pos`
the position in which the current value is displayed
<!-- trait ScaleExt::fn connect_format_value -->
Signal which allows you to change how the scale value is displayed.
Connect a signal handler which returns an allocated string representing
`value`. That string will then be used to display the scale's value.

If no user-provided handlers are installed, the value will be displayed on
its own, rounded according to the value of the `Scale:digits` property.

Here's an example signal handler which displays a value 1.0 as
with "-->1.0<--".

```C
static gchar*
format_value_callback (GtkScale *scale,
                       gdouble   value)
{
  return g_strdup_printf ("-->\%0.*g<--",
                          gtk_scale_get_digits (scale), value);
 }
```
## `value`
the value to format

# Returns

allocated string representing `value`
<!-- struct ScaleButton -->
`ScaleButton` provides a button which pops up a scale widget.
This kind of widget is commonly used for volume controls in multimedia
applications, and GTK+ provides a `VolumeButton` subclass that
is tailored for this use case.

# CSS nodes

`ScaleButton` has a single CSS node with name button. To differentiate
it from a plain `Button`, it gets the .scale style class.

The popup widget that contains the scale has a .scale-popup style class.

# Implements

[`ScaleButtonExt`](trait.ScaleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ScaleButtonExt -->
Trait containing all `ScaleButton` methods.

# Implementors

[`ScaleButton`](struct.ScaleButton.html), [`VolumeButton`](struct.VolumeButton.html)
<!-- impl ScaleButton::fn new -->
Creates a `ScaleButton`, with a range between `min` and `max`, with
a stepping of `step`.
## `size`
a stock icon size (`IconSize`)
## `min`
the minimum value of the scale (usually 0)
## `max`
the maximum value of the scale (usually 100)
## `step`
the stepping of value when a scroll-wheel event,
 or up/down arrow event occurs (usually 2)
## `icons`
a `None`-terminated
 array of icon names, or `None` if you want to set the list
 later with `ScaleButtonExt::set_icons`

# Returns

a new `ScaleButton`
<!-- trait ScaleButtonExt::fn get_adjustment -->
Gets the `Adjustment` associated with the `ScaleButton`’s scale.
See `RangeExt::get_adjustment` for details.

# Returns

the adjustment associated with the scale
<!-- trait ScaleButtonExt::fn get_minus_button -->
Retrieves the minus button of the `ScaleButton`.

# Returns

the minus button of the `ScaleButton` as a `Button`
<!-- trait ScaleButtonExt::fn get_plus_button -->
Retrieves the plus button of the `ScaleButton`.

# Returns

the plus button of the `ScaleButton` as a `Button`
<!-- trait ScaleButtonExt::fn get_popup -->
Retrieves the popup of the `ScaleButton`.

# Returns

the popup of the `ScaleButton`
<!-- trait ScaleButtonExt::fn get_value -->
Gets the current value of the scale button.

# Returns

current value of the scale button
<!-- trait ScaleButtonExt::fn set_adjustment -->
Sets the `Adjustment` to be used as a model
for the `ScaleButton`’s scale.
See `RangeExt::set_adjustment` for details.
## `adjustment`
a `Adjustment`
<!-- trait ScaleButtonExt::fn set_icons -->
Sets the icons to be used by the scale button.
For details, see the `ScaleButton:icons` property.
## `icons`
a `None`-terminated array of icon names
<!-- trait ScaleButtonExt::fn set_value -->
Sets the current value of the scale; if the value is outside
the minimum or maximum range values, it will be clamped to fit
inside them. The scale button emits the `ScaleButton::value-changed`
signal if the value changes.
## `value`
new value of the scale button
<!-- trait ScaleButtonExt::fn connect_popdown -->
The ::popdown signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to popdown the scale widget.

The default binding for this signal is Escape.
<!-- trait ScaleButtonExt::fn connect_popup -->
The ::popup signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to popup the scale widget.

The default bindings for this signal are Space, Enter and Return.
<!-- trait ScaleButtonExt::fn connect_value_changed -->
The ::value-changed signal is emitted when the value field has
changed.
## `value`
the new value
<!-- trait ScaleButtonExt::fn get_property_icons -->
The names of the icons to be used by the scale button.
The first item in the array will be used in the button
when the current value is the lowest value, the second
item for the highest value. All the subsequent icons will
be used for all the other values, spread evenly over the
range of values.

If there's only one icon name in the `icons` array, it will
be used for all the values. If only two icon names are in
the `icons` array, the first one will be used for the bottom
50% of the scale, and the second one for the top 50%.

It is recommended to use at least 3 icons so that the
`ScaleButton` reflects the current value of the scale
better for the users.
<!-- trait ScaleButtonExt::fn set_property_icons -->
The names of the icons to be used by the scale button.
The first item in the array will be used in the button
when the current value is the lowest value, the second
item for the highest value. All the subsequent icons will
be used for all the other values, spread evenly over the
range of values.

If there's only one icon name in the `icons` array, it will
be used for all the values. If only two icon names are in
the `icons` array, the first one will be used for the bottom
50% of the scale, and the second one for the top 50%.

It is recommended to use at least 3 icons so that the
`ScaleButton` reflects the current value of the scale
better for the users.
<!-- enum ScrollStep -->
<!-- enum ScrollStep::variant Steps -->
Scroll in steps.
<!-- enum ScrollStep::variant Pages -->
Scroll by pages.
<!-- enum ScrollStep::variant Ends -->
Scroll to ends.
<!-- enum ScrollStep::variant HorizontalSteps -->
Scroll in horizontal steps.
<!-- enum ScrollStep::variant HorizontalPages -->
Scroll by horizontal pages.
<!-- enum ScrollStep::variant HorizontalEnds -->
Scroll to the horizontal ends.
<!-- enum ScrollType -->
Scrolling types.
<!-- enum ScrollType::variant None -->
No scrolling.
<!-- enum ScrollType::variant Jump -->
Jump to new location.
<!-- enum ScrollType::variant StepBackward -->
Step backward.
<!-- enum ScrollType::variant StepForward -->
Step forward.
<!-- enum ScrollType::variant PageBackward -->
Page backward.
<!-- enum ScrollType::variant PageForward -->
Page forward.
<!-- enum ScrollType::variant StepUp -->
Step up.
<!-- enum ScrollType::variant StepDown -->
Step down.
<!-- enum ScrollType::variant PageUp -->
Page up.
<!-- enum ScrollType::variant PageDown -->
Page down.
<!-- enum ScrollType::variant StepLeft -->
Step to the left.
<!-- enum ScrollType::variant StepRight -->
Step to the right.
<!-- enum ScrollType::variant PageLeft -->
Page to the left.
<!-- enum ScrollType::variant PageRight -->
Page to the right.
<!-- enum ScrollType::variant Start -->
Scroll to start.
<!-- enum ScrollType::variant End -->
Scroll to end.
<!-- struct Scrollable -->
`Scrollable` is an interface that is implemented by widgets with native
scrolling ability.

To implement this interface you should override the
`Scrollable:hadjustment` and `Scrollable:vadjustment` properties.

## Creating a scrollable widget

All scrollable widgets should do the following.

- When a parent widget sets the scrollable child widget’s adjustments,
 the widget should populate the adjustments’
 `Adjustment:lower`, `Adjustment:upper`,
 `Adjustment:step-increment`, `Adjustment:page-increment` and
 `Adjustment:page-size` properties and connect to the
 `Adjustment::value-changed` signal.

- Because its preferred size is the size for a fully expanded widget,
 the scrollable widget must be able to cope with underallocations.
 This means that it must accept any value passed to its
 `WidgetClass.size_allocate`() function.

- When the parent allocates space to the scrollable child widget,
 the widget should update the adjustments’ properties with new values.

- When any of the adjustments emits the `Adjustment::value-changed` signal,
 the scrollable widget should scroll its contents.

# Implements

[`ScrollableExt`](trait.ScrollableExt.html)
<!-- trait ScrollableExt -->
Trait containing all `Scrollable` methods.

# Implementors

[`IconView`](struct.IconView.html), [`Layout`](struct.Layout.html), [`Scrollable`](struct.Scrollable.html), [`TextView`](struct.TextView.html), [`ToolPalette`](struct.ToolPalette.html), [`TreeView`](struct.TreeView.html), [`Viewport`](struct.Viewport.html)
<!-- trait ScrollableExt::fn get_border -->
Returns the size of a non-scrolling border around the
outside of the scrollable. An example for this would
be treeview headers. GTK+ can use this information to
display overlayed graphics, like the overshoot indication,
at the right position.

Feature: `v3_16`

## `border`
return location for the results

# Returns

`true` if `border` has been set
<!-- trait ScrollableExt::fn get_hadjustment -->
Retrieves the `Adjustment` used for horizontal scrolling.

# Returns

horizontal `Adjustment`.
<!-- trait ScrollableExt::fn get_hscroll_policy -->
Gets the horizontal `ScrollablePolicy`.

# Returns

The horizontal `ScrollablePolicy`.
<!-- trait ScrollableExt::fn get_vadjustment -->
Retrieves the `Adjustment` used for vertical scrolling.

# Returns

vertical `Adjustment`.
<!-- trait ScrollableExt::fn get_vscroll_policy -->
Gets the vertical `ScrollablePolicy`.

# Returns

The vertical `ScrollablePolicy`.
<!-- trait ScrollableExt::fn set_hadjustment -->
Sets the horizontal adjustment of the `Scrollable`.
## `hadjustment`
a `Adjustment`
<!-- trait ScrollableExt::fn set_hscroll_policy -->
Sets the `ScrollablePolicy` to determine whether
horizontal scrolling should start below the minimum width or
below the natural width.
## `policy`
the horizontal `ScrollablePolicy`
<!-- trait ScrollableExt::fn set_vadjustment -->
Sets the vertical adjustment of the `Scrollable`.
## `vadjustment`
a `Adjustment`
<!-- trait ScrollableExt::fn set_vscroll_policy -->
Sets the `ScrollablePolicy` to determine whether
vertical scrolling should start below the minimum height or
below the natural height.
## `policy`
the vertical `ScrollablePolicy`
<!-- trait ScrollableExt::fn get_property_hadjustment -->
Horizontal `Adjustment` of the scrollable widget. This adjustment is
shared between the scrollable widget and its parent.
<!-- trait ScrollableExt::fn set_property_hadjustment -->
Horizontal `Adjustment` of the scrollable widget. This adjustment is
shared between the scrollable widget and its parent.
<!-- trait ScrollableExt::fn get_property_hscroll_policy -->
Determines whether horizontal scrolling should start once the scrollable
widget is allocated less than its minimum width or less than its natural width.
<!-- trait ScrollableExt::fn set_property_hscroll_policy -->
Determines whether horizontal scrolling should start once the scrollable
widget is allocated less than its minimum width or less than its natural width.
<!-- trait ScrollableExt::fn get_property_vadjustment -->
Verical `Adjustment` of the scrollable widget. This adjustment is shared
between the scrollable widget and its parent.
<!-- trait ScrollableExt::fn set_property_vadjustment -->
Verical `Adjustment` of the scrollable widget. This adjustment is shared
between the scrollable widget and its parent.
<!-- trait ScrollableExt::fn get_property_vscroll_policy -->
Determines whether vertical scrolling should start once the scrollable
widget is allocated less than its minimum height or less than its natural height.
<!-- trait ScrollableExt::fn set_property_vscroll_policy -->
Determines whether vertical scrolling should start once the scrollable
widget is allocated less than its minimum height or less than its natural height.
<!-- enum ScrollablePolicy -->
Defines the policy to be used in a scrollable widget when updating
the scrolled window adjustments in a given orientation.
<!-- enum ScrollablePolicy::variant Minimum -->
Scrollable adjustments are based on the minimum size
<!-- enum ScrollablePolicy::variant Natural -->
Scrollable adjustments are based on the natural size
<!-- struct Scrollbar -->
The `Scrollbar` widget is a horizontal or vertical scrollbar,
depending on the value of the `Orientable:orientation` property.

Its position and movement are controlled by the adjustment that is passed to
or created by `Scrollbar::new`. See `Adjustment` for more details. The
`Adjustment:value` field sets the position of the thumb and must be between
`Adjustment:lower` and `Adjustment:upper` - `Adjustment:page-size`. The
`Adjustment:page-size` represents the size of the visible scrollable area.
The fields `Adjustment:step-increment` and `Adjustment:page-increment`
fields are added to or subtracted from the `Adjustment:value` when the user
asks to move by a step (using e.g. the cursor arrow keys or, if present, the
stepper buttons) or by a page (using e.g. the Page Down/Up keys).

# CSS nodes


```plain
scrollbar[.fine-tune]
╰── contents
    ├── [button.up]
    ├── [button.down]
    ├── trough
    │   ╰── slider
    ├── [button.up]
    ╰── [button.down]
```

`Scrollbar` has a main CSS node with name scrollbar and a subnode for its
contents, with subnodes named trough and slider.

The main node gets the style class .fine-tune added when the scrollbar is
in 'fine-tuning' mode.

If steppers are enabled, they are represented by up to four additional
subnodes with name button. These get the style classes .up and .down to
indicate in which direction they are moving.

Other style classes that may be added to scrollbars inside `ScrolledWindow`
include the positional classes (.left, .right, .top, .bottom) and style
classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering).

# Implements

[`RangeExt`](trait.RangeExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl Scrollbar::fn new -->
Creates a new scrollbar with the given orientation.
## `orientation`
the scrollbar’s orientation.
## `adjustment`
the `Adjustment` to use, or `None` to create a new adjustment.

# Returns

the new `Scrollbar`.
<!-- struct ScrolledWindow -->
`ScrolledWindow` is a container that accepts a single child widget, makes
that child scrollable using either internally added scrollbars or externally
associated adjustments, and optionally draws a frame around the child.

Widgets with native scrolling support, i.e. those whose classes implement the
`Scrollable` interface, are added directly. For other types of widget, the
class `Viewport` acts as an adaptor, giving scrollability to other widgets.
`ScrolledWindow`’s implementation of `ContainerExt::add` intelligently
accounts for whether or not the added child is a `Scrollable`. If it isn’t,
`ScrolledWindow` wraps the child in a `Viewport` and adds that for you.
Therefore, you can just add any child widget and not worry about the details.

If `ContainerExt::add` has added a `Viewport` for you, you can remove
both your added child widget from the `Viewport`, and the `Viewport`
from the `ScrolledWindow`, like this:


```C
GtkWidget *scrolled_window = gtk_scrolled_window_new (NULL, NULL);
GtkWidget *child_widget = gtk_button_new ();

// GtkButton is not a GtkScrollable, so GtkScrolledWindow will automatically
// add a GtkViewport.
gtk_container_add (GTK_CONTAINER (scrolled_window),
                   child_widget);

// Either of these will result in child_widget being unparented:
gtk_container_remove (GTK_CONTAINER (scrolled_window),
                      child_widget);
// or
gtk_container_remove (GTK_CONTAINER (scrolled_window),
                      gtk_bin_get_child (GTK_BIN (scrolled_window)));
```

Unless `ScrolledWindow:policy` is GTK_POLICY_NEVER or GTK_POLICY_EXTERNAL,
`ScrolledWindow` adds internal `Scrollbar` widgets around its child. The
scroll position of the child, and if applicable the scrollbars, is controlled
by the `ScrolledWindow:hadjustment` and `ScrolledWindow:vadjustment`
that are associated with the `ScrolledWindow`. See the docs on `Scrollbar`
for the details, but note that the “step_increment” and “page_increment”
fields are only effective if the policy causes scrollbars to be present.

If a `ScrolledWindow` doesn’t behave quite as you would like, or
doesn’t have exactly the right layout, it’s very possible to set up
your own scrolling with `Scrollbar` and for example a `Grid`.

# Touch support

`ScrolledWindow` has built-in support for touch devices. When a
touchscreen is used, swiping will move the scrolled window, and will
expose 'kinetic' behavior. This can be turned off with the
`ScrolledWindow:kinetic-scrolling` property if it is undesired.

`ScrolledWindow` also displays visual 'overshoot' indication when
the content is pulled beyond the end, and this situation can be
captured with the `ScrolledWindow::edge-overshot` signal.

If no mouse device is present, the scrollbars will overlayed as
narrow, auto-hiding indicators over the content. If traditional
scrollbars are desired although no mouse is present, this behaviour
can be turned off with the `ScrolledWindow:overlay-scrolling`
property.

# CSS nodes

`ScrolledWindow` has a main CSS node with name scrolledwindow.

It uses subnodes with names overshoot and undershoot to
draw the overflow and underflow indications. These nodes get
the .left, .right, .top or .bottom style class added depending
on where the indication is drawn.

`ScrolledWindow` also sets the positional style classes (.left,
.right, .top, .bottom) and style classes related to overlay
scrolling (.overlay-indicator, .dragging, .hovering) on its scrollbars.

If both scrollbars are visible, the area where they meet is drawn
with a subnode named junction.

# Implements

[`ScrolledWindowExt`](trait.ScrolledWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ScrolledWindowExt -->
Trait containing all `ScrolledWindow` methods.

# Implementors

[`PlacesSidebar`](struct.PlacesSidebar.html), [`ScrolledWindow`](struct.ScrolledWindow.html)
<!-- impl ScrolledWindow::fn new -->
Creates a new scrolled window.

The two arguments are the scrolled window’s adjustments; these will be
shared with the scrollbars and the child widget to keep the bars in sync
with the child. Usually you want to pass `None` for the adjustments, which
will cause the scrolled window to create them for you.
## `hadjustment`
horizontal adjustment
## `vadjustment`
vertical adjustment

# Returns

a new scrolled window
<!-- trait ScrolledWindowExt::fn get_capture_button_press -->
Return whether button presses are captured during kinetic
scrolling. See `ScrolledWindowExt::set_capture_button_press`.

# Returns

`true` if button presses are captured during kinetic scrolling
<!-- trait ScrolledWindowExt::fn get_hadjustment -->
Returns the horizontal scrollbar’s adjustment, used to connect the
horizontal scrollbar to the child widget’s horizontal scroll
functionality.

# Returns

the horizontal `Adjustment`
<!-- trait ScrolledWindowExt::fn get_hscrollbar -->
Returns the horizontal scrollbar of `self`.

# Returns

the horizontal scrollbar of the scrolled window.
<!-- trait ScrolledWindowExt::fn get_kinetic_scrolling -->
Returns the specified kinetic scrolling behavior.

# Returns

the scrolling behavior flags.
<!-- trait ScrolledWindowExt::fn get_max_content_height -->
Returns the maximum content height set.

Feature: `v3_22`


# Returns

the maximum content height, or -1
<!-- trait ScrolledWindowExt::fn get_max_content_width -->
Returns the maximum content width set.

Feature: `v3_22`


# Returns

the maximum content width, or -1
<!-- trait ScrolledWindowExt::fn get_min_content_height -->
Gets the minimal content height of `self`, or -1 if not set.

# Returns

the minimal content height
<!-- trait ScrolledWindowExt::fn get_min_content_width -->
Gets the minimum content width of `self`, or -1 if not set.

# Returns

the minimum content width
<!-- trait ScrolledWindowExt::fn get_overlay_scrolling -->
Returns whether overlay scrolling is enabled for this scrolled window.

Feature: `v3_16`


# Returns

`true` if overlay scrolling is enabled
<!-- trait ScrolledWindowExt::fn get_placement -->
Gets the placement of the contents with respect to the scrollbars
for the scrolled window. See `ScrolledWindowExt::set_placement`.

# Returns

the current placement value.

See also `ScrolledWindowExt::set_placement` and
`ScrolledWindowExt::unset_placement`.
<!-- trait ScrolledWindowExt::fn get_policy -->
Retrieves the current policy values for the horizontal and vertical
scrollbars. See `ScrolledWindowExt::set_policy`.
## `hscrollbar_policy`
location to store the policy
 for the horizontal scrollbar, or `None`
## `vscrollbar_policy`
location to store the policy
 for the vertical scrollbar, or `None`
<!-- trait ScrolledWindowExt::fn get_propagate_natural_height -->
Reports whether the natural height of the child will be calculated and propagated
through the scrolled window’s requested natural height.

Feature: `v3_22`


# Returns

whether natural height propagation is enabled.
<!-- trait ScrolledWindowExt::fn get_propagate_natural_width -->
Reports whether the natural width of the child will be calculated and propagated
through the scrolled window’s requested natural width.

Feature: `v3_22`


# Returns

whether natural width propagation is enabled.
<!-- trait ScrolledWindowExt::fn get_shadow_type -->
Gets the shadow type of the scrolled window. See
`ScrolledWindowExt::set_shadow_type`.

# Returns

the current shadow type
<!-- trait ScrolledWindowExt::fn get_vadjustment -->
Returns the vertical scrollbar’s adjustment, used to connect the
vertical scrollbar to the child widget’s vertical scroll functionality.

# Returns

the vertical `Adjustment`
<!-- trait ScrolledWindowExt::fn get_vscrollbar -->
Returns the vertical scrollbar of `self`.

# Returns

the vertical scrollbar of the scrolled window.
<!-- trait ScrolledWindowExt::fn set_capture_button_press -->
Changes the behaviour of `self` with regard to the initial
event that possibly starts kinetic scrolling. When `capture_button_press`
is set to `true`, the event is captured by the scrolled window, and
then later replayed if it is meant to go to the child widget.

This should be enabled if any child widgets perform non-reversible
actions on `Widget::button-press-event`. If they don't, and handle
additionally handle `Widget::grab-broken-event`, it might be better
to set `capture_button_press` to `false`.

This setting only has an effect if kinetic scrolling is enabled.
## `capture_button_press`
`true` to capture button presses
<!-- trait ScrolledWindowExt::fn set_hadjustment -->
Sets the `Adjustment` for the horizontal scrollbar.
## `hadjustment`
the `Adjustment` to use, or `None` to create a new one
<!-- trait ScrolledWindowExt::fn set_kinetic_scrolling -->
Turns kinetic scrolling on or off.
Kinetic scrolling only applies to devices with source
`gdk::InputSource::Touchscreen`.
## `kinetic_scrolling`
`true` to enable kinetic scrolling
<!-- trait ScrolledWindowExt::fn set_max_content_height -->
Sets the maximum height that `self` should keep visible. The
`self` will grow up to this height before it starts scrolling
the content.

It is a programming error to set the maximum content height to a value
smaller than `ScrolledWindow:min-content-height`.

Feature: `v3_22`

## `height`
the maximum content height
<!-- trait ScrolledWindowExt::fn set_max_content_width -->
Sets the maximum width that `self` should keep visible. The
`self` will grow up to this width before it starts scrolling
the content.

It is a programming error to set the maximum content width to a value
smaller than `ScrolledWindow:min-content-width`.

Feature: `v3_22`

## `width`
the maximum content width
<!-- trait ScrolledWindowExt::fn set_min_content_height -->
Sets the minimum height that `self` should keep visible.
Note that this can and (usually will) be smaller than the minimum
size of the content.

It is a programming error to set the minimum content height to a
value greater than `ScrolledWindow:max-content-height`.
## `height`
the minimal content height
<!-- trait ScrolledWindowExt::fn set_min_content_width -->
Sets the minimum width that `self` should keep visible.
Note that this can and (usually will) be smaller than the minimum
size of the content.

It is a programming error to set the minimum content width to a
value greater than `ScrolledWindow:max-content-width`.
## `width`
the minimal content width
<!-- trait ScrolledWindowExt::fn set_overlay_scrolling -->
Enables or disables overlay scrolling for this scrolled window.

Feature: `v3_16`

## `overlay_scrolling`
whether to enable overlay scrolling
<!-- trait ScrolledWindowExt::fn set_placement -->
Sets the placement of the contents with respect to the scrollbars
for the scrolled window.

The default is `CornerType::TopLeft`, meaning the child is
in the top left, with the scrollbars underneath and to the right.
Other values in `CornerType` are `CornerType::TopRight`,
`CornerType::BottomLeft`, and `CornerType::BottomRight`.

See also `ScrolledWindowExt::get_placement` and
`ScrolledWindowExt::unset_placement`.
## `window_placement`
position of the child window
<!-- trait ScrolledWindowExt::fn set_policy -->
Sets the scrollbar policy for the horizontal and vertical scrollbars.

The policy determines when the scrollbar should appear; it is a value
from the `PolicyType` enumeration. If `PolicyType::Always`, the
scrollbar is always present; if `PolicyType::Never`, the scrollbar is
never present; if `PolicyType::Automatic`, the scrollbar is present only
if needed (that is, if the slider part of the bar would be smaller
than the trough — the display is larger than the page size).
## `hscrollbar_policy`
policy for horizontal bar
## `vscrollbar_policy`
policy for vertical bar
<!-- trait ScrolledWindowExt::fn set_propagate_natural_height -->
Sets whether the natural height of the child should be calculated and propagated
through the scrolled window’s requested natural height.

Feature: `v3_22`

## `propagate`
whether to propagate natural height
<!-- trait ScrolledWindowExt::fn set_propagate_natural_width -->
Sets whether the natural width of the child should be calculated and propagated
through the scrolled window’s requested natural width.

Feature: `v3_22`

## `propagate`
whether to propagate natural width
<!-- trait ScrolledWindowExt::fn set_shadow_type -->
Changes the type of shadow drawn around the contents of
`self`.
## `type_`
kind of shadow to draw around scrolled window contents
<!-- trait ScrolledWindowExt::fn set_vadjustment -->
Sets the `Adjustment` for the vertical scrollbar.
## `vadjustment`
the `Adjustment` to use, or `None` to create a new one
<!-- trait ScrolledWindowExt::fn unset_placement -->
Unsets the placement of the contents with respect to the scrollbars
for the scrolled window. If no window placement is set for a scrolled
window, it defaults to `CornerType::TopLeft`.

See also `ScrolledWindowExt::set_placement` and
`ScrolledWindowExt::get_placement`.
<!-- trait ScrolledWindowExt::fn connect_edge_overshot -->
The ::edge-overshot signal is emitted whenever user initiated scrolling
makes the scrolled window firmly surpass (i.e. with some edge resistance)
the lower or upper limits defined by the adjustment in that orientation.

A similar behavior without edge resistance is provided by the
`ScrolledWindow::edge-reached` signal.

Note: The `pos` argument is LTR/RTL aware, so callers should be aware too
if intending to provide behavior on horizontal edges.

Feature: `v3_16`

## `pos`
edge side that was hit
<!-- trait ScrolledWindowExt::fn connect_edge_reached -->
The ::edge-reached signal is emitted whenever user-initiated scrolling
makes the scrolled window exactly reach the lower or upper limits
defined by the adjustment in that orientation.

A similar behavior with edge resistance is provided by the
`ScrolledWindow::edge-overshot` signal.

Note: The `pos` argument is LTR/RTL aware, so callers should be aware too
if intending to provide behavior on horizontal edges.

Feature: `v3_16`

## `pos`
edge side that was reached
<!-- trait ScrolledWindowExt::fn connect_move_focus_out -->
The ::move-focus-out signal is a
[keybinding signal][`BindingSignal`] which gets
emitted when focus is moved away from the scrolled window by a
keybinding. The `Widget::move-focus` signal is emitted with
`direction_type` on this scrolled window’s toplevel parent in the
container hierarchy. The default bindings for this signal are
`Ctrl + Tab` to move forward and `Ctrl + Shift + Tab` to move backward.
## `direction_type`
either `DirectionType::TabForward` or
 `DirectionType::TabBackward`
<!-- trait ScrolledWindowExt::fn connect_scroll_child -->
The ::scroll-child signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when a keybinding that scrolls is pressed.
The horizontal or vertical adjustment is updated which triggers a
signal that the scrolled window’s child may listen to and scroll itself.
## `scroll`
a `ScrollType` describing how much to scroll
## `horizontal`
whether the keybinding scrolls the child
 horizontally or not
<!-- trait ScrolledWindowExt::fn get_property_kinetic_scrolling -->
Whether kinetic scrolling is enabled or not. Kinetic scrolling
only applies to devices with source `gdk::InputSource::Touchscreen`.
<!-- trait ScrolledWindowExt::fn set_property_kinetic_scrolling -->
Whether kinetic scrolling is enabled or not. Kinetic scrolling
only applies to devices with source `gdk::InputSource::Touchscreen`.
<!-- trait ScrolledWindowExt::fn get_property_max_content_height -->
The maximum content height of `scrolled_window`, or -1 if not set.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn set_property_max_content_height -->
The maximum content height of `scrolled_window`, or -1 if not set.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn get_property_max_content_width -->
The maximum content width of `scrolled_window`, or -1 if not set.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn set_property_max_content_width -->
The maximum content width of `scrolled_window`, or -1 if not set.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn get_property_min_content_height -->
The minimum content height of `scrolled_window`, or -1 if not set.
<!-- trait ScrolledWindowExt::fn set_property_min_content_height -->
The minimum content height of `scrolled_window`, or -1 if not set.
<!-- trait ScrolledWindowExt::fn get_property_min_content_width -->
The minimum content width of `scrolled_window`, or -1 if not set.
<!-- trait ScrolledWindowExt::fn set_property_min_content_width -->
The minimum content width of `scrolled_window`, or -1 if not set.
<!-- trait ScrolledWindowExt::fn get_property_overlay_scrolling -->
Whether overlay scrolling is enabled or not. If it is, the
scrollbars are only added as traditional widgets when a mouse
is present. Otherwise, they are overlayed on top of the content,
as narrow indicators.

Note that overlay scrolling can also be globally disabled, with
the `Settings::gtk-overlay-scrolling` setting.

Feature: `v3_16`

<!-- trait ScrolledWindowExt::fn set_property_overlay_scrolling -->
Whether overlay scrolling is enabled or not. If it is, the
scrollbars are only added as traditional widgets when a mouse
is present. Otherwise, they are overlayed on top of the content,
as narrow indicators.

Note that overlay scrolling can also be globally disabled, with
the `Settings::gtk-overlay-scrolling` setting.

Feature: `v3_16`

<!-- trait ScrolledWindowExt::fn get_property_propagate_natural_height -->
Whether the natural height of the child should be calculated and propagated
through the scrolled window’s requested natural height.

This is useful in cases where an attempt should be made to allocate exactly
enough space for the natural size of the child.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn set_property_propagate_natural_height -->
Whether the natural height of the child should be calculated and propagated
through the scrolled window’s requested natural height.

This is useful in cases where an attempt should be made to allocate exactly
enough space for the natural size of the child.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn get_property_propagate_natural_width -->
Whether the natural width of the child should be calculated and propagated
through the scrolled window’s requested natural width.

This is useful in cases where an attempt should be made to allocate exactly
enough space for the natural size of the child.

Feature: `v3_22`

<!-- trait ScrolledWindowExt::fn set_property_propagate_natural_width -->
Whether the natural width of the child should be calculated and propagated
through the scrolled window’s requested natural width.

This is useful in cases where an attempt should be made to allocate exactly
enough space for the natural size of the child.

Feature: `v3_22`

<!-- struct SearchBar -->
`SearchBar` is a container made to have a search entry (possibly
with additional connex widgets, such as drop-down menus, or buttons)
built-in. The search bar would appear when a search is started through
typing on the keyboard, or the application’s search mode is toggled on.

For keyboard presses to start a search, events will need to be
forwarded from the top-level window that contains the search bar.
See `SearchBarExt::handle_event` for example code. Common shortcuts
such as Ctrl+F should be handled as an application action, or through
the menu items.

You will also need to tell the search bar about which entry you
are using as your search entry using `SearchBarExt::connect_entry`.
The following example shows you how to create a more complex search
entry.

# CSS nodes

`SearchBar` has a single CSS node with name searchbar.

## Creating a search bar

[A simple example](https://gitlab.gnome.org/GNOME/gtk/blob/gtk-3-24/examples/search-bar.c)

# Implements

[`SearchBarExt`](trait.SearchBarExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait SearchBarExt -->
Trait containing all `SearchBar` methods.

# Implementors

[`SearchBar`](struct.SearchBar.html)
<!-- impl SearchBar::fn new -->
Creates a `SearchBar`. You will need to tell it about
which widget is going to be your text entry using
`SearchBarExt::connect_entry`.

# Returns

a new `SearchBar`
<!-- trait SearchBarExt::fn connect_entry -->
Connects the `Entry` widget passed as the one to be used in
this search bar. The entry should be a descendant of the search bar.
This is only required if the entry isn’t the direct child of the
search bar (as in our main example).
## `entry`
a `Entry`
<!-- trait SearchBarExt::fn get_search_mode -->
Returns whether the search mode is on or off.

# Returns

whether search mode is toggled on
<!-- trait SearchBarExt::fn get_show_close_button -->
Returns whether the close button is shown.

# Returns

whether the close button is shown
<!-- trait SearchBarExt::fn handle_event -->
This function should be called when the top-level
window which contains the search bar received a key event.

If the key event is handled by the search bar, the bar will
be shown, the entry populated with the entered text and `GDK_EVENT_STOP`
will be returned. The caller should ensure that events are
not propagated further.

If no entry has been connected to the search bar, using
`SearchBarExt::connect_entry`, this function will return
immediately with a warning.

## Showing the search bar on key presses


```C
static gboolean
on_key_press_event (GtkWidget *widget,
                    GdkEvent  *event,
                    gpointer   user_data)
{
  GtkSearchBar *bar = GTK_SEARCH_BAR (user_data);
  return gtk_search_bar_handle_event (bar, event);
}

static void
create_toplevel (void)
{
  GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  GtkWindow *search_bar = gtk_search_bar_new ();

 // Add more widgets to the window...

  g_signal_connect (window,
                   "key-press-event",
                    G_CALLBACK (on_key_press_event),
                    search_bar);
}
```
## `event`
a ``GdkEvent`` containing key press events

# Returns

`GDK_EVENT_STOP` if the key press event resulted
 in text being entered in the search entry (and revealing
 the search bar if necessary), `GDK_EVENT_PROPAGATE` otherwise.
<!-- trait SearchBarExt::fn set_search_mode -->
Switches the search mode on or off.
## `search_mode`
the new state of the search mode
<!-- trait SearchBarExt::fn set_show_close_button -->
Shows or hides the close button. Applications that
already have a “search” toggle button should not show a close
button in their search bar, as it duplicates the role of the
toggle button.
## `visible`
whether the close button will be shown or not
<!-- struct SearchEntry -->
`SearchEntry` is a subclass of `Entry` that has been
tailored for use as a search entry.

It will show an inactive symbolic “find” icon when the search
entry is empty, and a symbolic “clear” icon when there is text.
Clicking on the “clear” icon will empty the search entry.

Note that the search/clear icon is shown using a secondary
icon, and thus does not work if you are using the secondary
icon position for some other purpose.

To make filtering appear more reactive, it is a good idea to
not react to every change in the entry text immediately, but
only after a short delay. To support this, `SearchEntry`
emits the `SearchEntry::search-changed` signal which can
be used instead of the `Editable::changed` signal.

The `SearchEntry::previous-match`, `SearchEntry::next-match`
and `SearchEntry::stop-search` signals can be used to implement
moving between search results and ending the search.

Often, `SearchEntry` will be fed events by means of being
placed inside a `SearchBar`. If that is not the case,
you can use `SearchEntryExt::handle_event` to pass events.

# Implements

[`SearchEntryExt`](trait.SearchEntryExt.html), [`EntryExt`](trait.EntryExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`EditableExt`](trait.EditableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`EditableSignals`](prelude/trait.EditableSignals.html)
<!-- trait SearchEntryExt -->
Trait containing all `SearchEntry` methods.

# Implementors

[`SearchEntry`](struct.SearchEntry.html)
<!-- impl SearchEntry::fn new -->
Creates a `SearchEntry`, with a find icon when the search field is
empty, and a clear icon when it isn't.

# Returns

a new `SearchEntry`
<!-- trait SearchEntryExt::fn handle_event -->
This function should be called when the top-level window
which contains the search entry received a key event. If
the entry is part of a `SearchBar`, it is preferable
to call `SearchBarExt::handle_event` instead, which will
reveal the entry in addition to passing the event to this
function.

If the key event is handled by the search entry and starts
or continues a search, `GDK_EVENT_STOP` will be returned.
The caller should ensure that the entry is shown in this
case, and not propagate the event further.

Feature: `v3_16`

## `event`
a key event

# Returns

`GDK_EVENT_STOP` if the key press event resulted
 in a search beginning or continuing, `GDK_EVENT_PROPAGATE`
 otherwise.
<!-- trait SearchEntryExt::fn connect_next_match -->
The ::next-match signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a move to the next match
for the current search string.

Applications should connect to it, to implement moving between
matches.

The default bindings for this signal is Ctrl-g.

Feature: `v3_16`

<!-- trait SearchEntryExt::fn connect_previous_match -->
The ::previous-match signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a move to the previous match
for the current search string.

Applications should connect to it, to implement moving between
matches.

The default bindings for this signal is Ctrl-Shift-g.

Feature: `v3_16`

<!-- trait SearchEntryExt::fn connect_search_changed -->
The `SearchEntry::search-changed` signal is emitted with a short
delay of 150 milliseconds after the last change to the entry text.
<!-- trait SearchEntryExt::fn connect_stop_search -->
The ::stop-search signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user stops a search via keyboard input.

Applications should connect to it, to implement hiding the search
entry in this case.

The default bindings for this signal is Escape.

Feature: `v3_16`

<!-- struct SelectionData -->
<!-- impl SelectionData::fn copy -->
Makes a copy of a `SelectionData`-struct and its data.

# Returns

a pointer to a copy of `self`.
<!-- impl SelectionData::fn free -->
Frees a `SelectionData`-struct returned from
`SelectionData::copy`.
<!-- impl SelectionData::fn get_data -->
Retrieves the raw data of the selection.

# Returns

the raw data of the selection.
<!-- impl SelectionData::fn get_data_type -->
Retrieves the data type of the selection.

# Returns

the data type of the selection.
<!-- impl SelectionData::fn get_data_with_length -->
Retrieves the raw data of the selection along with its length.
## `length`
return location for length of the data segment

# Returns

the raw data of the selection
<!-- impl SelectionData::fn get_display -->
Retrieves the display of the selection.

# Returns

the display of the selection.
<!-- impl SelectionData::fn get_format -->
Retrieves the format of the selection.

# Returns

the format of the selection.
<!-- impl SelectionData::fn get_length -->
Retrieves the length of the raw data of the selection.

# Returns

the length of the data of the selection.
<!-- impl SelectionData::fn get_pixbuf -->
Gets the contents of the selection data as a `gdk_pixbuf::Pixbuf`.

# Returns

if the selection data
 contained a recognized image type and it could be converted to a
 `gdk_pixbuf::Pixbuf`, a newly allocated pixbuf is returned, otherwise
 `None`. If the result is non-`None` it must be freed with
 `gobject::ObjectExt::unref`.
<!-- impl SelectionData::fn get_selection -->
Retrieves the selection `gdk::Atom` of the selection data.

# Returns

the selection `gdk::Atom` of the selection data.
<!-- impl SelectionData::fn get_target -->
Retrieves the target of the selection.

# Returns

the target of the selection.
<!-- impl SelectionData::fn get_targets -->
Gets the contents of `self` as an array of targets.
This can be used to interpret the results of getting
the standard TARGETS target that is always supplied for
any selection.
## `targets`

 location to store an array of targets. The result stored
 here must be freed with `g_free`.
## `n_atoms`
location to store number of items in `targets`.

# Returns

`true` if `self` contains a valid
 array of targets, otherwise `false`.
<!-- impl SelectionData::fn get_text -->
Gets the contents of the selection data as a UTF-8 string.

# Returns

if the selection data contained a
 recognized text type and it could be converted to UTF-8, a newly
 allocated string containing the converted text, otherwise `None`.
 If the result is non-`None` it must be freed with `g_free`.
<!-- impl SelectionData::fn get_uris -->
Gets the contents of the selection data as array of URIs.

# Returns

if
 the selection data contains a list of
 URIs, a newly allocated `None`-terminated string array
 containing the URIs, otherwise `None`. If the result is
 non-`None` it must be freed with `g_strfreev`.
<!-- impl SelectionData::fn set -->
Stores new data into a `SelectionData` object. Should
only be called from a selection handler callback.
Zero-terminates the stored data.
## `type_`
the type of selection data
## `format`
format (number of bits in a unit)
## `data`
pointer to the data (will be copied)
## `length`
length of the data
<!-- impl SelectionData::fn set_pixbuf -->
Sets the contents of the selection from a `gdk_pixbuf::Pixbuf`
The pixbuf is converted to the form determined by
`self`->target.
## `pixbuf`
a `gdk_pixbuf::Pixbuf`

# Returns

`true` if the selection was successfully set,
 otherwise `false`.
<!-- impl SelectionData::fn set_text -->
Sets the contents of the selection from a UTF-8 encoded string.
The string is converted to the form determined by
`self`->target.
## `str`
a UTF-8 string
## `len`
the length of `str`, or -1 if `str` is nul-terminated.

# Returns

`true` if the selection was successfully set,
 otherwise `false`.
<!-- impl SelectionData::fn set_uris -->
Sets the contents of the selection from a list of URIs.
The string is converted to the form determined by
`self`->target.
## `uris`
a `None`-terminated array of
 strings holding URIs

# Returns

`true` if the selection was successfully set,
 otherwise `false`.
<!-- impl SelectionData::fn targets_include_image -->
Given a `SelectionData` object holding a list of targets,
determines if any of the targets in `targets` can be used to
provide a `gdk_pixbuf::Pixbuf`.
## `writable`
whether to accept only targets for which GTK+ knows
 how to convert a pixbuf into the format

# Returns

`true` if `self` holds a list of targets,
 and a suitable target for images is included, otherwise `false`.
<!-- impl SelectionData::fn targets_include_rich_text -->
Given a `SelectionData` object holding a list of targets,
determines if any of the targets in `targets` can be used to
provide rich text.
## `buffer`
a `TextBuffer`

# Returns

`true` if `self` holds a list of targets,
 and a suitable target for rich text is included,
 otherwise `false`.
<!-- impl SelectionData::fn targets_include_text -->
Given a `SelectionData` object holding a list of targets,
determines if any of the targets in `targets` can be used to
provide text.

# Returns

`true` if `self` holds a list of targets,
 and a suitable target for text is included, otherwise `false`.
<!-- impl SelectionData::fn targets_include_uri -->
Given a `SelectionData` object holding a list of targets,
determines if any of the targets in `targets` can be used to
provide a list or URIs.

# Returns

`true` if `self` holds a list of targets,
 and a suitable target for URI lists is included, otherwise `false`.
<!-- enum SelectionMode -->
Used to control what selections users are allowed to make.
<!-- enum SelectionMode::variant None -->
No selection is possible.
<!-- enum SelectionMode::variant Single -->
Zero or one element may be selected.
<!-- enum SelectionMode::variant Browse -->
Exactly one element is selected.
 In some circumstances, such as initially or during a search
 operation, it’s possible for no element to be selected with
 `SelectionMode::Browse`. What is really enforced is that the user
 can’t deselect a currently selected element except by selecting
 another element.
<!-- enum SelectionMode::variant Multiple -->
Any number of elements may be selected.
 The Ctrl key may be used to enlarge the selection, and Shift
 key to select between the focus and the child pointed to.
 Some widgets may also allow Click-drag to select a range of elements.
<!-- enum SensitivityType -->
Determines how GTK+ handles the sensitivity of stepper arrows
at the end of range widgets.
<!-- enum SensitivityType::variant Auto -->
The arrow is made insensitive if the
 thumb is at the end
<!-- enum SensitivityType::variant On -->
The arrow is always sensitive
<!-- enum SensitivityType::variant Off -->
The arrow is always insensitive
<!-- struct Separator -->
`Separator` is a horizontal or vertical separator widget, depending on the
value of the `Orientable:orientation` property, used to group the widgets
within a window. It displays a line with a shadow to make it appear sunken
into the interface.

# CSS nodes

`Separator` has a single CSS node with name separator. The node
gets one of the .horizontal or .vertical style classes.

# Implements

[`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl Separator::fn new -->
Creates a new `Separator` with the given orientation.
## `orientation`
the separator’s orientation.

# Returns

a new `Separator`.
<!-- struct SeparatorMenuItem -->
The `SeparatorMenuItem` is a separator used to group
items within a menu. It displays a horizontal line with a shadow to
make it appear sunken into the interface.

# CSS nodes

`SeparatorMenuItem` has a single CSS node with name separator.

# Implements

[`GtkMenuItemExt`](trait.GtkMenuItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl SeparatorMenuItem::fn new -->
Creates a new `SeparatorMenuItem`.

# Returns

a new `SeparatorMenuItem`.
<!-- struct SeparatorToolItem -->
A `SeparatorToolItem` is a `ToolItem` that separates groups of other
``GtkToolItems``. Depending on the theme, a `SeparatorToolItem` will
often look like a vertical line on horizontally docked toolbars.

If the `Toolbar` child property “expand” is `true` and the property
`SeparatorToolItem:draw` is `false`, a `SeparatorToolItem` will act as
a “spring” that forces other items to the ends of the toolbar.

Use `SeparatorToolItem::new` to create a new `SeparatorToolItem`.

# CSS nodes

`SeparatorToolItem` has a single CSS node with name separator.

# Implements

[`SeparatorToolItemExt`](trait.SeparatorToolItemExt.html), [`ToolItemExt`](trait.ToolItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait SeparatorToolItemExt -->
Trait containing all `SeparatorToolItem` methods.

# Implementors

[`SeparatorToolItem`](struct.SeparatorToolItem.html)
<!-- impl SeparatorToolItem::fn new -->
Create a new `SeparatorToolItem`

# Returns

the new `SeparatorToolItem`
<!-- trait SeparatorToolItemExt::fn get_draw -->
Returns whether `self` is drawn as a line, or just blank.
See `SeparatorToolItemExt::set_draw`.

# Returns

`true` if `self` is drawn as a line, or just blank.
<!-- trait SeparatorToolItemExt::fn set_draw -->
Whether `self` is drawn as a vertical line, or just blank.
Setting this to `false` along with `ToolItemExt::set_expand` is useful
to create an item that forces following items to the end of the toolbar.
## `draw`
whether `self` is drawn as a vertical line
<!-- struct Settings -->
`Settings` provide a mechanism to share global settings between
applications.

On the X window system, this sharing is realized by an
[XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec)
manager that is usually part of the desktop environment, along with
utilities that let the user change these settings. In the absence of
an Xsettings manager, GTK+ reads default values for settings from
`settings.ini` files in
`/etc/gtk-3.0`, `$XDG_CONFIG_DIRS/gtk-3.0`
and `$XDG_CONFIG_HOME/gtk-3.0`.
These files must be valid key files (see `glib::KeyFile`), and have
a section called Settings. Themes can also provide default values
for settings by installing a `settings.ini` file
next to their `gtk.css` file.

Applications can override system-wide settings by setting the property
of the `Settings` object with `gobject::ObjectExt::set`. This should be restricted
to special cases though; `Settings` are not meant as an application
configuration facility. When doing so, you need to be aware that settings
that are specific to individual widgets may not be available before the
widget type has been realized at least once. The following example
demonstrates a way to do this:

```C
  gtk_init (&argc, &argv);

  // make sure the type is realized
  g_type_class_unref (g_type_class_ref (GTK_TYPE_IMAGE_MENU_ITEM));

  g_object_set (gtk_settings_get_default (), "gtk-enable-animations", FALSE, NULL);
```

There is one `Settings` instance per screen. It can be obtained with
`Settings::get_for_screen`, but in many cases, it is more convenient
to use `WidgetExt::get_settings`. `Settings::get_default` returns the
`Settings` instance for the default screen.

# Implements

[`SettingsExt`](trait.SettingsExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`StyleProviderExt`](trait.StyleProviderExt.html)
<!-- trait SettingsExt -->
Trait containing all `Settings` methods.

# Implementors

[`Settings`](struct.Settings.html)
<!-- impl Settings::fn get_default -->
Gets the `Settings` object for the default GDK screen, creating
it if necessary. See `Settings::get_for_screen`.

# Returns

a `Settings` object. If there is
no default screen, then returns `None`.
<!-- impl Settings::fn get_for_screen -->
Gets the `Settings` object for `screen`, creating it if necessary.
## `screen`
a `gdk::Screen`.

# Returns

a `Settings` object.
<!-- impl Settings::fn install_property -->

# Deprecated since 3.16

This function is not useful outside GTK+.
<!-- impl Settings::fn install_property_parser -->

# Deprecated since 3.16

This function is not useful outside GTK+.
<!-- trait SettingsExt::fn reset_property -->
Undoes the effect of calling `gobject::ObjectExt::set` to install an
application-specific value for a setting. After this call,
the setting will again follow the session-wide value for
this setting.

Feature: `v3_20`

## `name`
the name of the setting to reset
<!-- trait SettingsExt::fn set_double_property -->

# Deprecated since 3.16

Use `gobject::ObjectExt::set` instead.
<!-- trait SettingsExt::fn set_long_property -->

# Deprecated since 3.16

Use `gobject::ObjectExt::set` instead.
<!-- trait SettingsExt::fn set_property_value -->

# Deprecated since 3.16

Use `gobject::ObjectExt::set` instead.
<!-- trait SettingsExt::fn set_string_property -->

# Deprecated since 3.16

Use `gobject::ObjectExt::set` instead.
<!-- trait SettingsExt::fn get_property_gtk_alternative_sort_arrows -->
Controls the direction of the sort indicators in sorted list and tree
views. By default an arrow pointing down means the column is sorted
in ascending order. When set to `true`, this order will be inverted.
<!-- trait SettingsExt::fn set_property_gtk_alternative_sort_arrows -->
Controls the direction of the sort indicators in sorted list and tree
views. By default an arrow pointing down means the column is sorted
in ascending order. When set to `true`, this order will be inverted.
<!-- trait SettingsExt::fn get_property_gtk_application_prefer_dark_theme -->
Whether the application prefers to use a dark theme. If a GTK+ theme
includes a dark variant, it will be used instead of the configured
theme.

Some applications benefit from minimizing the amount of light pollution that
interferes with the content. Good candidates for dark themes are photo and
video editors that make the actual content get all the attention and minimize
the distraction of the chrome.

Dark themes should not be used for documents, where large spaces are white/light
and the dark chrome creates too much contrast (web browser, text editor...).
<!-- trait SettingsExt::fn set_property_gtk_application_prefer_dark_theme -->
Whether the application prefers to use a dark theme. If a GTK+ theme
includes a dark variant, it will be used instead of the configured
theme.

Some applications benefit from minimizing the amount of light pollution that
interferes with the content. Good candidates for dark themes are photo and
video editors that make the actual content get all the attention and minimize
the distraction of the chrome.

Dark themes should not be used for documents, where large spaces are white/light
and the dark chrome creates too much contrast (web browser, text editor...).
<!-- trait SettingsExt::fn get_property_gtk_cursor_blink -->
Whether the cursor should blink.

Also see the `Settings:gtk-cursor-blink-timeout` setting,
which allows more flexible control over cursor blinking.
<!-- trait SettingsExt::fn set_property_gtk_cursor_blink -->
Whether the cursor should blink.

Also see the `Settings:gtk-cursor-blink-timeout` setting,
which allows more flexible control over cursor blinking.
<!-- trait SettingsExt::fn get_property_gtk_cursor_blink_timeout -->
Time after which the cursor stops blinking, in seconds.
The timer is reset after each user interaction.

Setting this to zero has the same effect as setting
`Settings:gtk-cursor-blink` to `false`.
<!-- trait SettingsExt::fn set_property_gtk_cursor_blink_timeout -->
Time after which the cursor stops blinking, in seconds.
The timer is reset after each user interaction.

Setting this to zero has the same effect as setting
`Settings:gtk-cursor-blink` to `false`.
<!-- trait SettingsExt::fn get_property_gtk_decoration_layout -->
This setting determines which buttons should be put in the
titlebar of client-side decorated windows, and whether they
should be placed at the left of right.

The format of the string is button names, separated by commas.
A colon separates the buttons that should appear on the left
from those on the right. Recognized button names are minimize,
maximize, close, icon (the window icon) and menu (a menu button
for the fallback app menu).

For example, "menu:minimize,maximize,close" specifies a menu
on the left, and minimize, maximize and close buttons on the right.

Note that buttons will only be shown when they are meaningful.
E.g. a menu button only appears when the desktop shell does not
show the app menu, and a close button only appears on a window
that can be closed.

Also note that the setting can be overridden with the
`HeaderBar:decoration-layout` property.
<!-- trait SettingsExt::fn set_property_gtk_decoration_layout -->
This setting determines which buttons should be put in the
titlebar of client-side decorated windows, and whether they
should be placed at the left of right.

The format of the string is button names, separated by commas.
A colon separates the buttons that should appear on the left
from those on the right. Recognized button names are minimize,
maximize, close, icon (the window icon) and menu (a menu button
for the fallback app menu).

For example, "menu:minimize,maximize,close" specifies a menu
on the left, and minimize, maximize and close buttons on the right.

Note that buttons will only be shown when they are meaningful.
E.g. a menu button only appears when the desktop shell does not
show the app menu, and a close button only appears on a window
that can be closed.

Also note that the setting can be overridden with the
`HeaderBar:decoration-layout` property.
<!-- trait SettingsExt::fn get_property_gtk_dialogs_use_header -->
Whether builtin GTK+ dialogs such as the file chooser, the
color chooser or the font chooser will use a header bar at
the top to show action widgets, or an action area at the bottom.

This setting does not affect custom dialogs using `Dialog`
directly, or message dialogs.
<!-- trait SettingsExt::fn set_property_gtk_dialogs_use_header -->
Whether builtin GTK+ dialogs such as the file chooser, the
color chooser or the font chooser will use a header bar at
the top to show action widgets, or an action area at the bottom.

This setting does not affect custom dialogs using `Dialog`
directly, or message dialogs.
<!-- trait SettingsExt::fn get_property_gtk_enable_accels -->
Whether menu items should have visible accelerators which can be
activated.
<!-- trait SettingsExt::fn set_property_gtk_enable_accels -->
Whether menu items should have visible accelerators which can be
activated.
<!-- trait SettingsExt::fn get_property_gtk_enable_event_sounds -->
Whether to play any event sounds at all.

See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec)
for more information on event sounds and sound themes.

GTK+ itself does not support event sounds, you have to use a loadable
module like the one that comes with libcanberra.
<!-- trait SettingsExt::fn set_property_gtk_enable_event_sounds -->
Whether to play any event sounds at all.

See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec)
for more information on event sounds and sound themes.

GTK+ itself does not support event sounds, you have to use a loadable
module like the one that comes with libcanberra.
<!-- trait SettingsExt::fn get_property_gtk_enable_input_feedback_sounds -->
Whether to play event sounds as feedback to user input.

See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec)
for more information on event sounds and sound themes.

GTK+ itself does not support event sounds, you have to use a loadable
module like the one that comes with libcanberra.
<!-- trait SettingsExt::fn set_property_gtk_enable_input_feedback_sounds -->
Whether to play event sounds as feedback to user input.

See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec)
for more information on event sounds and sound themes.

GTK+ itself does not support event sounds, you have to use a loadable
module like the one that comes with libcanberra.
<!-- trait SettingsExt::fn get_property_gtk_enable_primary_paste -->
Whether a middle click on a mouse should paste the
'PRIMARY' clipboard content at the cursor location.
<!-- trait SettingsExt::fn set_property_gtk_enable_primary_paste -->
Whether a middle click on a mouse should paste the
'PRIMARY' clipboard content at the cursor location.
<!-- trait SettingsExt::fn get_property_gtk_entry_password_hint_timeout -->
How long to show the last input character in hidden
entries. This value is in milliseconds. 0 disables showing the
last char. 600 is a good value for enabling it.
<!-- trait SettingsExt::fn set_property_gtk_entry_password_hint_timeout -->
How long to show the last input character in hidden
entries. This value is in milliseconds. 0 disables showing the
last char. 600 is a good value for enabling it.
<!-- trait SettingsExt::fn get_property_gtk_error_bell -->
When `true`, keyboard navigation and other input-related errors
will cause a beep. Since the error bell is implemented using
`gdk::WindowExt::beep`, the windowing system may offer ways to
configure the error bell in many ways, such as flashing the
window or similar visual effects.
<!-- trait SettingsExt::fn set_property_gtk_error_bell -->
When `true`, keyboard navigation and other input-related errors
will cause a beep. Since the error bell is implemented using
`gdk::WindowExt::beep`, the windowing system may offer ways to
configure the error bell in many ways, such as flashing the
window or similar visual effects.
<!-- trait SettingsExt::fn get_property_gtk_font_name -->
The default font to use. GTK+ uses the family name and size from this string.
<!-- trait SettingsExt::fn set_property_gtk_font_name -->
The default font to use. GTK+ uses the family name and size from this string.
<!-- trait SettingsExt::fn get_property_gtk_im_module -->
Which IM (input method) module should be used by default. This is the
input method that will be used if the user has not explicitly chosen
another input method from the IM context menu.
This also can be a colon-separated list of input methods, which GTK+
will try in turn until it finds one available on the system.

See `IMContext`.
<!-- trait SettingsExt::fn set_property_gtk_im_module -->
Which IM (input method) module should be used by default. This is the
input method that will be used if the user has not explicitly chosen
another input method from the IM context menu.
This also can be a colon-separated list of input methods, which GTK+
will try in turn until it finds one available on the system.

See `IMContext`.
<!-- trait SettingsExt::fn get_property_gtk_keynav_use_caret -->
Whether GTK+ should make sure that text can be navigated with
a caret, even if it is not editable. This is useful when using
a screen reader.

Feature: `v3_20`

<!-- trait SettingsExt::fn set_property_gtk_keynav_use_caret -->
Whether GTK+ should make sure that text can be navigated with
a caret, even if it is not editable. This is useful when using
a screen reader.

Feature: `v3_20`

<!-- trait SettingsExt::fn get_property_gtk_long_press_time -->
The time for a button or touch press to be considered a "long press".
<!-- trait SettingsExt::fn set_property_gtk_long_press_time -->
The time for a button or touch press to be considered a "long press".
<!-- trait SettingsExt::fn get_property_gtk_overlay_scrolling -->
Whether scrolled windows may use overlayed scrolling indicators.
If this is set to `false`, scrolled windows will have permanent
scrollbars.

Feature: `v3_24_9`

<!-- trait SettingsExt::fn set_property_gtk_overlay_scrolling -->
Whether scrolled windows may use overlayed scrolling indicators.
If this is set to `false`, scrolled windows will have permanent
scrollbars.

Feature: `v3_24_9`

<!-- trait SettingsExt::fn get_property_gtk_primary_button_warps_slider -->
If the value of this setting is `true`, clicking the primary button in a
`Range` trough will move the slider, and hence set the range’s value, to
the point that you clicked. If it is `false`, a primary click will cause the
slider/value to move by the range’s page-size towards the point clicked.

Whichever action you choose for the primary button, the other action will
be available by holding Shift and primary-clicking, or (since GTK+ 3.22.25)
clicking the middle mouse button.
<!-- trait SettingsExt::fn set_property_gtk_primary_button_warps_slider -->
If the value of this setting is `true`, clicking the primary button in a
`Range` trough will move the slider, and hence set the range’s value, to
the point that you clicked. If it is `false`, a primary click will cause the
slider/value to move by the range’s page-size towards the point clicked.

Whichever action you choose for the primary button, the other action will
be available by holding Shift and primary-clicking, or (since GTK+ 3.22.25)
clicking the middle mouse button.
<!-- trait SettingsExt::fn get_property_gtk_print_backends -->
A comma-separated list of print backends to use in the print
dialog. Available print backends depend on the GTK+ installation,
and may include "file", "cups", "lpr" or "papi".
<!-- trait SettingsExt::fn set_property_gtk_print_backends -->
A comma-separated list of print backends to use in the print
dialog. Available print backends depend on the GTK+ installation,
and may include "file", "cups", "lpr" or "papi".
<!-- trait SettingsExt::fn get_property_gtk_print_preview_command -->
A command to run for displaying the print preview. The command
should contain a `%f` placeholder, which will get replaced by
the path to the pdf file. The command may also contain a `%s`
placeholder, which will get replaced by the path to a file
containing the print settings in the format produced by
`PrintSettings::to_file`.

The preview application is responsible for removing the pdf file
and the print settings file when it is done.
<!-- trait SettingsExt::fn set_property_gtk_print_preview_command -->
A command to run for displaying the print preview. The command
should contain a `%f` placeholder, which will get replaced by
the path to the pdf file. The command may also contain a `%s`
placeholder, which will get replaced by the path to a file
containing the print settings in the format produced by
`PrintSettings::to_file`.

The preview application is responsible for removing the pdf file
and the print settings file when it is done.
<!-- trait SettingsExt::fn get_property_gtk_recent_files_enabled -->
Whether GTK+ should keep track of items inside the recently used
resources list. If set to `false`, the list will always be empty.
<!-- trait SettingsExt::fn set_property_gtk_recent_files_enabled -->
Whether GTK+ should keep track of items inside the recently used
resources list. If set to `false`, the list will always be empty.
<!-- trait SettingsExt::fn get_property_gtk_recent_files_max_age -->
The maximum age, in days, of the items inside the recently used
resources list. Items older than this setting will be excised
from the list. If set to 0, the list will always be empty; if
set to -1, no item will be removed.
<!-- trait SettingsExt::fn set_property_gtk_recent_files_max_age -->
The maximum age, in days, of the items inside the recently used
resources list. Items older than this setting will be excised
from the list. If set to 0, the list will always be empty; if
set to -1, no item will be removed.
<!-- trait SettingsExt::fn get_property_gtk_sound_theme_name -->
The XDG sound theme to use for event sounds.

See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec)
for more information on event sounds and sound themes.

GTK+ itself does not support event sounds, you have to use a loadable
module like the one that comes with libcanberra.
<!-- trait SettingsExt::fn set_property_gtk_sound_theme_name -->
The XDG sound theme to use for event sounds.

See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec)
for more information on event sounds and sound themes.

GTK+ itself does not support event sounds, you have to use a loadable
module like the one that comes with libcanberra.
<!-- trait SettingsExt::fn get_property_gtk_titlebar_double_click -->
This setting determines the action to take when a double-click
occurs on the titlebar of client-side decorated windows.

Recognized actions are minimize, toggle-maximize, menu, lower
or none.
<!-- trait SettingsExt::fn set_property_gtk_titlebar_double_click -->
This setting determines the action to take when a double-click
occurs on the titlebar of client-side decorated windows.

Recognized actions are minimize, toggle-maximize, menu, lower
or none.
<!-- trait SettingsExt::fn get_property_gtk_titlebar_middle_click -->
This setting determines the action to take when a middle-click
occurs on the titlebar of client-side decorated windows.

Recognized actions are minimize, toggle-maximize, menu, lower
or none.
<!-- trait SettingsExt::fn set_property_gtk_titlebar_middle_click -->
This setting determines the action to take when a middle-click
occurs on the titlebar of client-side decorated windows.

Recognized actions are minimize, toggle-maximize, menu, lower
or none.
<!-- trait SettingsExt::fn get_property_gtk_titlebar_right_click -->
This setting determines the action to take when a right-click
occurs on the titlebar of client-side decorated windows.

Recognized actions are minimize, toggle-maximize, menu, lower
or none.
<!-- trait SettingsExt::fn set_property_gtk_titlebar_right_click -->
This setting determines the action to take when a right-click
occurs on the titlebar of client-side decorated windows.

Recognized actions are minimize, toggle-maximize, menu, lower
or none.
<!-- enum ShadowType -->
Used to change the appearance of an outline typically provided by a `Frame`.

Note that many themes do not differentiate the appearance of the
various shadow types: Either their is no visible shadow (`ShadowType::None`),
or there is (any other value).
<!-- enum ShadowType::variant None -->
No outline.
<!-- enum ShadowType::variant In -->
The outline is bevelled inwards.
<!-- enum ShadowType::variant Out -->
The outline is bevelled outwards like a button.
<!-- enum ShadowType::variant EtchedIn -->
The outline has a sunken 3d appearance.
<!-- enum ShadowType::variant EtchedOut -->
The outline has a raised 3d appearance.
<!-- struct ShortcutLabel -->
`ShortcutLabel` is a widget that represents a single keyboard shortcut or gesture
in the user interface.

Feature: `v3_22`

# Implements

[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl ShortcutLabel::fn new -->
Creates a new `ShortcutLabel` with `accelerator` set.

Feature: `v3_22`

## `accelerator`
the initial accelerator

# Returns

a newly-allocated `ShortcutLabel`
<!-- impl ShortcutLabel::fn get_accelerator -->
Retrieves the current accelerator of `self`.

Feature: `v3_22`


# Returns

the current accelerator.
<!-- impl ShortcutLabel::fn get_disabled_text -->
Retrieves the text that is displayed when no accelerator is set.

Feature: `v3_22`


# Returns

the current text displayed when no
accelerator is set.
<!-- impl ShortcutLabel::fn set_accelerator -->
Sets the accelerator to be displayed by `self`.

Feature: `v3_22`

## `accelerator`
the new accelerator
<!-- impl ShortcutLabel::fn set_disabled_text -->
Sets the text to be displayed by `self` when no accelerator is set.

Feature: `v3_22`

## `disabled_text`
the text to be displayed when no accelerator is set
<!-- impl ShortcutLabel::fn get_property_accelerator -->
The accelerator that `self_` displays. See `ShortcutsShortcut:accelerator`
for the accepted syntax.

Feature: `v3_22`

<!-- impl ShortcutLabel::fn set_property_accelerator -->
The accelerator that `self_` displays. See `ShortcutsShortcut:accelerator`
for the accepted syntax.

Feature: `v3_22`

<!-- impl ShortcutLabel::fn get_property_disabled_text -->
The text that is displayed when no accelerator is set.

Feature: `v3_22`

<!-- impl ShortcutLabel::fn set_property_disabled_text -->
The text that is displayed when no accelerator is set.

Feature: `v3_22`

<!-- enum ShortcutType -->
`ShortcutType` specifies the kind of shortcut that is being described.
More values may be added to this enumeration over time.
<!-- enum ShortcutType::variant Accelerator -->
The shortcut is a keyboard accelerator. The `ShortcutsShortcut:accelerator`
 property will be used.
<!-- enum ShortcutType::variant GesturePinch -->
The shortcut is a pinch gesture. GTK+ provides an icon and subtitle.
<!-- enum ShortcutType::variant GestureStretch -->
The shortcut is a stretch gesture. GTK+ provides an icon and subtitle.
<!-- enum ShortcutType::variant GestureRotateClockwise -->
The shortcut is a clockwise rotation gesture. GTK+ provides an icon and subtitle.
<!-- enum ShortcutType::variant GestureRotateCounterclockwise -->
The shortcut is a counterclockwise rotation gesture. GTK+ provides an icon and subtitle.
<!-- enum ShortcutType::variant GestureTwoFingerSwipeLeft -->
The shortcut is a two-finger swipe gesture. GTK+ provides an icon and subtitle.
<!-- enum ShortcutType::variant GestureTwoFingerSwipeRight -->
The shortcut is a two-finger swipe gesture. GTK+ provides an icon and subtitle.
<!-- enum ShortcutType::variant Gesture -->
The shortcut is a gesture. The `ShortcutsShortcut:icon` property will be
 used.

Feature: `v3_20`

<!-- struct ShortcutsGroup -->
A `ShortcutsGroup` represents a group of related keyboard shortcuts
or gestures. The group has a title. It may optionally be associated with
a view of the application, which can be used to show only relevant shortcuts
depending on the application context.

This widget is only meant to be used with `ShortcutsWindow`.

Feature: `v3_20`

# Implements

[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl ShortcutsGroup::fn set_property_accel_size_group -->
The size group for the accelerator portion of shortcuts in this group.

This is used internally by GTK+, and must not be modified by applications.
<!-- impl ShortcutsGroup::fn get_property_height -->
A rough measure for the number of lines in this group.

This is used internally by GTK+, and is not useful for applications.
<!-- impl ShortcutsGroup::fn get_property_title -->
The title for this group of shortcuts.
<!-- impl ShortcutsGroup::fn set_property_title -->
The title for this group of shortcuts.
<!-- impl ShortcutsGroup::fn set_property_title_size_group -->
The size group for the textual portion of shortcuts in this group.

This is used internally by GTK+, and must not be modified by applications.
<!-- impl ShortcutsGroup::fn get_property_view -->
An optional view that the shortcuts in this group are relevant for.
The group will be hidden if the `ShortcutsWindow:view-name` property
does not match the view of this group.

Set this to `None` to make the group always visible.
<!-- impl ShortcutsGroup::fn set_property_view -->
An optional view that the shortcuts in this group are relevant for.
The group will be hidden if the `ShortcutsWindow:view-name` property
does not match the view of this group.

Set this to `None` to make the group always visible.
<!-- struct ShortcutsSection -->
A `ShortcutsSection` collects all the keyboard shortcuts and gestures
for a major application mode. If your application needs multiple sections,
you should give each section a unique `ShortcutsSection:section-name` and
a `ShortcutsSection:title` that can be shown in the section selector of
the `ShortcutsWindow`.

The `ShortcutsSection:max-height` property can be used to influence how
the groups in the section are distributed over pages and columns.

This widget is only meant to be used with `ShortcutsWindow`.

Feature: `v3_20`

# Implements

[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl ShortcutsSection::fn get_property_max_height -->
The maximum number of lines to allow per column. This property can
be used to influence how the groups in this section are distributed
across pages and columns. The default value of 15 should work in
most cases.
<!-- impl ShortcutsSection::fn set_property_max_height -->
The maximum number of lines to allow per column. This property can
be used to influence how the groups in this section are distributed
across pages and columns. The default value of 15 should work in
most cases.
<!-- impl ShortcutsSection::fn get_property_section_name -->
A unique name to identify this section among the sections
added to the `ShortcutsWindow`. Setting the `ShortcutsWindow:section-name`
property to this string will make this section shown in the
`ShortcutsWindow`.
<!-- impl ShortcutsSection::fn set_property_section_name -->
A unique name to identify this section among the sections
added to the `ShortcutsWindow`. Setting the `ShortcutsWindow:section-name`
property to this string will make this section shown in the
`ShortcutsWindow`.
<!-- impl ShortcutsSection::fn get_property_title -->
The string to show in the section selector of the `ShortcutsWindow`
for this section. If there is only one section, you don't need to
set a title, since the section selector will not be shown in this case.
<!-- impl ShortcutsSection::fn set_property_title -->
The string to show in the section selector of the `ShortcutsWindow`
for this section. If there is only one section, you don't need to
set a title, since the section selector will not be shown in this case.
<!-- impl ShortcutsSection::fn get_property_view_name -->
A view name to filter the groups in this section by.
See `ShortcutsGroup:view`.

Applications are expected to use the `ShortcutsWindow:view-name`
property for this purpose.
<!-- impl ShortcutsSection::fn set_property_view_name -->
A view name to filter the groups in this section by.
See `ShortcutsGroup:view`.

Applications are expected to use the `ShortcutsWindow:view-name`
property for this purpose.
<!-- struct ShortcutsShortcut -->
A `ShortcutsShortcut` represents a single keyboard shortcut or gesture
with a short text. This widget is only meant to be used with `ShortcutsWindow`.

Feature: `v3_20`

# Implements

[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- impl ShortcutsShortcut::fn set_property_accel_size_group -->
The size group for the accelerator portion of this shortcut.

This is used internally by GTK+, and must not be modified by applications.
<!-- impl ShortcutsShortcut::fn get_property_accelerator -->
The accelerator(s) represented by this object. This property is used
if `ShortcutsShortcut:shortcut-type` is set to `ShortcutType::Accelerator`.

The syntax of this property is (an extension of) the syntax understood by
`gtk_accelerator_parse`. Multiple accelerators can be specified by separating
them with a space, but keep in mind that the available width is limited.
It is also possible to specify ranges of shortcuts, using ... between the keys.
Sequences of keys can be specified using a + or & between the keys.

Examples:
- A single shortcut: `<ctl>``<alt>`delete
- Two alternative shortcuts: `<shift>`a Home
- A range of shortcuts: `<alt>`1...`<alt>`9
- Several keys pressed together: Control_L&Control_R
- A sequence of shortcuts or keys: `<ctl>`c+`<ctl>`x

Use + instead of & when the keys may (or have to be) pressed sequentially (e.g
use t+t for 'press the t key twice').

Note that <, > and & need to be escaped as &lt;, &gt; and &amp; when used
in .ui files.
<!-- impl ShortcutsShortcut::fn set_property_accelerator -->
The accelerator(s) represented by this object. This property is used
if `ShortcutsShortcut:shortcut-type` is set to `ShortcutType::Accelerator`.

The syntax of this property is (an extension of) the syntax understood by
`gtk_accelerator_parse`. Multiple accelerators can be specified by separating
them with a space, but keep in mind that the available width is limited.
It is also possible to specify ranges of shortcuts, using ... between the keys.
Sequences of keys can be specified using a + or & between the keys.

Examples:
- A single shortcut: `<ctl>``<alt>`delete
- Two alternative shortcuts: `<shift>`a Home
- A range of shortcuts: `<alt>`1...`<alt>`9
- Several keys pressed together: Control_L&Control_R
- A sequence of shortcuts or keys: `<ctl>`c+`<ctl>`x

Use + instead of & when the keys may (or have to be) pressed sequentially (e.g
use t+t for 'press the t key twice').

Note that <, > and & need to be escaped as &lt;, &gt; and &amp; when used
in .ui files.
<!-- impl ShortcutsShortcut::fn get_property_action_name -->
A detailed action name. If this is set for a shortcut
of type `ShortcutType::Accelerator`, then GTK+ will use
the accelerators that are associated with the action
via `GtkApplicationExt::set_accels_for_action`, and setting
`ShortcutsShortcut::accelerator` is not necessary.

Feature: `v3_22`

<!-- impl ShortcutsShortcut::fn set_property_action_name -->
A detailed action name. If this is set for a shortcut
of type `ShortcutType::Accelerator`, then GTK+ will use
the accelerators that are associated with the action
via `GtkApplicationExt::set_accels_for_action`, and setting
`ShortcutsShortcut::accelerator` is not necessary.

Feature: `v3_22`

<!-- impl ShortcutsShortcut::fn get_property_direction -->
The text direction for which this shortcut is active. If the shortcut
is used regardless of the text direction, set this property to
`TextDirection::None`.
<!-- impl ShortcutsShortcut::fn set_property_direction -->
The text direction for which this shortcut is active. If the shortcut
is used regardless of the text direction, set this property to
`TextDirection::None`.
<!-- impl ShortcutsShortcut::fn get_property_icon -->
An icon to represent the shortcut or gesture. This property is used if
`ShortcutsShortcut:shortcut-type` is set to `ShortcutType::Gesture`.
For the other predefined gesture types, GTK+ provides an icon on its own.
<!-- impl ShortcutsShortcut::fn set_property_icon -->
An icon to represent the shortcut or gesture. This property is used if
`ShortcutsShortcut:shortcut-type` is set to `ShortcutType::Gesture`.
For the other predefined gesture types, GTK+ provides an icon on its own.
<!-- impl ShortcutsShortcut::fn get_property_icon_set -->
`true` if an icon has been set.
<!-- impl ShortcutsShortcut::fn set_property_icon_set -->
`true` if an icon has been set.
<!-- impl ShortcutsShortcut::fn get_property_shortcut_type -->
The type of shortcut that is represented.
<!-- impl ShortcutsShortcut::fn set_property_shortcut_type -->
The type of shortcut that is represented.
<!-- impl ShortcutsShortcut::fn get_property_subtitle -->
The subtitle for the shortcut or gesture.

This is typically used for gestures and should be a short, one-line
text that describes the gesture itself. For the predefined gesture
types, GTK+ provides a subtitle on its own.
<!-- impl ShortcutsShortcut::fn set_property_subtitle -->
The subtitle for the shortcut or gesture.

This is typically used for gestures and should be a short, one-line
text that describes the gesture itself. For the predefined gesture
types, GTK+ provides a subtitle on its own.
<!-- impl ShortcutsShortcut::fn get_property_subtitle_set -->
`true` if a subtitle has been set.
<!-- impl ShortcutsShortcut::fn set_property_subtitle_set -->
`true` if a subtitle has been set.
<!-- impl ShortcutsShortcut::fn get_property_title -->
The textual description for the shortcut or gesture represented by
this object. This should be a short string that can fit in a single line.
<!-- impl ShortcutsShortcut::fn set_property_title -->
The textual description for the shortcut or gesture represented by
this object. This should be a short string that can fit in a single line.
<!-- impl ShortcutsShortcut::fn set_property_title_size_group -->
The size group for the textual portion of this shortcut.

This is used internally by GTK+, and must not be modified by applications.
<!-- struct ShortcutsWindow -->
A `ShortcutsWindow` shows brief information about the keyboard shortcuts
and gestures of an application. The shortcuts can be grouped, and you can
have multiple sections in this window, corresponding to the major modes of
your application.

Additionally, the shortcuts can be filtered by the current view, to avoid
showing information that is not relevant in the current application context.

The recommended way to construct a `ShortcutsWindow` is with `Builder`,
by populating a `ShortcutsWindow` with one or more `ShortcutsSection`
objects, which contain ``GtkShortcutsGroups`` that in turn contain objects of
class `ShortcutsShortcut`.

# A simple example:

![](gedit-shortcuts.png)

This example has as single section. As you can see, the shortcut groups
are arranged in columns, and spread across several pages if there are too
many to find on a single page.

The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-gedit.ui).

# An example with multiple views:

![](clocks-shortcuts.png)

This example shows a `ShortcutsWindow` that has been configured to show only
the shortcuts relevant to the "stopwatch" view.

The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-clocks.ui).

# An example with multiple sections:

![](builder-shortcuts.png)

This example shows a `ShortcutsWindow` with two sections, "Editor Shortcuts"
and "Terminal Shortcuts".

The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-builder.ui).

Feature: `v3_20`

# Implements

[`ShortcutsWindowExt`](trait.ShortcutsWindowExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ShortcutsWindowExt -->
Trait containing all `ShortcutsWindow` methods.

Feature: `v3_20`

# Implementors

[`ShortcutsWindow`](struct.ShortcutsWindow.html)
<!-- trait ShortcutsWindowExt::fn connect_close -->
The ::close signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user uses a keybinding to close
the window.

The default binding for this signal is the Escape key.
<!-- trait ShortcutsWindowExt::fn connect_search -->
The ::search signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user uses a keybinding to start a search.

The default binding for this signal is Control-F.
<!-- trait ShortcutsWindowExt::fn get_property_section_name -->
The name of the section to show.

This should be the section-name of one of the `ShortcutsSection`
objects that are in this shortcuts window.
<!-- trait ShortcutsWindowExt::fn set_property_section_name -->
The name of the section to show.

This should be the section-name of one of the `ShortcutsSection`
objects that are in this shortcuts window.
<!-- trait ShortcutsWindowExt::fn get_property_view_name -->
The view name by which to filter the contents.

This should correspond to the `ShortcutsGroup:view` property of some of
the `ShortcutsGroup` objects that are inside this shortcuts window.

Set this to `None` to show all groups.
<!-- trait ShortcutsWindowExt::fn set_property_view_name -->
The view name by which to filter the contents.

This should correspond to the `ShortcutsGroup:view` property of some of
the `ShortcutsGroup` objects that are inside this shortcuts window.

Set this to `None` to show all groups.
<!-- struct SizeGroup -->
`SizeGroup` provides a mechanism for grouping a number of widgets
together so they all request the same amount of space. This is
typically useful when you want a column of widgets to have the same
size, but you can’t use a `Grid` widget.

In detail, the size requested for each widget in a `SizeGroup` is
the maximum of the sizes that would have been requested for each
widget in the size group if they were not in the size group. The mode
of the size group (see `SizeGroupExt::set_mode`) determines whether
this applies to the horizontal size, the vertical size, or both sizes.

Note that size groups only affect the amount of space requested, not
the size that the widgets finally receive. If you want the widgets in
a `SizeGroup` to actually be the same size, you need to pack them in
such a way that they get the size they request and not more. For
example, if you are packing your widgets into a table, you would not
include the `AttachOptions::Fill` flag.

`SizeGroup` objects are referenced by each widget in the size group,
so once you have added all widgets to a `SizeGroup`, you can drop
the initial reference to the size group with `gobject::ObjectExt::unref`. If the
widgets in the size group are subsequently destroyed, then they will
be removed from the size group and drop their references on the size
group; when all widgets have been removed, the size group will be
freed.

Widgets can be part of multiple size groups; GTK+ will compute the
horizontal size of a widget from the horizontal requisition of all
widgets that can be reached from the widget by a chain of size groups
of type `SizeGroupMode::Horizontal` or `SizeGroupMode::Both`, and the
vertical size from the vertical requisition of all widgets that can be
reached from the widget by a chain of size groups of type
`SizeGroupMode::Vertical` or `SizeGroupMode::Both`.

Note that only non-contextual sizes of every widget are ever consulted
by size groups (since size groups have no knowledge of what size a widget
will be allocated in one dimension, it cannot derive how much height
a widget will receive for a given width). When grouping widgets that
trade height for width in mode `SizeGroupMode::Vertical` or `SizeGroupMode::Both`:
the height for the minimum width will be the requested height for all
widgets in the group. The same is of course true when horizontally grouping
width for height widgets.

Widgets that trade height-for-width should set a reasonably large minimum width
by way of `Label:width-chars` for instance. Widgets with static sizes as well
as widgets that grow (such as ellipsizing text) need no such considerations.

# `SizeGroup` as `Buildable`

Size groups can be specified in a UI definition by placing an `<object>`
element with `class="GtkSizeGroup"` somewhere in the UI definition. The
widgets that belong to the size group are specified by a `<widgets>` element
that may contain multiple `<widget>` elements, one for each member of the
size group. The ”name” attribute gives the id of the widget.

An example of a UI definition fragment with `SizeGroup`:

```text
<object class="GtkSizeGroup">
  <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
  <widgets>
    <widget name="radio1"/>
    <widget name="radio2"/>
  </widgets>
</object>
```

# Implements

[`SizeGroupExt`](trait.SizeGroupExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait SizeGroupExt -->
Trait containing all `SizeGroup` methods.

# Implementors

[`SizeGroup`](struct.SizeGroup.html)
<!-- impl SizeGroup::fn new -->
Create a new `SizeGroup`.
## `mode`
the mode for the new size group.

# Returns

a newly created `SizeGroup`
<!-- trait SizeGroupExt::fn add_widget -->
Adds a widget to a `SizeGroup`. In the future, the requisition
of the widget will be determined as the maximum of its requisition
and the requisition of the other widgets in the size group.
Whether this applies horizontally, vertically, or in both directions
depends on the mode of the size group. See `SizeGroupExt::set_mode`.

When the widget is destroyed or no longer referenced elsewhere, it will
be removed from the size group.
## `widget`
the `Widget` to add
<!-- trait SizeGroupExt::fn get_ignore_hidden -->
Returns if invisible widgets are ignored when calculating the size.

# Deprecated since 3.22

Measuring the size of hidden widgets has not worked
 reliably for a long time. In most cases, they will report a size
 of 0 nowadays, and thus, their size will not affect the other
 size group members. In effect, size groups will always operate
 as if this property was `true`. Use a `Stack` instead to hide
 widgets while still having their size taken into account.

# Returns

`true` if invisible widgets are ignored.
<!-- trait SizeGroupExt::fn get_mode -->
Gets the current mode of the size group. See `SizeGroupExt::set_mode`.

# Returns

the current mode of the size group.
<!-- trait SizeGroupExt::fn get_widgets -->
Returns the list of widgets associated with `self`.

# Returns

a `glib::SList` of
 widgets. The list is owned by GTK+ and should not be modified.
<!-- trait SizeGroupExt::fn remove_widget -->
Removes a widget from a `SizeGroup`.
## `widget`
the `Widget` to remove
<!-- trait SizeGroupExt::fn set_ignore_hidden -->
Sets whether unmapped widgets should be ignored when
calculating the size.

# Deprecated since 3.22

Measuring the size of hidden widgets has not worked
 reliably for a long time. In most cases, they will report a size
 of 0 nowadays, and thus, their size will not affect the other
 size group members. In effect, size groups will always operate
 as if this property was `true`. Use a `Stack` instead to hide
 widgets while still having their size taken into account.
## `ignore_hidden`
whether unmapped widgets should be ignored
 when calculating the size
<!-- trait SizeGroupExt::fn set_mode -->
Sets the `SizeGroupMode` of the size group. The mode of the size
group determines whether the widgets in the size group should
all have the same horizontal requisition (`SizeGroupMode::Horizontal`)
all have the same vertical requisition (`SizeGroupMode::Vertical`),
or should all have the same requisition in both directions
(`SizeGroupMode::Both`).
## `mode`
the mode to set for the size group.
<!-- trait SizeGroupExt::fn get_property_ignore_hidden -->
If `true`, unmapped widgets are ignored when determining
the size of the group.

# Deprecated since 3.22

Measuring the size of hidden widgets has not worked
 reliably for a long time. In most cases, they will report a size
 of 0 nowadays, and thus, their size will not affect the other
 size group members. In effect, size groups will always operate
 as if this property was `true`. Use a `Stack` instead to hide
 widgets while still having their size taken into account.
<!-- trait SizeGroupExt::fn set_property_ignore_hidden -->
If `true`, unmapped widgets are ignored when determining
the size of the group.

# Deprecated since 3.22

Measuring the size of hidden widgets has not worked
 reliably for a long time. In most cases, they will report a size
 of 0 nowadays, and thus, their size will not affect the other
 size group members. In effect, size groups will always operate
 as if this property was `true`. Use a `Stack` instead to hide
 widgets while still having their size taken into account.
<!-- enum SizeGroupMode -->
The mode of the size group determines the directions in which the size
group affects the requested sizes of its component widgets.
<!-- enum SizeGroupMode::variant None -->
group has no effect
<!-- enum SizeGroupMode::variant Horizontal -->
group affects horizontal requisition
<!-- enum SizeGroupMode::variant Vertical -->
group affects vertical requisition
<!-- enum SizeGroupMode::variant Both -->
group affects both horizontal and vertical requisition
<!-- enum SizeRequestMode -->
Specifies a preference for height-for-width or
width-for-height geometry management.
<!-- enum SizeRequestMode::variant HeightForWidth -->
Prefer height-for-width geometry management
<!-- enum SizeRequestMode::variant WidthForHeight -->
Prefer width-for-height geometry management
<!-- enum SizeRequestMode::variant ConstantSize -->
Don’t trade height-for-width or width-for-height
<!-- struct Socket -->
Together with `Plug`, `Socket` provides the ability to embed
widgets from one process into another process in a fashion that
is transparent to the user. One process creates a `Socket` widget
and passes that widget’s window ID to the other process, which then
creates a `Plug` with that window ID. Any widgets contained in the
`Plug` then will appear inside the first application’s window.

The socket’s window ID is obtained by using `GtkSocketExt::get_id`.
Before using this function, the socket must have been realized,
and for hence, have been added to its parent.

## Obtaining the window ID of a socket.


```C
GtkWidget *socket = gtk_socket_new ();
gtk_widget_show (socket);
gtk_container_add (GTK_CONTAINER (parent), socket);

// The following call is only necessary if one of
// the ancestors of the socket is not yet visible.
gtk_widget_realize (socket);
g_print ("The ID of the sockets window is %#x\n",
         gtk_socket_get_id (socket));
```

Note that if you pass the window ID of the socket to another
process that will create a plug in the socket, you must make
sure that the socket widget is not destroyed until that plug
is created. Violating this rule will cause unpredictable
consequences, the most likely consequence being that the plug
will appear as a separate toplevel window. You can check if
the plug has been created by using `GtkSocketExt::get_plug_window`.
If it returns a non-`None` value, then the plug has been
successfully created inside of the socket.

When GTK+ is notified that the embedded window has been destroyed,
then it will destroy the socket as well. You should always,
therefore, be prepared for your sockets to be destroyed at any
time when the main event loop is running. To prevent this from
happening, you can connect to the `Socket::plug-removed` signal.

The communication between a `Socket` and a `Plug` follows the
[XEmbed Protocol](http://www.freedesktop.org/Standards/xembed-spec).
This protocol has also been implemented in other toolkits, e.g. Qt,
allowing the same level of integration when embedding a Qt widget
in GTK or vice versa.

The `Plug` and `Socket` widgets are only available when GTK+
is compiled for the X11 platform and `GDK_WINDOWING_X11` is defined.
They can only be used on a ``GdkX11Display``. To use `Plug` and
`Socket`, you need to include the `gtk/gtkx.h` header.

# Implements

[`GtkSocketExt`](trait.GtkSocketExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait GtkSocketExt -->
Trait containing all `Socket` methods.

# Implementors

[`Socket`](struct.Socket.html)
<!-- impl Socket::fn new -->
Create a new empty `Socket`.

# Returns

the new `Socket`.
<!-- trait GtkSocketExt::fn add_id -->
Adds an XEMBED client, such as a `Plug`, to the `Socket`. The
client may be in the same process or in a different process.

To embed a `Plug` in a `Socket`, you can either create the
`Plug` with `gtk_plug_new (0)`, call
`PlugExt::get_id` to get the window ID of the plug, and then pass that to the
`GtkSocketExt::add_id`, or you can call `GtkSocketExt::get_id` to get the
window ID for the socket, and call `Plug::new` passing in that
ID.

The `Socket` must have already be added into a toplevel window
 before you can make this call.
## `window`
the Window of a client participating in the XEMBED protocol.
<!-- trait GtkSocketExt::fn get_id -->
Gets the window ID of a `Socket` widget, which can then
be used to create a client embedded inside the socket, for
instance with `Plug::new`.

The `Socket` must have already be added into a toplevel window
before you can make this call.

# Returns

the window ID for the socket
<!-- trait GtkSocketExt::fn get_plug_window -->
Retrieves the window of the plug. Use this to check if the plug has
been created inside of the socket.

# Returns

the window of the plug if
available, or `None`
<!-- trait GtkSocketExt::fn connect_plug_added -->
This signal is emitted when a client is successfully
added to the socket.
<!-- trait GtkSocketExt::fn connect_plug_removed -->
This signal is emitted when a client is removed from the socket.
The default action is to destroy the `Socket` widget, so if you
want to reuse it you must add a signal handler that returns `true`.

# Returns

`true` to stop other handlers from being invoked.
<!-- enum SortType -->
Determines the direction of a sort.
<!-- enum SortType::variant Ascending -->
Sorting is in ascending order.
<!-- enum SortType::variant Descending -->
Sorting is in descending order.
<!-- struct SpinButton -->
A `SpinButton` is an ideal way to allow the user to set the value of
some attribute. Rather than having to directly type a number into a
`Entry`, `SpinButton` allows the user to click on one of two arrows
to increment or decrement the displayed value. A value can still be
typed in, with the bonus that it can be checked to ensure it is in a
given range.

The main properties of a `SpinButton` are through an adjustment.
See the `Adjustment` section for more details about an adjustment's
properties. Note that `SpinButton` will by default make its entry
large enough to accomodate the lower and upper bounds of the adjustment,
which can lead to surprising results. Best practice is to set both
the `Entry:width-chars` and `Entry:max-width-chars` poperties
to the desired number of characters to display in the entry.

# CSS nodes


```plain
spinbutton.horizontal
├── undershoot.left
├── undershoot.right
├── entry
│   ╰── ...
├── button.down
╰── button.up
```


```plain
spinbutton.vertical
├── undershoot.left
├── undershoot.right
├── button.up
├── entry
│   ╰── ...
╰── button.down
```

`GtkSpinButtons` main CSS node has the name spinbutton. It creates subnodes
for the entry and the two buttons, with these names. The button nodes have
the style classes .up and .down. The `Entry` subnodes (if present) are put
below the entry node. The orientation of the spin button is reflected in
the .vertical or .horizontal style class on the main node.

## Using a `SpinButton` to get an integer


```C
// Provides a function to retrieve an integer value from a GtkSpinButton
// and creates a spin button to model percentage values.

gint
grab_int_value (GtkSpinButton *button,
                gpointer       user_data)
{
  return gtk_spin_button_get_value_as_int (button);
}

void
create_integer_spin_button (void)
{

  GtkWidget *window, *button;
  GtkAdjustment *adjustment;

  adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_container_set_border_width (GTK_CONTAINER (window), 5);

  // creates the spinbutton, with no decimal places
  button = gtk_spin_button_new (adjustment, 1.0, 0);
  gtk_container_add (GTK_CONTAINER (window), button);

  gtk_widget_show_all (window);
}
```

## Using a `SpinButton` to get a floating point value


```C
// Provides a function to retrieve a floating point value from a
// GtkSpinButton, and creates a high precision spin button.

gfloat
grab_float_value (GtkSpinButton *button,
                  gpointer       user_data)
{
  return gtk_spin_button_get_value (button);
}

void
create_floating_spin_button (void)
{
  GtkWidget *window, *button;
  GtkAdjustment *adjustment;

  adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_container_set_border_width (GTK_CONTAINER (window), 5);

  // creates the spinbutton, with three decimal places
  button = gtk_spin_button_new (adjustment, 0.001, 3);
  gtk_container_add (GTK_CONTAINER (window), button);

  gtk_widget_show_all (window);
}
```

# Implements

[`SpinButtonExt`](trait.SpinButtonExt.html), [`EntryExt`](trait.EntryExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`EditableExt`](trait.EditableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`SpinButtonSignals`](prelude/trait.SpinButtonSignals.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`EditableSignals`](prelude/trait.EditableSignals.html)
<!-- trait SpinButtonExt -->
Trait containing all `SpinButton` methods.

# Implementors

[`SpinButton`](struct.SpinButton.html)
<!-- impl SpinButton::fn new -->
Creates a new `SpinButton`.
## `adjustment`
the `Adjustment` object that this spin
 button should use, or `None`
## `climb_rate`
specifies by how much the rate of change in the value will
 accelerate if you continue to hold down an up/down button or arrow key
## `digits`
the number of decimal places to display

# Returns

The new spin button as a `Widget`
<!-- impl SpinButton::fn new_with_range -->
This is a convenience constructor that allows creation of a numeric
`SpinButton` without manually creating an adjustment. The value is
initially set to the minimum value and a page increment of 10 * `step`
is the default. The precision of the spin button is equivalent to the
precision of `step`.

Note that the way in which the precision is derived works best if `step`
is a power of ten. If the resulting precision is not suitable for your
needs, use `SpinButtonExt::set_digits` to correct it.
## `min`
Minimum allowable value
## `max`
Maximum allowable value
## `step`
Increment added or subtracted by spinning the widget

# Returns

The new spin button as a `Widget`
<!-- trait SpinButtonExt::fn configure -->
Changes the properties of an existing spin button. The adjustment,
climb rate, and number of decimal places are updated accordingly.
## `adjustment`
a `Adjustment` to replace the spin button’s
 existing adjustment, or `None` to leave its current adjustment unchanged
## `climb_rate`
the new climb rate
## `digits`
the number of decimal places to display in the spin button
<!-- trait SpinButtonExt::fn get_adjustment -->
Get the adjustment associated with a `SpinButton`

# Returns

the `Adjustment` of `self`
<!-- trait SpinButtonExt::fn get_digits -->
Fetches the precision of `self`. See `SpinButtonExt::set_digits`.

# Returns

the current precision
<!-- trait SpinButtonExt::fn get_increments -->
Gets the current step and page the increments used by `self`. See
`SpinButtonExt::set_increments`.
## `step`
location to store step increment, or `None`
## `page`
location to store page increment, or `None`
<!-- trait SpinButtonExt::fn get_numeric -->
Returns whether non-numeric text can be typed into the spin button.
See `SpinButtonExt::set_numeric`.

# Returns

`true` if only numeric text can be entered
<!-- trait SpinButtonExt::fn get_range -->
Gets the range allowed for `self`.
See `SpinButtonExt::set_range`.
## `min`
location to store minimum allowed value, or `None`
## `max`
location to store maximum allowed value, or `None`
<!-- trait SpinButtonExt::fn get_snap_to_ticks -->
Returns whether the values are corrected to the nearest step.
See `SpinButtonExt::set_snap_to_ticks`.

# Returns

`true` if values are snapped to the nearest step
<!-- trait SpinButtonExt::fn get_update_policy -->
Gets the update behavior of a spin button.
See `SpinButtonExt::set_update_policy`.

# Returns

the current update policy
<!-- trait SpinButtonExt::fn get_value -->
Get the value in the `self`.

# Returns

the value of `self`
<!-- trait SpinButtonExt::fn get_value_as_int -->
Get the value `self` represented as an integer.

# Returns

the value of `self`
<!-- trait SpinButtonExt::fn get_wrap -->
Returns whether the spin button’s value wraps around to the
opposite limit when the upper or lower limit of the range is
exceeded. See `SpinButtonExt::set_wrap`.

# Returns

`true` if the spin button wraps around
<!-- trait SpinButtonExt::fn set_adjustment -->
Replaces the `Adjustment` associated with `self`.
## `adjustment`
a `Adjustment` to replace the existing adjustment
<!-- trait SpinButtonExt::fn set_digits -->
Set the precision to be displayed by `self`. Up to 20 digit precision
is allowed.
## `digits`
the number of digits after the decimal point to be displayed for the spin button’s value
<!-- trait SpinButtonExt::fn set_increments -->
Sets the step and page increments for spin_button. This affects how
quickly the value changes when the spin button’s arrows are activated.
## `step`
increment applied for a button 1 press.
## `page`
increment applied for a button 2 press.
<!-- trait SpinButtonExt::fn set_numeric -->
Sets the flag that determines if non-numeric text can be typed
into the spin button.
## `numeric`
flag indicating if only numeric entry is allowed
<!-- trait SpinButtonExt::fn set_range -->
Sets the minimum and maximum allowable values for `self`.

If the current value is outside this range, it will be adjusted
to fit within the range, otherwise it will remain unchanged.
## `min`
minimum allowable value
## `max`
maximum allowable value
<!-- trait SpinButtonExt::fn set_snap_to_ticks -->
Sets the policy as to whether values are corrected to the
nearest step increment when a spin button is activated after
providing an invalid value.
## `snap_to_ticks`
a flag indicating if invalid values should be corrected
<!-- trait SpinButtonExt::fn set_update_policy -->
Sets the update behavior of a spin button.
This determines whether the spin button is always updated
or only when a valid value is set.
## `policy`
a `SpinButtonUpdatePolicy` value
<!-- trait SpinButtonExt::fn set_value -->
Sets the value of `self`.
## `value`
the new value
<!-- trait SpinButtonExt::fn set_wrap -->
Sets the flag that determines if a spin button value wraps
around to the opposite limit when the upper or lower limit
of the range is exceeded.
## `wrap`
a flag indicating if wrapping behavior is performed
<!-- trait SpinButtonExt::fn spin -->
Increment or decrement a spin button’s value in a specified
direction by a specified amount.
## `direction`
a `SpinType` indicating the direction to spin
## `increment`
step increment to apply in the specified direction
<!-- trait SpinButtonExt::fn update -->
Manually force an update of the spin button.
<!-- trait SpinButtonExt::fn connect_change_value -->
The ::change-value signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a value change.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically.

The default bindings for this signal are Up/Down and PageUp and/PageDown.
## `scroll`
a `ScrollType` to specify the speed and amount of change
<!-- trait SpinButtonExt::fn connect_input -->
The ::input signal can be used to influence the conversion of
the users input into a double value. The signal handler is
expected to use `EntryExt::get_text` to retrieve the text of
the entry and set `new_value` to the new value.

The default conversion uses `g_strtod`.
## `new_value`
return location for the new value

# Returns

`true` for a successful conversion, `false` if the input
 was not handled, and `GTK_INPUT_ERROR` if the conversion failed.
<!-- trait SpinButtonExt::fn connect_output -->
The ::output signal can be used to change to formatting
of the value that is displayed in the spin buttons entry.

```C
// show leading zeros
static gboolean
on_output (GtkSpinButton *spin,
           gpointer       data)
{
   GtkAdjustment *adjustment;
   gchar *text;
   int value;

   adjustment = gtk_spin_button_get_adjustment (spin);
   value = (int)gtk_adjustment_get_value (adjustment);
   text = g_strdup_printf ("%02d", value);
   gtk_entry_set_text (GTK_ENTRY (spin), text);
   g_free (text);

   return TRUE;
}
```

# Returns

`true` if the value has been displayed
<!-- trait SpinButtonExt::fn connect_value_changed -->
The ::value-changed signal is emitted when the value represented by
`spinbutton` changes. Also see the `SpinButton::output` signal.
<!-- trait SpinButtonExt::fn connect_wrapped -->
The ::wrapped signal is emitted right after the spinbutton wraps
from its maximum to minimum value or vice-versa.
<!-- enum SpinButtonUpdatePolicy -->
The spin button update policy determines whether the spin button displays
values even if they are outside the bounds of its adjustment.
See `SpinButtonExt::set_update_policy`.
<!-- enum SpinButtonUpdatePolicy::variant Always -->
When refreshing your `SpinButton`, the value is
 always displayed
<!-- enum SpinButtonUpdatePolicy::variant IfValid -->
When refreshing your `SpinButton`, the value is
 only displayed if it is valid within the bounds of the spin button's
 adjustment
<!-- enum SpinType -->
The values of the `SpinType` enumeration are used to specify the
change to make in `SpinButtonExt::spin`.
<!-- enum SpinType::variant StepForward -->
Increment by the adjustments step increment.
<!-- enum SpinType::variant StepBackward -->
Decrement by the adjustments step increment.
<!-- enum SpinType::variant PageForward -->
Increment by the adjustments page increment.
<!-- enum SpinType::variant PageBackward -->
Decrement by the adjustments page increment.
<!-- enum SpinType::variant Home -->
Go to the adjustments lower bound.
<!-- enum SpinType::variant End -->
Go to the adjustments upper bound.
<!-- enum SpinType::variant UserDefined -->
Change by a specified amount.
<!-- struct Spinner -->
A `Spinner` widget displays an icon-size spinning animation.
It is often used as an alternative to a `ProgressBar` for
displaying indefinite activity, instead of actual progress.

To start the animation, use `SpinnerExt::start`, to stop it
use `SpinnerExt::stop`.

# CSS nodes

`Spinner` has a single CSS node with the name spinner. When the animation is
active, the :checked pseudoclass is added to this node.

# Implements

[`SpinnerExt`](trait.SpinnerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait SpinnerExt -->
Trait containing all `Spinner` methods.

# Implementors

[`Spinner`](struct.Spinner.html)
<!-- impl Spinner::fn new -->
Returns a new spinner widget. Not yet started.

# Returns

a new `Spinner`
<!-- trait SpinnerExt::fn start -->
Starts the animation of the spinner.
<!-- trait SpinnerExt::fn stop -->
Stops the animation of the spinner.
<!-- struct Stack -->
The `Stack` widget is a container which only shows
one of its children at a time. In contrast to `Notebook`,
`Stack` does not provide a means for users to change the
visible child. Instead, the `StackSwitcher` widget can be
used with `Stack` to provide this functionality.

Transitions between pages can be animated as slides or
fades. This can be controlled with `StackExt::set_transition_type`.
These animations respect the `Settings:gtk-enable-animations`
setting.

The `Stack` widget was added in GTK+ 3.10.

# CSS nodes

`Stack` has a single CSS node named stack.

# Implements

[`StackExt`](trait.StackExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait StackExt -->
Trait containing all `Stack` methods.

# Implementors

[`Stack`](struct.Stack.html)
<!-- impl Stack::fn new -->
Creates a new `Stack` container.

# Returns

a new `Stack`
<!-- trait StackExt::fn add_named -->
Adds a child to `self`.
The child is identified by the `name`.
## `child`
the widget to add
## `name`
the name for `child`
<!-- trait StackExt::fn add_titled -->
Adds a child to `self`.
The child is identified by the `name`. The `title`
will be used by `StackSwitcher` to represent
`child` in a tab bar, so it should be short.
## `child`
the widget to add
## `name`
the name for `child`
## `title`
a human-readable title for `child`
<!-- trait StackExt::fn get_child_by_name -->
Finds the child of the `Stack` with the name given as
the argument. Returns `None` if there is no child with this
name.
## `name`
the name of the child to find

# Returns

the requested child of the `Stack`
<!-- trait StackExt::fn get_hhomogeneous -->
Gets whether `self` is horizontally homogeneous.
See `StackExt::set_hhomogeneous`.

Feature: `v3_16`


# Returns

whether `self` is horizontally homogeneous.
<!-- trait StackExt::fn get_homogeneous -->
Gets whether `self` is homogeneous.
See `StackExt::set_homogeneous`.

# Returns

whether `self` is homogeneous.
<!-- trait StackExt::fn get_interpolate_size -->
Returns wether the `Stack` is set up to interpolate between
the sizes of children on page switch.

Feature: `v3_18`


# Returns

`true` if child sizes are interpolated
<!-- trait StackExt::fn get_transition_duration -->
Returns the amount of time (in milliseconds) that
transitions between pages in `self` will take.

# Returns

the transition duration
<!-- trait StackExt::fn get_transition_running -->
Returns whether the `self` is currently in a transition from one page to
another.

# Returns

`true` if the transition is currently running, `false` otherwise.
<!-- trait StackExt::fn get_transition_type -->
Gets the type of animation that will be used
for transitions between pages in `self`.

# Returns

the current transition type of `self`
<!-- trait StackExt::fn get_vhomogeneous -->
Gets whether `self` is vertically homogeneous.
See `StackExt::set_vhomogeneous`.

Feature: `v3_16`


# Returns

whether `self` is vertically homogeneous.
<!-- trait StackExt::fn get_visible_child -->
Gets the currently visible child of `self`, or `None` if
there are no visible children.

# Returns

the visible child of the `Stack`
<!-- trait StackExt::fn get_visible_child_name -->
Returns the name of the currently visible child of `self`, or
`None` if there is no visible child.

# Returns

the name of the visible child of the `Stack`
<!-- trait StackExt::fn set_hhomogeneous -->
Sets the `Stack` to be horizontally homogeneous or not.
If it is homogeneous, the `Stack` will request the same
width for all its children. If it isn't, the stack
may change width when a different child becomes visible.

Feature: `v3_16`

## `hhomogeneous`
`true` to make `self` horizontally homogeneous
<!-- trait StackExt::fn set_homogeneous -->
Sets the `Stack` to be homogeneous or not. If it
is homogeneous, the `Stack` will request the same
size for all its children. If it isn't, the stack
may change size when a different child becomes visible.

Since 3.16, homogeneity can be controlled separately
for horizontal and vertical size, with the
`Stack:hhomogeneous` and `Stack:vhomogeneous`.
## `homogeneous`
`true` to make `self` homogeneous
<!-- trait StackExt::fn set_interpolate_size -->
Sets whether or not `self` will interpolate its size when
changing the visible child. If the `Stack:interpolate-size`
property is set to `true`, `self` will interpolate its size between
the current one and the one it'll take after changing the
visible child, according to the set transition duration.

Feature: `v3_18`

## `interpolate_size`
the new value
<!-- trait StackExt::fn set_transition_duration -->
Sets the duration that transitions between pages in `self`
will take.
## `duration`
the new duration, in milliseconds
<!-- trait StackExt::fn set_transition_type -->
Sets the type of animation that will be used for
transitions between pages in `self`. Available
types include various kinds of fades and slides.

The transition type can be changed without problems
at runtime, so it is possible to change the animation
based on the page that is about to become current.
## `transition`
the new transition type
<!-- trait StackExt::fn set_vhomogeneous -->
Sets the `Stack` to be vertically homogeneous or not.
If it is homogeneous, the `Stack` will request the same
height for all its children. If it isn't, the stack
may change height when a different child becomes visible.

Feature: `v3_16`

## `vhomogeneous`
`true` to make `self` vertically homogeneous
<!-- trait StackExt::fn set_visible_child -->
Makes `child` the visible child of `self`.

If `child` is different from the currently
visible child, the transition between the
two will be animated with the current
transition type of `self`.

Note that the `child` widget has to be visible itself
(see `WidgetExt::show`) in order to become the visible
child of `self`.
## `child`
a child of `self`
<!-- trait StackExt::fn set_visible_child_full -->
Makes the child with the given name visible.

Note that the child widget has to be visible itself
(see `WidgetExt::show`) in order to become the visible
child of `self`.
## `name`
the name of the child to make visible
## `transition`
the transition type to use
<!-- trait StackExt::fn set_visible_child_name -->
Makes the child with the given name visible.

If `child` is different from the currently
visible child, the transition between the
two will be animated with the current
transition type of `self`.

Note that the child widget has to be visible itself
(see `WidgetExt::show`) in order to become the visible
child of `self`.
## `name`
the name of the child to make visible
<!-- trait StackExt::fn get_property_hhomogeneous -->
`true` if the stack allocates the same width for all children.

Feature: `v3_16`

<!-- trait StackExt::fn set_property_hhomogeneous -->
`true` if the stack allocates the same width for all children.

Feature: `v3_16`

<!-- trait StackExt::fn get_property_vhomogeneous -->
`true` if the stack allocates the same height for all children.

Feature: `v3_16`

<!-- trait StackExt::fn set_property_vhomogeneous -->
`true` if the stack allocates the same height for all children.

Feature: `v3_16`

<!-- struct StackSidebar -->
A `StackSidebar` enables you to quickly and easily provide a
consistent "sidebar" object for your user interface.

In order to use a `StackSidebar`, you simply use a `Stack` to
organize your UI flow, and add the sidebar to your sidebar area. You
can use `StackSidebarExt::set_stack` to connect the `StackSidebar`
to the `Stack`.

# CSS nodes

`StackSidebar` has a single CSS node with name stacksidebar and
style class .sidebar.

When circumstances require it, `StackSidebar` adds the
.needs-attention style class to the widgets representing the stack
pages.

Feature: `v3_16`

# Implements

[`StackSidebarExt`](trait.StackSidebarExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait StackSidebarExt -->
Trait containing all `StackSidebar` methods.

Feature: `v3_16`

# Implementors

[`StackSidebar`](struct.StackSidebar.html)
<!-- impl StackSidebar::fn new -->
Creates a new sidebar.

Feature: `v3_16`


# Returns

the new `StackSidebar`
<!-- trait StackSidebarExt::fn get_stack -->
Retrieves the stack.
See `StackSidebarExt::set_stack`.

Feature: `v3_16`


# Returns

the associated `Stack` or
 `None` if none has been set explicitly
<!-- trait StackSidebarExt::fn set_stack -->
Set the `Stack` associated with this `StackSidebar`.

The sidebar widget will automatically update according to the order
(packing) and items within the given `Stack`.

Feature: `v3_16`

## `stack`
a `Stack`
<!-- struct StackSwitcher -->
The `StackSwitcher` widget acts as a controller for a
`Stack`; it shows a row of buttons to switch between
the various pages of the associated stack widget.

All the content for the buttons comes from the child properties
of the `Stack`; the button visibility in a `StackSwitcher`
widget is controlled by the visibility of the child in the
`Stack`.

It is possible to associate multiple `StackSwitcher` widgets
with the same `Stack` widget.

The `StackSwitcher` widget was added in 3.10.

# CSS nodes

`StackSwitcher` has a single CSS node named stackswitcher and
style class .stack-switcher.

When circumstances require it, `StackSwitcher` adds the
.needs-attention style class to the widgets representing the
stack pages.

# Implements

[`StackSwitcherExt`](trait.StackSwitcherExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait StackSwitcherExt -->
Trait containing all `StackSwitcher` methods.

# Implementors

[`StackSwitcher`](struct.StackSwitcher.html)
<!-- impl StackSwitcher::fn new -->
Create a new `StackSwitcher`.

# Returns

a new `StackSwitcher`.
<!-- trait StackSwitcherExt::fn get_stack -->
Retrieves the stack.
See `StackSwitcherExt::set_stack`.

# Returns

the stack, or `None` if
 none has been set explicitly.
<!-- trait StackSwitcherExt::fn set_stack -->
Sets the stack to control.
## `stack`
a `Stack`
<!-- trait StackSwitcherExt::fn get_property_icon_size -->
Use the "icon-size" property to change the size of the image displayed
when a `StackSwitcher` is displaying icons.

Feature: `v3_20`

<!-- trait StackSwitcherExt::fn set_property_icon_size -->
Use the "icon-size" property to change the size of the image displayed
when a `StackSwitcher` is displaying icons.

Feature: `v3_20`

<!-- enum StackTransitionType -->
These enumeration values describe the possible transitions
between pages in a `Stack` widget.

New values may be added to this enumeration over time.
<!-- enum StackTransitionType::variant None -->
No transition
<!-- enum StackTransitionType::variant Crossfade -->
A cross-fade
<!-- enum StackTransitionType::variant SlideRight -->
Slide from left to right
<!-- enum StackTransitionType::variant SlideLeft -->
Slide from right to left
<!-- enum StackTransitionType::variant SlideUp -->
Slide from bottom up
<!-- enum StackTransitionType::variant SlideDown -->
Slide from top down
<!-- enum StackTransitionType::variant SlideLeftRight -->
Slide from left or right according to the children order
<!-- enum StackTransitionType::variant SlideUpDown -->
Slide from top down or bottom up according to the order
<!-- enum StackTransitionType::variant OverUp -->
Cover the old page by sliding up. Since 3.12
<!-- enum StackTransitionType::variant OverDown -->
Cover the old page by sliding down. Since: 3.12
<!-- enum StackTransitionType::variant OverLeft -->
Cover the old page by sliding to the left. Since: 3.12
<!-- enum StackTransitionType::variant OverRight -->
Cover the old page by sliding to the right. Since: 3.12
<!-- enum StackTransitionType::variant UnderUp -->
Uncover the new page by sliding up. Since 3.12
<!-- enum StackTransitionType::variant UnderDown -->
Uncover the new page by sliding down. Since: 3.12
<!-- enum StackTransitionType::variant UnderLeft -->
Uncover the new page by sliding to the left. Since: 3.12
<!-- enum StackTransitionType::variant UnderRight -->
Uncover the new page by sliding to the right. Since: 3.12
<!-- enum StackTransitionType::variant OverUpDown -->
Cover the old page sliding up or uncover the new page sliding down, according to order. Since: 3.12
<!-- enum StackTransitionType::variant OverDownUp -->
Cover the old page sliding down or uncover the new page sliding up, according to order. Since: 3.14
<!-- enum StackTransitionType::variant OverLeftRight -->
Cover the old page sliding left or uncover the new page sliding right, according to order. Since: 3.14
<!-- enum StackTransitionType::variant OverRightLeft -->
Cover the old page sliding right or uncover the new page sliding left, according to order. Since: 3.14
<!-- struct StateFlags -->
Describes a widget state. Widget states are used to match the widget
against CSS pseudo-classes. Note that GTK extends the regular CSS
classes and sometimes uses different names.
<!-- struct StateFlags::const NORMAL -->
State during normal operation.
<!-- struct StateFlags::const ACTIVE -->
Widget is active.
<!-- struct StateFlags::const PRELIGHT -->
Widget has a mouse pointer over it.
<!-- struct StateFlags::const SELECTED -->
Widget is selected.
<!-- struct StateFlags::const INSENSITIVE -->
Widget is insensitive.
<!-- struct StateFlags::const INCONSISTENT -->
Widget is inconsistent.
<!-- struct StateFlags::const FOCUSED -->
Widget has the keyboard focus.
<!-- struct StateFlags::const BACKDROP -->
Widget is in a background toplevel window.
<!-- struct StateFlags::const DIR_LTR -->
Widget is in left-to-right text direction. Since 3.8
<!-- struct StateFlags::const DIR_RTL -->
Widget is in right-to-left text direction. Since 3.8
<!-- struct StateFlags::const LINK -->
Widget is a link. Since 3.12
<!-- struct StateFlags::const VISITED -->
The location the widget points to has already been visited. Since 3.12
<!-- struct StateFlags::const CHECKED -->
Widget is checked. Since 3.14
<!-- struct StateFlags::const DROP_ACTIVE -->
Widget is highlighted as a drop target for DND. Since 3.20
<!-- struct Statusbar -->
A `Statusbar` is usually placed along the bottom of an application's
main `Window`. It may provide a regular commentary of the application's
status (as is usually the case in a web browser, for example), or may be
used to simply output a message when the status changes, (when an upload
is complete in an FTP client, for example).

Status bars in GTK+ maintain a stack of messages. The message at
the top of the each bar’s stack is the one that will currently be displayed.

Any messages added to a statusbar’s stack must specify a
context id that is used to uniquely identify
the source of a message. This context id can be generated by
`StatusbarExt::get_context_id`, given a message and the statusbar that
it will be added to. Note that messages are stored in a stack, and when
choosing which message to display, the stack structure is adhered to,
regardless of the context identifier of a message.

One could say that a statusbar maintains one stack of messages for
display purposes, but allows multiple message producers to maintain
sub-stacks of the messages they produced (via context ids).

Status bars are created using `Statusbar::new`.

Messages are added to the bar’s stack with `StatusbarExt::push`.

The message at the top of the stack can be removed using
`StatusbarExt::pop`. A message can be removed from anywhere in the
stack if its message id was recorded at the time it was added. This
is done using `StatusbarExt::remove`.

# CSS node

`Statusbar` has a single CSS node with name statusbar.

# Implements

[`StatusbarExt`](trait.StatusbarExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait StatusbarExt -->
Trait containing all `Statusbar` methods.

# Implementors

[`Statusbar`](struct.Statusbar.html)
<!-- impl Statusbar::fn new -->
Creates a new `Statusbar` ready for messages.

# Returns

the new `Statusbar`
<!-- trait StatusbarExt::fn get_context_id -->
Returns a new context identifier, given a description
of the actual context. Note that the description is
not shown in the UI.
## `context_description`
textual description of what context
 the new message is being used in

# Returns

an integer id
<!-- trait StatusbarExt::fn get_message_area -->
Retrieves the box containing the label widget.

# Returns

a `Box`
<!-- trait StatusbarExt::fn pop -->
Removes the first message in the `Statusbar`’s stack
with the given context id.

Note that this may not change the displayed message, if
the message at the top of the stack has a different
context id.
## `context_id`
a context identifier
<!-- trait StatusbarExt::fn push -->
Pushes a new message onto a statusbar’s stack.
## `context_id`
the message’s context id, as returned by
 `StatusbarExt::get_context_id`
## `text`
the message to add to the statusbar

# Returns

a message id that can be used with
 `StatusbarExt::remove`.
<!-- trait StatusbarExt::fn remove -->
Forces the removal of a message from a statusbar’s stack.
The exact `context_id` and `message_id` must be specified.
## `context_id`
a context identifier
## `message_id`
a message identifier, as returned by `StatusbarExt::push`
<!-- trait StatusbarExt::fn remove_all -->
Forces the removal of all messages from a statusbar's
stack with the exact `context_id`.
## `context_id`
a context identifier
<!-- trait StatusbarExt::fn connect_text_popped -->
Is emitted whenever a new message is popped off a statusbar's stack.
## `context_id`
the context id of the relevant message/statusbar
## `text`
the message that was just popped
<!-- trait StatusbarExt::fn connect_text_pushed -->
Is emitted whenever a new message gets pushed onto a statusbar's stack.
## `context_id`
the context id of the relevant message/statusbar
## `text`
the message that was pushed
<!-- struct StyleContext -->
`StyleContext` is an object that stores styling information affecting
a widget defined by `WidgetPath`.

In order to construct the final style information, `StyleContext`
queries information from all attached ``GtkStyleProviders``. Style providers
can be either attached explicitly to the context through
`StyleContextExt::add_provider`, or to the screen through
`StyleContext::add_provider_for_screen`. The resulting style is a
combination of all providers’ information in priority order.

For GTK+ widgets, any `StyleContext` returned by
`WidgetExt::get_style_context` will already have a `WidgetPath`, a
`gdk::Screen` and RTL/LTR information set. The style context will also be
updated automatically if any of these settings change on the widget.

If you are using the theming layer standalone, you will need to set a
widget path and a screen yourself to the created style context through
`StyleContextExt::set_path` and possibly `StyleContextExt::set_screen`. See
the “Foreign drawing“ example in gtk3-demo.

# Style Classes # {`gtkstylecontext`-classes}

Widgets can add style classes to their context, which can be used to associate
different styles by class. The documentation for individual widgets lists
which style classes it uses itself, and which style classes may be added by
applications to affect their appearance.

GTK+ defines macros for a number of style classes.

# Style Regions

Widgets can also add regions with flags to their context. This feature is
deprecated and will be removed in a future GTK+ update. Please use style
classes instead.

GTK+ defines macros for a number of style regions.

# Custom styling in UI libraries and applications

If you are developing a library with custom ``GtkWidgets`` that
render differently than standard components, you may need to add a
`StyleProvider` yourself with the `GTK_STYLE_PROVIDER_PRIORITY_FALLBACK`
priority, either a `CssProvider` or a custom object implementing the
`StyleProvider` interface. This way themes may still attempt
to style your UI elements in a different way if needed so.

If you are using custom styling on an applications, you probably want then
to make your style information prevail to the theme’s, so you must use
a `StyleProvider` with the `GTK_STYLE_PROVIDER_PRIORITY_APPLICATION`
priority, keep in mind that the user settings in
`XDG_CONFIG_HOME/gtk-3.0/gtk.css` will
still take precedence over your changes, as it uses the
`GTK_STYLE_PROVIDER_PRIORITY_USER` priority.

# Implements

[`StyleContextExt`](trait.StyleContextExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`StyleContextExtManual`](prelude/trait.StyleContextExtManual.html)
<!-- trait StyleContextExt -->
Trait containing all `StyleContext` methods.

# Implementors

[`StyleContext`](struct.StyleContext.html)
<!-- impl StyleContext::fn new -->
Creates a standalone `StyleContext`, this style context
won’t be attached to any widget, so you may want
to call `StyleContextExt::set_path` yourself.

This function is only useful when using the theming layer
separated from GTK+, if you are using `StyleContext` to
theme ``GtkWidgets``, use `WidgetExt::get_style_context`
in order to get a style context ready to theme the widget.

# Returns

A newly created `StyleContext`.
<!-- impl StyleContext::fn add_provider_for_screen -->
Adds a global style provider to `screen`, which will be used
in style construction for all ``GtkStyleContexts`` under `screen`.

GTK+ uses this to make styling information from `Settings`
available.

Note: If both priorities are the same, A `StyleProvider`
added through `StyleContextExt::add_provider` takes precedence
over another added through this function.
## `screen`
a `gdk::Screen`
## `provider`
a `StyleProvider`
## `priority`
the priority of the style provider. The lower
 it is, the earlier it will be used in the style
 construction. Typically this will be in the range
 between `GTK_STYLE_PROVIDER_PRIORITY_FALLBACK` and
 `GTK_STYLE_PROVIDER_PRIORITY_USER`
<!-- impl StyleContext::fn remove_provider_for_screen -->
Removes `provider` from the global style providers list in `screen`.
## `screen`
a `gdk::Screen`
## `provider`
a `StyleProvider`
<!-- impl StyleContext::fn reset_widgets -->
This function recomputes the styles for all widgets under a particular
`gdk::Screen`. This is useful when some global parameter has changed that
affects the appearance of all widgets, because when a widget gets a new
style, it will both redraw and recompute any cached information about
its appearance. As an example, it is used when the color scheme changes
in the related `Settings` object.
## `screen`
a `gdk::Screen`
<!-- trait StyleContextExt::fn add_class -->
Adds a style class to `self`, so posterior calls to
`StyleContextExt::get` or any of the gtk_render_*()
functions will make use of this new class for styling.

In the CSS file format, a `Entry` defining a “search”
class, would be matched by:


```CSS
entry.search { ... }
```

While any widget defining a “search” class would be
matched by:

```CSS
.search { ... }
```
## `class_name`
class name to use in styling
<!-- trait StyleContextExt::fn add_provider -->
Adds a style provider to `self`, to be used in style construction.
Note that a style provider added by this function only affects
the style of the widget to which `self` belongs. If you want
to affect the style of all widgets, use
`StyleContext::add_provider_for_screen`.

Note: If both priorities are the same, a `StyleProvider`
added through this function takes precedence over another added
through `StyleContext::add_provider_for_screen`.
## `provider`
a `StyleProvider`
## `priority`
the priority of the style provider. The lower
 it is, the earlier it will be used in the style
 construction. Typically this will be in the range
 between `GTK_STYLE_PROVIDER_PRIORITY_FALLBACK` and
 `GTK_STYLE_PROVIDER_PRIORITY_USER`
<!-- trait StyleContextExt::fn get -->
Retrieves several style property values from `self` for a
given state.

See `StyleContextExt::get_property` for details.
## `state`
state to retrieve the property values for
<!-- trait StyleContextExt::fn get_background_color -->
Gets the background color for a given state.

This function is far less useful than it seems, and it should not be used in
newly written code. CSS has no concept of "background color", as a background
can be an image, or a gradient, or any other pattern including solid colors.

The only reason why you would call `StyleContextExt::get_background_color` is
to use the returned value to draw the background with it; the correct way to
achieve this result is to use `gtk_render_background` instead, along with CSS
style classes to modify the color to be rendered.

# Deprecated since 3.16

Use `gtk_render_background` instead.
## `state`
state to retrieve the color for
## `color`
return value for the background color
<!-- trait StyleContextExt::fn get_border -->
Gets the border for a given state as a `Border`.

See `StyleContextExt::get_property` and
`GTK_STYLE_PROPERTY_BORDER_WIDTH` for details.
## `state`
state to retrieve the border for
## `border`
return value for the border settings
<!-- trait StyleContextExt::fn get_border_color -->
Gets the border color for a given state.

# Deprecated since 3.16

Use `gtk_render_frame` instead.
## `state`
state to retrieve the color for
## `color`
return value for the border color
<!-- trait StyleContextExt::fn get_color -->
Gets the foreground color for a given state.

See `StyleContextExt::get_property` and
`GTK_STYLE_PROPERTY_COLOR` for details.
## `state`
state to retrieve the color for
## `color`
return value for the foreground color
<!-- trait StyleContextExt::fn get_frame_clock -->
Returns the `gdk::FrameClock` to which `self` is attached.

# Returns

a `gdk::FrameClock`, or `None`
 if `self` does not have an attached frame clock.
<!-- trait StyleContextExt::fn get_junction_sides -->
Returns the sides where rendered elements connect visually with others.

# Returns

the junction sides
<!-- trait StyleContextExt::fn get_margin -->
Gets the margin for a given state as a `Border`.
See `gtk_style_property_get` and `GTK_STYLE_PROPERTY_MARGIN`
for details.
## `state`
state to retrieve the border for
## `margin`
return value for the margin settings
<!-- trait StyleContextExt::fn get_padding -->
Gets the padding for a given state as a `Border`.
See `StyleContextExt::get` and `GTK_STYLE_PROPERTY_PADDING`
for details.
## `state`
state to retrieve the padding for
## `padding`
return value for the padding settings
<!-- trait StyleContextExt::fn get_parent -->
Gets the parent context set via `StyleContextExt::set_parent`.
See that function for details.

# Returns

the parent context or `None`
<!-- trait StyleContextExt::fn get_path -->
Returns the widget path used for style matching.

# Returns

A `WidgetPath`
<!-- trait StyleContextExt::fn get_property -->
Gets a style property from `self` for the given state.

Note that not all CSS properties that are supported by GTK+ can be
retrieved in this way, since they may not be representable as `gobject::Value`.
GTK+ defines macros for a number of properties that can be used
with this function.

Note that passing a state other than the current state of `self`
is not recommended unless the style context has been saved with
`StyleContextExt::save`.

When `value` is no longer needed, `gobject::Value::unset` must be called
to free any allocated memory.
## `property`
style property name
## `state`
state to retrieve the property value for
## `value`
return location for the style property value
<!-- trait StyleContextExt::fn get_scale -->
Returns the scale used for assets.

# Returns

the scale
<!-- trait StyleContextExt::fn get_screen -->
Returns the `gdk::Screen` to which `self` is attached.

# Returns

a `gdk::Screen`.
<!-- trait StyleContextExt::fn get_section -->
Queries the location in the CSS where `property` was defined for the
current `self`. Note that the state to be queried is taken from
`StyleContextExt::get_state`.

If the location is not available, `None` will be returned. The
location might not be available for various reasons, such as the
property being overridden, `property` not naming a supported CSS
property or tracking of definitions being disabled for performance
reasons.

Shorthand CSS properties cannot be queried for a location and will
always return `None`.
## `property`
style property name

# Returns

`None` or the section where a value
for `property` was defined
<!-- trait StyleContextExt::fn get_state -->
Returns the state used for style matching.

This method should only be used to retrieve the `StateFlags`
to pass to `StyleContext` methods, like `StyleContextExt::get_padding`.
If you need to retrieve the current state of a `Widget`, use
`WidgetExt::get_state_flags`.

# Returns

the state flags
<!-- trait StyleContextExt::fn get_style -->
Retrieves several widget style properties from `self` according to the
current style.
<!-- trait StyleContextExt::fn get_style_property -->
Gets the value for a widget style property.

When `value` is no longer needed, `gobject::Value::unset` must be called
to free any allocated memory.
## `property_name`
the name of the widget style property
## `value`
Return location for the property value
<!-- trait StyleContextExt::fn get_style_valist -->
Retrieves several widget style properties from `self` according to the
current style.
## `args`
va_list of property name/return location pairs, followed by `None`
<!-- trait StyleContextExt::fn get_valist -->
Retrieves several style property values from `self` for a given state.

See `StyleContextExt::get_property` for details.
## `state`
state to retrieve the property values for
## `args`
va_list of property name/return location pairs, followed by `None`
<!-- trait StyleContextExt::fn has_class -->
Returns `true` if `self` currently has defined the
given class name.
## `class_name`
a class name

# Returns

`true` if `self` has `class_name` defined
<!-- trait StyleContextExt::fn list_classes -->
Returns the list of classes currently defined in `self`.

# Returns

a `glib::List` of
 strings with the currently defined classes. The contents
 of the list are owned by GTK+, but you must free the list
 itself with `glib::List::free` when you are done with it.
<!-- trait StyleContextExt::fn lookup_color -->
Looks up and resolves a color name in the `self` color map.
## `color_name`
color name to lookup
## `color`
Return location for the looked up color

# Returns

`true` if `color_name` was found and resolved, `false` otherwise
<!-- trait StyleContextExt::fn remove_class -->
Removes `class_name` from `self`.
## `class_name`
class name to remove
<!-- trait StyleContextExt::fn remove_provider -->
Removes `provider` from the style providers list in `self`.
## `provider`
a `StyleProvider`
<!-- trait StyleContextExt::fn restore -->
Restores `self` state to a previous stage.
See `StyleContextExt::save`.
<!-- trait StyleContextExt::fn save -->
Saves the `self` state, so temporary modifications done through
`StyleContextExt::add_class`, `StyleContextExt::remove_class`,
`StyleContextExt::set_state`, etc. can quickly be reverted
in one go through `StyleContextExt::restore`.

The matching call to `StyleContextExt::restore` must be done
before GTK returns to the main loop.
<!-- trait StyleContextExt::fn set_background -->
Sets the background of `window` to the background pattern or
color specified in `self` for its current state.

# Deprecated since 3.18

Use `gtk_render_background` instead.
 Note that clients still using this function are now responsible
 for calling this function again whenever `self` is invalidated.
## `window`
a `gdk::Window`
<!-- trait StyleContextExt::fn set_frame_clock -->
Attaches `self` to the given frame clock.

The frame clock is used for the timing of animations.

If you are using a `StyleContext` returned from
`WidgetExt::get_style_context`, you do not need to
call this yourself.
## `frame_clock`
a `gdk::FrameClock`
<!-- trait StyleContextExt::fn set_junction_sides -->
Sets the sides where rendered elements (mostly through
`gtk_render_frame`) will visually connect with other visual elements.

This is merely a hint that may or may not be honored
by themes.

Container widgets are expected to set junction hints as appropriate
for their children, so it should not normally be necessary to call
this function manually.
## `sides`
sides where rendered elements are visually connected to
 other elements
<!-- trait StyleContextExt::fn set_parent -->
Sets the parent style context for `self`. The parent style
context is used to implement
[inheritance](http://www.w3.org/TR/css3-cascade/`inheritance`)
of properties.

If you are using a `StyleContext` returned from
`WidgetExt::get_style_context`, the parent will be set for you.
## `parent`
the new parent or `None`
<!-- trait StyleContextExt::fn set_path -->
Sets the `WidgetPath` used for style matching. As a
consequence, the style will be regenerated to match
the new given path.

If you are using a `StyleContext` returned from
`WidgetExt::get_style_context`, you do not need to call
this yourself.
## `path`
a `WidgetPath`
<!-- trait StyleContextExt::fn set_scale -->
Sets the scale to use when getting image assets for the style.
## `scale`
scale
<!-- trait StyleContextExt::fn set_screen -->
Attaches `self` to the given screen.

The screen is used to add style information from “global” style
providers, such as the screen’s `Settings` instance.

If you are using a `StyleContext` returned from
`WidgetExt::get_style_context`, you do not need to
call this yourself.
## `screen`
a `gdk::Screen`
<!-- trait StyleContextExt::fn set_state -->
Sets the state to be used for style matching.
## `flags`
state to represent
<!-- trait StyleContextExt::fn to_string -->
Converts the style context into a string representation.

The string representation always includes information about
the name, state, id, visibility and style classes of the CSS
node that is backing `self`. Depending on the flags, more
information may be included.

This function is intended for testing and debugging of the
CSS implementation in GTK+. There are no guarantees about
the format of the returned string, it may change.

Feature: `v3_20`

## `flags`
Flags that determine what to print

# Returns

a newly allocated string representing `self`
<!-- trait StyleContextExt::fn connect_changed -->
The ::changed signal is emitted when there is a change in the
`StyleContext`.

For a `StyleContext` returned by `WidgetExt::get_style_context`, the
`Widget::style-updated` signal/vfunc might be more convenient to use.

This signal is useful when using the theming layer standalone.
<!-- trait StyleContextExt::fn get_property_parent -->
Sets or gets the style context’s parent. See `StyleContextExt::set_parent`
for details.
<!-- trait StyleContextExt::fn set_property_parent -->
Sets or gets the style context’s parent. See `StyleContextExt::set_parent`
for details.
<!-- struct StyleContextPrintFlags -->
Flags that modify the behavior of `StyleContextExt::to_string`.
New values may be added to this enumeration.
<!-- struct StyleContextPrintFlags::const RECURSE -->
Print the entire tree of
 CSS nodes starting at the style context's node
<!-- struct StyleContextPrintFlags::const SHOW_STYLE -->
Show the values of the
 CSS properties for each node

Feature: `v3_20`

<!-- struct StyleProperties -->
`[Deprecated since 3.16]` `StyleProperties` provides the storage for style information
that is used by `StyleContext` and other `StyleProvider`
implementations.

Before style properties can be stored in `StyleProperties`, they
must be registered with `StyleProperties::register_property`.

Unless you are writing a `StyleProvider` implementation, you
are unlikely to use this API directly, as `StyleContextExt::get`
and its variants are the preferred way to access styling information
from widget implementations and theming engine implementations
should use the APIs provided by `ThemingEngine` instead.

`StyleProperties` has been deprecated in GTK 3.16. The CSS
machinery does not use it anymore and all users of this object
have been deprecated.

# Implements

[`StylePropertiesExt`](trait.StylePropertiesExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`StyleProviderExt`](trait.StyleProviderExt.html)
<!-- trait StylePropertiesExt -->
`[Deprecated since 3.16]` Trait containing all `StyleProperties` methods.

# Implementors

[`StyleProperties`](struct.StyleProperties.html)
<!-- impl StyleProperties::fn new -->
Returns a newly created `StyleProperties`

# Deprecated since 3.16

`StyleProperties` are deprecated.

# Returns

a new `StyleProperties`
<!-- trait StylePropertiesExt::fn clear -->
Clears all style information from `self`.

# Deprecated since 3.16

`StyleProperties` are deprecated.
<!-- trait StylePropertiesExt::fn get -->
Retrieves several style property values from `self` for a
given state.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `state`
state to retrieve the property values for
<!-- trait StylePropertiesExt::fn get_property -->
Gets a style property from `self` for the given state. When done with `value`,
`gobject::Value::unset` needs to be called to free any allocated memory.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `property`
style property name
## `state`
state to retrieve the property value for
## `value`
return location for the style property value.

# Returns

`true` if the property exists in `self`, `false` otherwise
<!-- trait StylePropertiesExt::fn get_valist -->
Retrieves several style property values from `self` for a given state.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `state`
state to retrieve the property values for
## `args`
va_list of property name/return location pairs, followed by `None`
<!-- trait StylePropertiesExt::fn merge -->
Merges into `self` all the style information contained
in `props_to_merge`. If `replace` is `true`, the values
will be overwritten, if it is `false`, the older values
will prevail.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `props_to_merge`
a second `StyleProperties`
## `replace`
whether to replace values or not
<!-- trait StylePropertiesExt::fn set -->
Sets several style properties on `self`.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `state`
state to set the values for
<!-- trait StylePropertiesExt::fn set_property -->
Sets a styling property in `self`.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `property`
styling property to set
## `state`
state to set the value for
## `value`
new value for the property
<!-- trait StylePropertiesExt::fn set_valist -->
Sets several style properties on `self`.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `state`
state to set the values for
## `args`
va_list of property name/value pairs, followed by `None`
<!-- trait StylePropertiesExt::fn unset_property -->
Unsets a style property in `self`.

# Deprecated since 3.16

`StyleProperties` are deprecated.
## `property`
property to unset
## `state`
state to unset
<!-- struct StyleProvider -->
`StyleProvider` is an interface used to provide style information to a `StyleContext`.
See `StyleContextExt::add_provider` and `StyleContext::add_provider_for_screen`.

# Implements

[`StyleProviderExt`](trait.StyleProviderExt.html)
<!-- trait StyleProviderExt -->
Trait containing all `StyleProvider` methods.

# Implementors

[`CssProvider`](struct.CssProvider.html), [`Settings`](struct.Settings.html), [`StyleProperties`](struct.StyleProperties.html), [`StyleProvider`](struct.StyleProvider.html)
<!-- trait StyleProviderExt::fn get_style_property -->
Looks up a widget style property as defined by `self` for
the widget represented by `path`.
## `path`
`WidgetPath` to query
## `state`
state to query the style property for
## `pspec`
The `gobject::ParamSpec` to query
## `value`
return location for the property value

# Returns

`true` if the property was found and has a value, `false` otherwise
<!-- struct Switch -->
`Switch` is a widget that has two states: on or off. The user can control
which state should be active by clicking the empty area, or by dragging the
handle.

`Switch` can also handle situations where the underlying state changes with
a delay. See `Switch::state-set` for details.

# CSS nodes


```plain
switch
╰── slider
```

`Switch` has two css nodes, the main node with the name switch and a subnode
named slider. Neither of them is using any style classes.

# Implements

[`SwitchExt`](trait.SwitchExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`SwitchExtManual`](prelude/trait.SwitchExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait SwitchExt -->
Trait containing all `Switch` methods.

# Implementors

[`Switch`](struct.Switch.html)
<!-- impl Switch::fn new -->
Creates a new `Switch` widget.

# Returns

the newly created `Switch` instance
<!-- trait SwitchExt::fn get_active -->
Gets whether the `Switch` is in its “on” or “off” state.

# Returns

`true` if the `Switch` is active, and `false` otherwise
<!-- trait SwitchExt::fn get_state -->
Gets the underlying state of the `Switch`.

# Returns

the underlying state
<!-- trait SwitchExt::fn set_active -->
Changes the state of `self` to the desired one.
## `is_active`
`true` if `self` should be active, and `false` otherwise
<!-- trait SwitchExt::fn set_state -->
Sets the underlying state of the `Switch`.

Normally, this is the same as `Switch:active`, unless the switch
is set up for delayed state changes. This function is typically
called from a `Switch::state-set` signal handler.

See `Switch::state-set` for details.
## `state`
the new state
<!-- trait SwitchExt::fn connect_activate -->
The ::activate signal on `Switch` is an action signal and
emitting it causes the switch to animate.
Applications should never connect to this signal, but use the
notify::active signal.
<!-- trait SwitchExt::fn connect_state_set -->
The ::state-set signal on `Switch` is emitted to change the underlying
state. It is emitted when the user changes the switch position. The
default handler keeps the state in sync with the `Switch:active`
property.

To implement delayed state change, applications can connect to this signal,
initiate the change of the underlying state, and call `SwitchExt::set_state`
when the underlying state change is complete. The signal handler should
return `true` to prevent the default handler from running.

Visually, the underlying state is represented by the trough color of
the switch, while the `Switch:active` property is represented by the
position of the switch.
## `state`
the new state of the switch

# Returns

`true` to stop the signal emission
<!-- trait SwitchExt::fn get_property_active -->
Whether the `Switch` widget is in its on or off state.
<!-- trait SwitchExt::fn set_property_active -->
Whether the `Switch` widget is in its on or off state.
<!-- trait SwitchExt::fn get_property_state -->
The backend state that is controlled by the switch.
See `Switch::state-set` for details.
<!-- trait SwitchExt::fn set_property_state -->
The backend state that is controlled by the switch.
See `Switch::state-set` for details.
<!-- struct TargetEntry -->
A `TargetEntry` represents a single type of
data than can be supplied for by a widget for a selection
or for supplied or received during drag-and-drop.
<!-- impl TargetEntry::fn new -->
Makes a new `TargetEntry`.
## `target`
String identifier for target
## `flags`
Set of flags, see `TargetFlags`
## `info`
an ID that will be passed back to the application

# Returns

a pointer to a new `TargetEntry`.
 Free with `TargetEntry::free`
<!-- impl TargetEntry::fn copy -->
Makes a copy of a `TargetEntry` and its data.

# Returns

a pointer to a copy of `self`.
 Free with `TargetEntry::free`
<!-- impl TargetEntry::fn free -->
Frees a `TargetEntry` returned from
`TargetEntry::new` or `TargetEntry::copy`.
<!-- struct TargetFlags -->
The `TargetFlags` enumeration is used to specify
constraints on a `TargetEntry`.
<!-- struct TargetFlags::const SAME_APP -->
If this is set, the target will only be selected
 for drags within a single application.
<!-- struct TargetFlags::const SAME_WIDGET -->
If this is set, the target will only be selected
 for drags within a single widget.
<!-- struct TargetFlags::const OTHER_APP -->
If this is set, the target will not be selected
 for drags within a single application.
<!-- struct TargetFlags::const OTHER_WIDGET -->
If this is set, the target will not be selected
 for drags withing a single widget.
<!-- struct TargetList -->
A `TargetList`-struct is a reference counted list
of `TargetPair` and should be treated as
opaque.
<!-- impl TargetList::fn new -->
Creates a new `TargetList` from an array of `TargetEntry`.
## `targets`
Pointer to an array
 of `TargetEntry`
## `ntargets`
number of entries in `targets`.

# Returns

the new `TargetList`.
<!-- impl TargetList::fn add -->
Appends another target to a `TargetList`.
## `target`
the interned atom representing the target
## `flags`
the flags for this target
## `info`
an ID that will be passed back to the application
<!-- impl TargetList::fn add_image_targets -->
Appends the image targets supported by `SelectionData` to
the target list. All targets are added with the same `info`.
## `info`
an ID that will be passed back to the application
## `writable`
whether to add only targets for which GTK+ knows
 how to convert a pixbuf into the format
<!-- impl TargetList::fn add_rich_text_targets -->
Appends the rich text targets registered with
`TextBuffer::register_serialize_format` or
`TextBufferExt::register_deserialize_format` to the target list. All
targets are added with the same `info`.
## `info`
an ID that will be passed back to the application
## `deserializable`
if `true`, then deserializable rich text formats
 will be added, serializable formats otherwise.
## `buffer`
a `TextBuffer`.
<!-- impl TargetList::fn add_table -->
Prepends a table of `TargetEntry` to a target list.
## `targets`
the table of `TargetEntry`
## `ntargets`
number of targets in the table
<!-- impl TargetList::fn add_text_targets -->
Appends the text targets supported by `SelectionData` to
the target list. All targets are added with the same `info`.
## `info`
an ID that will be passed back to the application
<!-- impl TargetList::fn add_uri_targets -->
Appends the URI targets supported by `SelectionData` to
the target list. All targets are added with the same `info`.
## `info`
an ID that will be passed back to the application
<!-- impl TargetList::fn find -->
Looks up a given target in a `TargetList`.
## `target`
an interned atom representing the target to search for
## `info`
a pointer to the location to store
 application info for target, or `None`

# Returns

`true` if the target was found, otherwise `false`
<!-- impl TargetList::fn ref -->
Increases the reference count of a `TargetList` by one.

# Returns

the passed in `TargetList`.
<!-- impl TargetList::fn remove -->
Removes a target from a target list.
## `target`
the interned atom representing the target
<!-- impl TargetList::fn unref -->
Decreases the reference count of a `TargetList` by one.
If the resulting reference count is zero, frees the list.
<!-- struct TextAttributes -->
Using `TextAttributes` directly should rarely be necessary.
It’s primarily useful with `TextIter::get_attributes`.
As with most GTK+ structs, the fields in this struct should only
be read, never modified directly.
<!-- impl TextAttributes::fn new -->
Creates a `TextAttributes`, which describes
a set of properties on some text.

# Returns

a new `TextAttributes`,
 free with `TextAttributes::unref`.
<!-- impl TextAttributes::fn copy -->
Copies `self` and returns a new `TextAttributes`.

# Returns

a copy of `self`,
 free with `TextAttributes::unref`
<!-- impl TextAttributes::fn copy_values -->
Copies the values from `self` to `dest` so that `dest` has
the same values as `self`. Frees existing values in `dest`.
## `dest`
another `TextAttributes`
<!-- impl TextAttributes::fn ref -->
Increments the reference count on `self`.

# Returns

the `TextAttributes` that were passed in
<!-- impl TextAttributes::fn unref -->
Decrements the reference count on `self`, freeing the structure
if the reference count reaches 0.
<!-- struct TextBuffer -->
You may wish to begin by reading the
[text widget conceptual overview][TextWidget]
which gives an overview of all the objects and data
types related to the text widget and how they work together.

# Implements

[`TextBufferExt`](trait.TextBufferExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`TextBufferExtManual`](prelude/trait.TextBufferExtManual.html)
<!-- trait TextBufferExt -->
Trait containing all `TextBuffer` methods.

# Implementors

[`TextBuffer`](struct.TextBuffer.html)
<!-- impl TextBuffer::fn new -->
Creates a new text buffer.
## `table`
a tag table, or `None` to create a new one

# Returns

a new text buffer
<!-- trait TextBufferExt::fn add_mark -->
Adds the mark at position `where_`. The mark must not be added to
another buffer, and if its name is not `None` then there must not
be another mark in the buffer with the same name.

Emits the `TextBuffer::mark-set` signal as notification of the mark's
initial placement.
## `mark`
the mark to add
## `where_`
location to place mark
<!-- trait TextBufferExt::fn add_selection_clipboard -->
Adds `clipboard` to the list of clipboards in which the selection
contents of `self` are available. In most cases, `clipboard` will be
the `Clipboard` of type `GDK_SELECTION_PRIMARY` for a view of `self`.
## `clipboard`
a `Clipboard`
<!-- trait TextBufferExt::fn apply_tag -->
Emits the “apply-tag” signal on `self`. The default
handler for the signal applies `tag` to the given range.
`start` and `end` do not have to be in order.
## `tag`
a `TextTag`
## `start`
one bound of range to be tagged
## `end`
other bound of range to be tagged
<!-- trait TextBufferExt::fn apply_tag_by_name -->
Calls `TextTagTableExt::lookup` on the buffer’s tag table to
get a `TextTag`, then calls `TextBufferExt::apply_tag`.
## `name`
name of a named `TextTag`
## `start`
one bound of range to be tagged
## `end`
other bound of range to be tagged
<!-- trait TextBufferExt::fn backspace -->
Performs the appropriate action as if the user hit the delete
key with the cursor at the position specified by `iter`. In the
normal case a single character will be deleted, but when
combining accents are involved, more than one character can
be deleted, and when precomposed character and accent combinations
are involved, less than one character will be deleted.

Because the buffer is modified, all outstanding iterators become
invalid after calling this function; however, the `iter` will be
re-initialized to point to the location where text was deleted.
## `iter`
a position in `self`
## `interactive`
whether the deletion is caused by user interaction
## `default_editable`
whether the buffer is editable by default

# Returns

`true` if the buffer was modified
<!-- trait TextBufferExt::fn begin_user_action -->
Called to indicate that the buffer operations between here and a
call to `TextBufferExt::end_user_action` are part of a single
user-visible operation. The operations between
`TextBufferExt::begin_user_action` and
`TextBufferExt::end_user_action` can then be grouped when creating
an undo stack. `TextBuffer` maintains a count of calls to
`TextBufferExt::begin_user_action` that have not been closed with
a call to `TextBufferExt::end_user_action`, and emits the
“begin-user-action” and “end-user-action” signals only for the
outermost pair of calls. This allows you to build user actions
from other user actions.

The “interactive” buffer mutation functions, such as
`TextBufferExt::insert_interactive`, automatically call begin/end
user action around the buffer operations they perform, so there's
no need to add extra calls if you user action consists solely of a
single call to one of those functions.
<!-- trait TextBufferExt::fn copy_clipboard -->
Copies the currently-selected text to a clipboard.
## `clipboard`
the `Clipboard` object to copy to
<!-- trait TextBufferExt::fn create_child_anchor -->
This is a convenience function which simply creates a child anchor
with `TextChildAnchor::new` and inserts it into the buffer
with `TextBufferExt::insert_child_anchor`. The new anchor is
owned by the buffer; no reference count is returned to
the caller of `TextBufferExt::create_child_anchor`.
## `iter`
location in the buffer

# Returns

the created child anchor
<!-- trait TextBufferExt::fn create_mark -->
Creates a mark at position `where_`. If `mark_name` is `None`, the mark
is anonymous; otherwise, the mark can be retrieved by name using
`TextBufferExt::get_mark`. If a mark has left gravity, and text is
inserted at the mark’s current location, the mark will be moved to
the left of the newly-inserted text. If the mark has right gravity
(`left_gravity` = `false`), the mark will end up on the right of
newly-inserted text. The standard left-to-right cursor is a mark
with right gravity (when you type, the cursor stays on the right
side of the text you’re typing).

The caller of this function does not own a
reference to the returned `TextMark`, so you can ignore the
return value if you like. Marks are owned by the buffer and go
away when the buffer does.

Emits the `TextBuffer::mark-set` signal as notification of the mark's
initial placement.
## `mark_name`
name for mark, or `None`
## `where_`
location to place mark
## `left_gravity`
whether the mark has left gravity

# Returns

the new `TextMark` object
<!-- trait TextBufferExt::fn create_tag -->
Creates a tag and adds it to the tag table for `self`.
Equivalent to calling `TextTag::new` and then adding the
tag to the buffer’s tag table. The returned tag is owned by
the buffer’s tag table, so the ref count will be equal to one.

If `tag_name` is `None`, the tag is anonymous.

If `tag_name` is non-`None`, a tag called `tag_name` must not already
exist in the tag table for this buffer.

The `first_property_name` argument and subsequent arguments are a list
of properties to set on the tag, as with `gobject::ObjectExt::set`.
## `tag_name`
name of the new tag, or `None`
## `first_property_name`
name of first property to set, or `None`

# Returns

a new tag
<!-- trait TextBufferExt::fn cut_clipboard -->
Copies the currently-selected text to a clipboard, then deletes
said text if it’s editable.
## `clipboard`
the `Clipboard` object to cut to
## `default_editable`
default editability of the buffer
<!-- trait TextBufferExt::fn delete -->
Deletes text between `start` and `end`. The order of `start` and `end`
is not actually relevant; `TextBufferExt::delete` will reorder
them. This function actually emits the “delete-range” signal, and
the default handler of that signal deletes the text. Because the
buffer is modified, all outstanding iterators become invalid after
calling this function; however, the `start` and `end` will be
re-initialized to point to the location where text was deleted.
## `start`
a position in `self`
## `end`
another position in `self`
<!-- trait TextBufferExt::fn delete_interactive -->
Deletes all editable text in the given range.
Calls `TextBufferExt::delete` for each editable sub-range of
[`start`,`end`). `start` and `end` are revalidated to point to
the location of the last deleted range, or left untouched if
no text was deleted.
## `start_iter`
start of range to delete
## `end_iter`
end of range
## `default_editable`
whether the buffer is editable by default

# Returns

whether some text was actually deleted
<!-- trait TextBufferExt::fn delete_mark -->
Deletes `mark`, so that it’s no longer located anywhere in the
buffer. Removes the reference the buffer holds to the mark, so if
you haven’t called `gobject::ObjectExt::ref` on the mark, it will be freed. Even
if the mark isn’t freed, most operations on `mark` become
invalid, until it gets added to a buffer again with
`TextBufferExt::add_mark`. Use `TextMarkExt::get_deleted` to
find out if a mark has been removed from its buffer.
The `TextBuffer::mark-deleted` signal will be emitted as notification after
the mark is deleted.
## `mark`
a `TextMark` in `self`
<!-- trait TextBufferExt::fn delete_mark_by_name -->
Deletes the mark named `name`; the mark must exist. See
`TextBufferExt::delete_mark` for details.
## `name`
name of a mark in `self`
<!-- trait TextBufferExt::fn delete_selection -->
Deletes the range between the “insert” and “selection_bound” marks,
that is, the currently-selected text. If `interactive` is `true`,
the editability of the selection will be considered (users can’t delete
uneditable text).
## `interactive`
whether the deletion is caused by user interaction
## `default_editable`
whether the buffer is editable by default

# Returns

whether there was a non-empty selection to delete
<!-- trait TextBufferExt::fn deserialize -->
This function deserializes rich text in format `format` and inserts
it at `iter`.

`formats` to be used must be registered using
`TextBufferExt::register_deserialize_format` or
`TextBufferExt::register_deserialize_tagset` beforehand.
## `content_buffer`
the `TextBuffer` to deserialize into
## `format`
the rich text format to use for deserializing
## `iter`
insertion point for the deserialized text
## `data`
data to deserialize
## `length`
length of `data`

# Returns

`true` on success, `false` otherwise.
<!-- trait TextBufferExt::fn deserialize_get_can_create_tags -->
This functions returns the value set with
`TextBufferExt::deserialize_set_can_create_tags`
## `format`
a `gdk::Atom` representing a registered rich text format

# Returns

whether deserializing this format may create tags
<!-- trait TextBufferExt::fn deserialize_set_can_create_tags -->
Use this function to allow a rich text deserialization function to
create new tags in the receiving buffer. Note that using this
function is almost always a bad idea, because the rich text
functions you register should know how to map the rich text format
they handler to your text buffers set of tags.

The ability of creating new (arbitrary!) tags in the receiving buffer
is meant for special rich text formats like the internal one that
is registered using `TextBufferExt::register_deserialize_tagset`,
because that format is essentially a dump of the internal structure
of the source buffer, including its tag names.

You should allow creation of tags only if you know what you are
doing, e.g. if you defined a tagset name for your application
suite’s text buffers and you know that it’s fine to receive new
tags from these buffers, because you know that your application can
handle the newly created tags.
## `format`
a `gdk::Atom` representing a registered rich text format
## `can_create_tags`
whether deserializing this format may create tags
<!-- trait TextBufferExt::fn end_user_action -->
Should be paired with a call to `TextBufferExt::begin_user_action`.
See that function for a full explanation.
<!-- trait TextBufferExt::fn get_bounds -->
Retrieves the first and last iterators in the buffer, i.e. the
entire buffer lies within the range [`start`,`end`).
## `start`
iterator to initialize with first position in the buffer
## `end`
iterator to initialize with the end iterator
<!-- trait TextBufferExt::fn get_char_count -->
Gets the number of characters in the buffer; note that characters
and bytes are not the same, you can’t e.g. expect the contents of
the buffer in string form to be this many bytes long. The character
count is cached, so this function is very fast.

# Returns

number of characters in the buffer
<!-- trait TextBufferExt::fn get_copy_target_list -->
This function returns the list of targets this text buffer can
provide for copying and as DND source. The targets in the list are
added with `info` values from the `TextBufferTargetInfo` enum,
using `TargetList::add_rich_text_targets` and
`TargetList::add_text_targets`.

# Returns

the `TargetList`
<!-- trait TextBufferExt::fn get_deserialize_formats -->
This function returns the rich text deserialize formats registered
with `self` using `TextBufferExt::register_deserialize_format` or
`TextBufferExt::register_deserialize_tagset`
## `n_formats`
return location for the number of formats

# Returns

an array of
 ``GdkAtoms`` representing the registered formats.
<!-- trait TextBufferExt::fn get_end_iter -->
Initializes `iter` with the “end iterator,” one past the last valid
character in the text buffer. If dereferenced with
`TextIter::get_char`, the end iterator has a character value of 0.
The entire buffer lies in the range from the first position in
the buffer (call `TextBufferExt::get_start_iter` to get
character position 0) to the end iterator.
## `iter`
iterator to initialize
<!-- trait TextBufferExt::fn get_has_selection -->
Indicates whether the buffer has some text currently selected.

# Returns

`true` if the there is text selected
<!-- trait TextBufferExt::fn get_insert -->
Returns the mark that represents the cursor (insertion point).
Equivalent to calling `TextBufferExt::get_mark` to get the mark
named “insert”, but very slightly more efficient, and involves less
typing.

# Returns

insertion point mark
<!-- trait TextBufferExt::fn get_iter_at_child_anchor -->
Obtains the location of `anchor` within `self`.
## `iter`
an iterator to be initialized
## `anchor`
a child anchor that appears in `self`
<!-- trait TextBufferExt::fn get_iter_at_line -->
Initializes `iter` to the start of the given line. If `line_number` is greater
than the number of lines in the `self`, the end iterator is returned.
## `iter`
iterator to initialize
## `line_number`
line number counting from 0
<!-- trait TextBufferExt::fn get_iter_at_line_index -->
Obtains an iterator pointing to `byte_index` within the given line.
`byte_index` must be the start of a UTF-8 character. Note bytes, not
characters; UTF-8 may encode one character as multiple bytes.

Before the 3.20 version, it was not allowed to pass an invalid location.

Since the 3.20 version, if `line_number` is greater than the number of lines
in the `self`, the end iterator is returned. And if `byte_index` is off the
end of the line, the iterator at the end of the line is returned.
## `iter`
iterator to initialize
## `line_number`
line number counting from 0
## `byte_index`
byte index from start of line
<!-- trait TextBufferExt::fn get_iter_at_line_offset -->
Obtains an iterator pointing to `char_offset` within the given line. Note
characters, not bytes; UTF-8 may encode one character as multiple bytes.

Before the 3.20 version, it was not allowed to pass an invalid location.

Since the 3.20 version, if `line_number` is greater than the number of lines
in the `self`, the end iterator is returned. And if `char_offset` is off the
end of the line, the iterator at the end of the line is returned.
## `iter`
iterator to initialize
## `line_number`
line number counting from 0
## `char_offset`
char offset from start of line
<!-- trait TextBufferExt::fn get_iter_at_mark -->
Initializes `iter` with the current position of `mark`.
## `iter`
iterator to initialize
## `mark`
a `TextMark` in `self`
<!-- trait TextBufferExt::fn get_iter_at_offset -->
Initializes `iter` to a position `char_offset` chars from the start
of the entire buffer. If `char_offset` is -1 or greater than the number
of characters in the buffer, `iter` is initialized to the end iterator,
the iterator one past the last valid character in the buffer.
## `iter`
iterator to initialize
## `char_offset`
char offset from start of buffer, counting from 0, or -1
<!-- trait TextBufferExt::fn get_line_count -->
Obtains the number of lines in the buffer. This value is cached, so
the function is very fast.

# Returns

number of lines in the buffer
<!-- trait TextBufferExt::fn get_mark -->
Returns the mark named `name` in buffer `self`, or `None` if no such
mark exists in the buffer.
## `name`
a mark name

# Returns

a `TextMark`, or `None`
<!-- trait TextBufferExt::fn get_modified -->
Indicates whether the buffer has been modified since the last call
to `TextBufferExt::set_modified` set the modification flag to
`false`. Used for example to enable a “save” function in a text
editor.

# Returns

`true` if the buffer has been modified
<!-- trait TextBufferExt::fn get_paste_target_list -->
This function returns the list of targets this text buffer supports
for pasting and as DND destination. The targets in the list are
added with `info` values from the `TextBufferTargetInfo` enum,
using `TargetList::add_rich_text_targets` and
`TargetList::add_text_targets`.

# Returns

the `TargetList`
<!-- trait TextBufferExt::fn get_selection_bound -->
Returns the mark that represents the selection bound. Equivalent
to calling `TextBufferExt::get_mark` to get the mark named
“selection_bound”, but very slightly more efficient, and involves
less typing.

The currently-selected text in `self` is the region between the
“selection_bound” and “insert” marks. If “selection_bound” and
“insert” are in the same place, then there is no current selection.
`TextBufferExt::get_selection_bounds` is another convenient function
for handling the selection, if you just want to know whether there’s a
selection and what its bounds are.

# Returns

selection bound mark
<!-- trait TextBufferExt::fn get_selection_bounds -->
Returns `true` if some text is selected; places the bounds
of the selection in `start` and `end` (if the selection has length 0,
then `start` and `end` are filled in with the same value).
`start` and `end` will be in ascending order. If `start` and `end` are
NULL, then they are not filled in, but the return value still indicates
whether text is selected.
## `start`
iterator to initialize with selection start
## `end`
iterator to initialize with selection end

# Returns

whether the selection has nonzero length
<!-- trait TextBufferExt::fn get_serialize_formats -->
This function returns the rich text serialize formats registered
with `self` using `TextBuffer::register_serialize_format` or
`TextBufferExt::register_serialize_tagset`
## `n_formats`
return location for the number of formats

# Returns

an array of
 ``GdkAtoms`` representing the registered formats.
<!-- trait TextBufferExt::fn get_slice -->
Returns the text in the range [`start`,`end`). Excludes undisplayed
text (text marked with tags that set the invisibility attribute) if
`include_hidden_chars` is `false`. The returned string includes a
0xFFFC character whenever the buffer contains
embedded images, so byte and character indexes into
the returned string do correspond to byte
and character indexes into the buffer. Contrast with
`TextBufferExt::get_text`. Note that 0xFFFC can occur in normal
text as well, so it is not a reliable indicator that a pixbuf or
widget is in the buffer.
## `start`
start of a range
## `end`
end of a range
## `include_hidden_chars`
whether to include invisible text

# Returns

an allocated UTF-8 string
<!-- trait TextBufferExt::fn get_start_iter -->
Initialized `iter` with the first position in the text buffer. This
is the same as using `TextBufferExt::get_iter_at_offset` to get
the iter at character offset 0.
## `iter`
iterator to initialize
<!-- trait TextBufferExt::fn get_tag_table -->
Get the `TextTagTable` associated with this buffer.

# Returns

the buffer’s tag table
<!-- trait TextBufferExt::fn get_text -->
Returns the text in the range [`start`,`end`). Excludes undisplayed
text (text marked with tags that set the invisibility attribute) if
`include_hidden_chars` is `false`. Does not include characters
representing embedded images, so byte and character indexes into
the returned string do not correspond to byte
and character indexes into the buffer. Contrast with
`TextBufferExt::get_slice`.
## `start`
start of a range
## `end`
end of a range
## `include_hidden_chars`
whether to include invisible text

# Returns

an allocated UTF-8 string
<!-- trait TextBufferExt::fn insert -->
Inserts `len` bytes of `text` at position `iter`. If `len` is -1,
`text` must be nul-terminated and will be inserted in its
entirety. Emits the “insert-text” signal; insertion actually occurs
in the default handler for the signal. `iter` is invalidated when
insertion occurs (because the buffer contents change), but the
default signal handler revalidates it to point to the end of the
inserted text.
## `iter`
a position in the buffer
## `text`
text in UTF-8 format
## `len`
length of text in bytes, or -1
<!-- trait TextBufferExt::fn insert_at_cursor -->
Simply calls `TextBufferExt::insert`, using the current
cursor position as the insertion point.
## `text`
text in UTF-8 format
## `len`
length of text, in bytes
<!-- trait TextBufferExt::fn insert_child_anchor -->
Inserts a child widget anchor into the text buffer at `iter`. The
anchor will be counted as one character in character counts, and
when obtaining the buffer contents as a string, will be represented
by the Unicode “object replacement character” 0xFFFC. Note that the
“slice” variants for obtaining portions of the buffer as a string
include this character for child anchors, but the “text” variants do
not. E.g. see `TextBufferExt::get_slice` and
`TextBufferExt::get_text`. Consider
`TextBufferExt::create_child_anchor` as a more convenient
alternative to this function. The buffer will add a reference to
the anchor, so you can unref it after insertion.
## `iter`
location to insert the anchor
## `anchor`
a `TextChildAnchor`
<!-- trait TextBufferExt::fn insert_interactive -->
Like `TextBufferExt::insert`, but the insertion will not occur if
`iter` is at a non-editable location in the buffer. Usually you
want to prevent insertions at ineditable locations if the insertion
results from a user action (is interactive).

`default_editable` indicates the editability of text that doesn't
have a tag affecting editability applied to it. Typically the
result of `TextViewExt::get_editable` is appropriate here.
## `iter`
a position in `self`
## `text`
some UTF-8 text
## `len`
length of text in bytes, or -1
## `default_editable`
default editability of buffer

# Returns

whether text was actually inserted
<!-- trait TextBufferExt::fn insert_interactive_at_cursor -->
Calls `TextBufferExt::insert_interactive` at the cursor
position.

`default_editable` indicates the editability of text that doesn't
have a tag affecting editability applied to it. Typically the
result of `TextViewExt::get_editable` is appropriate here.
## `text`
text in UTF-8 format
## `len`
length of text in bytes, or -1
## `default_editable`
default editability of buffer

# Returns

whether text was actually inserted
<!-- trait TextBufferExt::fn insert_markup -->
Inserts the text in `markup` at position `iter`. `markup` will be inserted
in its entirety and must be nul-terminated and valid UTF-8. Emits the
`TextBuffer::insert-text` signal, possibly multiple times; insertion
actually occurs in the default handler for the signal. `iter` will point
to the end of the inserted text on return.

Feature: `v3_16`

## `iter`
location to insert the markup
## `markup`
a nul-terminated UTF-8 string containing [Pango markup][PangoMarkupFormat]
## `len`
length of `markup` in bytes, or -1
<!-- trait TextBufferExt::fn insert_pixbuf -->
Inserts an image into the text buffer at `iter`. The image will be
counted as one character in character counts, and when obtaining
the buffer contents as a string, will be represented by the Unicode
“object replacement character” 0xFFFC. Note that the “slice”
variants for obtaining portions of the buffer as a string include
this character for pixbufs, but the “text” variants do
not. e.g. see `TextBufferExt::get_slice` and
`TextBufferExt::get_text`.
## `iter`
location to insert the pixbuf
## `pixbuf`
a `gdk_pixbuf::Pixbuf`
<!-- trait TextBufferExt::fn insert_range -->
Copies text, tags, and pixbufs between `start` and `end` (the order
of `start` and `end` doesn’t matter) and inserts the copy at `iter`.
Used instead of simply getting/inserting text because it preserves
images and tags. If `start` and `end` are in a different buffer from
`self`, the two buffers must share the same tag table.

Implemented via emissions of the insert_text and apply_tag signals,
so expect those.
## `iter`
a position in `self`
## `start`
a position in a `TextBuffer`
## `end`
another position in the same buffer as `start`
<!-- trait TextBufferExt::fn insert_range_interactive -->
Same as `TextBufferExt::insert_range`, but does nothing if the
insertion point isn’t editable. The `default_editable` parameter
indicates whether the text is editable at `iter` if no tags
enclosing `iter` affect editability. Typically the result of
`TextViewExt::get_editable` is appropriate here.
## `iter`
a position in `self`
## `start`
a position in a `TextBuffer`
## `end`
another position in the same buffer as `start`
## `default_editable`
default editability of the buffer

# Returns

whether an insertion was possible at `iter`
<!-- trait TextBufferExt::fn insert_with_tags -->
Inserts `text` into `self` at `iter`, applying the list of tags to
the newly-inserted text. The last tag specified must be `None` to
terminate the list. Equivalent to calling `TextBufferExt::insert`,
then `TextBufferExt::apply_tag` on the inserted text;
`TextBufferExt::insert_with_tags` is just a convenience function.
## `iter`
an iterator in `self`
## `text`
UTF-8 text
## `len`
length of `text`, or -1
## `first_tag`
first tag to apply to `text`
<!-- trait TextBufferExt::fn insert_with_tags_by_name -->
Same as `TextBufferExt::insert_with_tags`, but allows you
to pass in tag names instead of tag objects.
## `iter`
position in `self`
## `text`
UTF-8 text
## `len`
length of `text`, or -1
## `first_tag_name`
name of a tag to apply to `text`
<!-- trait TextBufferExt::fn move_mark -->
Moves `mark` to the new location `where_`. Emits the `TextBuffer::mark-set`
signal as notification of the move.
## `mark`
a `TextMark`
## `where_`
new location for `mark` in `self`
<!-- trait TextBufferExt::fn move_mark_by_name -->
Moves the mark named `name` (which must exist) to location `where_`.
See `TextBufferExt::move_mark` for details.
## `name`
name of a mark
## `where_`
new location for mark
<!-- trait TextBufferExt::fn paste_clipboard -->
Pastes the contents of a clipboard. If `override_location` is `None`, the
pasted text will be inserted at the cursor position, or the buffer selection
will be replaced if the selection is non-empty.

Note: pasting is asynchronous, that is, we’ll ask for the paste data and
return, and at some point later after the main loop runs, the paste data will
be inserted.
## `clipboard`
the `Clipboard` to paste from
## `override_location`
location to insert pasted text, or `None`
## `default_editable`
whether the buffer is editable by default
<!-- trait TextBufferExt::fn place_cursor -->
This function moves the “insert” and “selection_bound” marks
simultaneously. If you move them to the same place in two steps
with `TextBufferExt::move_mark`, you will temporarily select a
region in between their old and new locations, which can be pretty
inefficient since the temporarily-selected region will force stuff
to be recalculated. This function moves them as a unit, which can
be optimized.
## `where_`
where to put the cursor
<!-- trait TextBufferExt::fn register_deserialize_format -->
This function registers a rich text deserialization `function` along with
its `mime_type` with the passed `self`.
## `mime_type`
the format’s mime-type
## `function`
the deserialize function to register
## `user_data`
`function`’s user_data
## `user_data_destroy`
a function to call when `user_data` is no longer needed

# Returns

the `gdk::Atom` that corresponds to the
 newly registered format’s mime-type.
<!-- trait TextBufferExt::fn register_deserialize_tagset -->
This function registers GTK+’s internal rich text serialization
format with the passed `self`. See
`TextBufferExt::register_serialize_tagset` for details.
## `tagset_name`
an optional tagset name, on `None`

# Returns

the `gdk::Atom` that corresponds to the
 newly registered format’s mime-type.
<!-- trait TextBufferExt::fn register_serialize_format -->
This function registers a rich text serialization `function` along with
its `mime_type` with the passed `self`.
## `mime_type`
the format’s mime-type
## `function`
the serialize function to register
## `user_data`
`function`’s user_data
## `user_data_destroy`
a function to call when `user_data` is no longer needed

# Returns

the `gdk::Atom` that corresponds to the
 newly registered format’s mime-type.
<!-- trait TextBufferExt::fn register_serialize_tagset -->
This function registers GTK+’s internal rich text serialization
format with the passed `self`. The internal format does not comply
to any standard rich text format and only works between `TextBuffer`
instances. It is capable of serializing all of a text buffer’s tags
and embedded pixbufs.

This function is just a wrapper around
`TextBuffer::register_serialize_format`. The mime type used
for registering is “application/x-gtk-text-buffer-rich-text”, or
“application/x-gtk-text-buffer-rich-text;format=`tagset_name`” if a
`tagset_name` was passed.

The `tagset_name` can be used to restrict the transfer of rich text
to buffers with compatible sets of tags, in order to avoid unknown
tags from being pasted. It is probably the common case to pass an
identifier != `None` here, since the `None` tagset requires the
receiving buffer to deal with with pasting of arbitrary tags.
## `tagset_name`
an optional tagset name, on `None`

# Returns

the `gdk::Atom` that corresponds to the
 newly registered format’s mime-type.
<!-- trait TextBufferExt::fn remove_all_tags -->
Removes all tags in the range between `start` and `end`. Be careful
with this function; it could remove tags added in code unrelated to
the code you’re currently writing. That is, using this function is
probably a bad idea if you have two or more unrelated code sections
that add tags.
## `start`
one bound of range to be untagged
## `end`
other bound of range to be untagged
<!-- trait TextBufferExt::fn remove_selection_clipboard -->
Removes a `Clipboard` added with
`TextBufferExt::add_selection_clipboard`.
## `clipboard`
a `Clipboard` added to `self` by
 `TextBufferExt::add_selection_clipboard`
<!-- trait TextBufferExt::fn remove_tag -->
Emits the “remove-tag” signal. The default handler for the signal
removes all occurrences of `tag` from the given range. `start` and
`end` don’t have to be in order.
## `tag`
a `TextTag`
## `start`
one bound of range to be untagged
## `end`
other bound of range to be untagged
<!-- trait TextBufferExt::fn remove_tag_by_name -->
Calls `TextTagTableExt::lookup` on the buffer’s tag table to
get a `TextTag`, then calls `TextBufferExt::remove_tag`.
## `name`
name of a `TextTag`
## `start`
one bound of range to be untagged
## `end`
other bound of range to be untagged
<!-- trait TextBufferExt::fn select_range -->
This function moves the “insert” and “selection_bound” marks
simultaneously. If you move them in two steps
with `TextBufferExt::move_mark`, you will temporarily select a
region in between their old and new locations, which can be pretty
inefficient since the temporarily-selected region will force stuff
to be recalculated. This function moves them as a unit, which can
be optimized.
## `ins`
where to put the “insert” mark
## `bound`
where to put the “selection_bound” mark
<!-- trait TextBufferExt::fn serialize -->
This function serializes the portion of text between `start`
and `end` in the rich text format represented by `format`.

`formats` to be used must be registered using
`TextBuffer::register_serialize_format` or
`TextBufferExt::register_serialize_tagset` beforehand.
## `content_buffer`
the `TextBuffer` to serialize
## `format`
the rich text format to use for serializing
## `start`
start of block of text to serialize
## `end`
end of block of test to serialize
## `length`
return location for the length of the serialized data

# Returns

the serialized
 data, encoded as `format`
<!-- trait TextBufferExt::fn set_modified -->
Used to keep track of whether the buffer has been modified since the
last time it was saved. Whenever the buffer is saved to disk, call
gtk_text_buffer_set_modified (`self`, FALSE). When the buffer is modified,
it will automatically toggled on the modified bit again. When the modified
bit flips, the buffer emits the `TextBuffer::modified-changed` signal.
## `setting`
modification flag setting
<!-- trait TextBufferExt::fn set_text -->
Deletes current contents of `self`, and inserts `text` instead. If
`len` is -1, `text` must be nul-terminated. `text` must be valid UTF-8.
## `text`
UTF-8 text to insert
## `len`
length of `text` in bytes
<!-- trait TextBufferExt::fn unregister_deserialize_format -->
This function unregisters a rich text format that was previously
registered using `TextBufferExt::register_deserialize_format` or
`TextBufferExt::register_deserialize_tagset`.
## `format`
a `gdk::Atom` representing a registered rich text format.
<!-- trait TextBufferExt::fn unregister_serialize_format -->
This function unregisters a rich text format that was previously
registered using `TextBuffer::register_serialize_format` or
`TextBufferExt::register_serialize_tagset`
## `format`
a `gdk::Atom` representing a registered rich text format.
<!-- trait TextBufferExtManual::fn connect_apply_tag -->
The ::apply-tag signal is emitted to apply a tag to a
range of text in a `TextBuffer`.
Applying actually occurs in the default handler.

Note that if your handler runs before the default handler it must not
invalidate the `start` and `end` iters (or has to revalidate them).

See also:
`TextBufferExt::apply_tag`,
`TextBufferExt::insert_with_tags`,
`TextBufferExt::insert_range`.
## `tag`
the applied tag
## `start`
the start of the range the tag is applied to
## `end`
the end of the range the tag is applied to
<!-- trait TextBufferExt::fn connect_begin_user_action -->
The ::begin-user-action signal is emitted at the beginning of a single
user-visible operation on a `TextBuffer`.

See also:
`TextBufferExt::begin_user_action`,
`TextBufferExt::insert_interactive`,
`TextBufferExt::insert_range_interactive`,
`TextBufferExt::delete_interactive`,
`TextBufferExt::backspace`,
`TextBufferExt::delete_selection`.
<!-- trait TextBufferExt::fn connect_changed -->
The ::changed signal is emitted when the content of a `TextBuffer`
has changed.
<!-- trait TextBufferExtManual::fn connect_delete_range -->
The ::delete-range signal is emitted to delete a range
from a `TextBuffer`.

Note that if your handler runs before the default handler it must not
invalidate the `start` and `end` iters (or has to revalidate them).
The default signal handler revalidates the `start` and `end` iters to
both point to the location where text was deleted. Handlers
which run after the default handler (see `g_signal_connect_after`)
do not have access to the deleted text.

See also: `TextBufferExt::delete`.
## `start`
the start of the range to be deleted
## `end`
the end of the range to be deleted
<!-- trait TextBufferExt::fn connect_end_user_action -->
The ::end-user-action signal is emitted at the end of a single
user-visible operation on the `TextBuffer`.

See also:
`TextBufferExt::end_user_action`,
`TextBufferExt::insert_interactive`,
`TextBufferExt::insert_range_interactive`,
`TextBufferExt::delete_interactive`,
`TextBufferExt::backspace`,
`TextBufferExt::delete_selection`,
`TextBufferExt::backspace`.
<!-- trait TextBufferExtManual::fn connect_insert_child_anchor -->
The ::insert-child-anchor signal is emitted to insert a
`TextChildAnchor` in a `TextBuffer`.
Insertion actually occurs in the default handler.

Note that if your handler runs before the default handler it must
not invalidate the `location` iter (or has to revalidate it).
The default signal handler revalidates it to be placed after the
inserted `anchor`.

See also: `TextBufferExt::insert_child_anchor`.
## `location`
position to insert `anchor` in `textbuffer`
## `anchor`
the `TextChildAnchor` to be inserted
<!-- trait TextBufferExtManual::fn connect_insert_pixbuf -->
The ::insert-pixbuf signal is emitted to insert a `gdk_pixbuf::Pixbuf`
in a `TextBuffer`. Insertion actually occurs in the default handler.

Note that if your handler runs before the default handler it must not
invalidate the `location` iter (or has to revalidate it).
The default signal handler revalidates it to be placed after the
inserted `pixbuf`.

See also: `TextBufferExt::insert_pixbuf`.
## `location`
position to insert `pixbuf` in `textbuffer`
## `pixbuf`
the `gdk_pixbuf::Pixbuf` to be inserted
<!-- trait TextBufferExtManual::fn connect_insert_text -->
The ::insert-text signal is emitted to insert text in a `TextBuffer`.
Insertion actually occurs in the default handler.

Note that if your handler runs before the default handler it must not
invalidate the `location` iter (or has to revalidate it).
The default signal handler revalidates it to point to the end of the
inserted text.

See also:
`TextBufferExt::insert`,
`TextBufferExt::insert_range`.
## `location`
position to insert `text` in `textbuffer`
## `text`
the UTF-8 text to be inserted
## `len`
length of the inserted text in bytes
<!-- trait TextBufferExt::fn connect_mark_deleted -->
The ::mark-deleted signal is emitted as notification
after a `TextMark` is deleted.

See also:
`TextBufferExt::delete_mark`.
## `mark`
The mark that was deleted
<!-- trait TextBufferExt::fn connect_mark_set -->
The ::mark-set signal is emitted as notification
after a `TextMark` is set.

See also:
`TextBufferExt::create_mark`,
`TextBufferExt::move_mark`.
## `location`
The location of `mark` in `textbuffer`
## `mark`
The mark that is set
<!-- trait TextBufferExt::fn connect_modified_changed -->
The ::modified-changed signal is emitted when the modified bit of a
`TextBuffer` flips.

See also:
`TextBufferExt::set_modified`.
<!-- trait TextBufferExt::fn connect_paste_done -->
The paste-done signal is emitted after paste operation has been completed.
This is useful to properly scroll the view to the end of the pasted text.
See `TextBufferExt::paste_clipboard` for more details.
## `clipboard`
the `Clipboard` pasted from
<!-- trait TextBufferExtManual::fn connect_remove_tag -->
The ::remove-tag signal is emitted to remove all occurrences of `tag` from
a range of text in a `TextBuffer`.
Removal actually occurs in the default handler.

Note that if your handler runs before the default handler it must not
invalidate the `start` and `end` iters (or has to revalidate them).

See also:
`TextBufferExt::remove_tag`.
## `tag`
the tag to be removed
## `start`
the start of the range the tag is removed from
## `end`
the end of the range the tag is removed from
<!-- trait TextBufferExt::fn get_property_copy_target_list -->
The list of targets this buffer supports for clipboard copying
and as DND source.
<!-- trait TextBufferExt::fn get_property_cursor_position -->
The position of the insert mark (as offset from the beginning
of the buffer). It is useful for getting notified when the
cursor moves.
<!-- trait TextBufferExt::fn get_property_has_selection -->
Whether the buffer has some text currently selected.
<!-- trait TextBufferExt::fn get_property_paste_target_list -->
The list of targets this buffer supports for clipboard pasting
and as DND destination.
<!-- trait TextBufferExt::fn get_property_text -->
The text content of the buffer. Without child widgets and images,
see `TextBufferExt::get_text` for more information.
<!-- trait TextBufferExt::fn set_property_text -->
The text content of the buffer. Without child widgets and images,
see `TextBufferExt::get_text` for more information.
<!-- struct TextChildAnchor -->
A `TextChildAnchor` is a spot in the buffer where child widgets can
be “anchored” (inserted inline, as if they were characters). The anchor
can have multiple widgets anchored, to allow for multiple views.

# Implements

[`TextChildAnchorExt`](trait.TextChildAnchorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait TextChildAnchorExt -->
Trait containing all `TextChildAnchor` methods.

# Implementors

[`TextChildAnchor`](struct.TextChildAnchor.html)
<!-- impl TextChildAnchor::fn new -->
Creates a new `TextChildAnchor`. Usually you would then insert
it into a `TextBuffer` with `TextBufferExt::insert_child_anchor`.
To perform the creation and insertion in one step, use the
convenience function `TextBufferExt::create_child_anchor`.

# Returns

a new `TextChildAnchor`
<!-- trait TextChildAnchorExt::fn get_deleted -->
Determines whether a child anchor has been deleted from
the buffer. Keep in mind that the child anchor will be
unreferenced when removed from the buffer, so you need to
hold your own reference (with `gobject::ObjectExt::ref`) if you plan
to use this function — otherwise all deleted child anchors
will also be finalized.

# Returns

`true` if the child anchor has been deleted from its buffer
<!-- trait TextChildAnchorExt::fn get_widgets -->
Gets a list of all widgets anchored at this child anchor.
The returned list should be freed with `glib::List::free`.

# Returns

list of widgets anchored at `self`
<!-- enum TextDirection -->
Reading directions for text.
<!-- enum TextDirection::variant None -->
No direction.
<!-- enum TextDirection::variant Ltr -->
Left to right text direction.
<!-- enum TextDirection::variant Rtl -->
Right to left text direction.
<!-- enum TextExtendSelection -->
Granularity types that extend the text selection. Use the
`TextView::extend-selection` signal to customize the selection.
<!-- enum TextExtendSelection::variant Word -->
Selects the current word. It is triggered by
 a double-click for example.
<!-- enum TextExtendSelection::variant Line -->
Selects the current line. It is triggered by
 a triple-click for example.

Feature: `v3_16`

<!-- struct TextIter -->
You may wish to begin by reading the
[text widget conceptual overview][TextWidget]
which gives an overview of all the objects and data
types related to the text widget and how they work together.
<!-- impl TextIter::fn assign -->
Assigns the value of `other` to `self`. This function
is not useful in applications, because iterators can be assigned
with `GtkTextIter i = j;`. The
function is used by language bindings.
## `other`
another `TextIter`
<!-- impl TextIter::fn backward_char -->
Moves backward by one character offset. Returns `true` if movement
was possible; if `self` was the first in the buffer (character
offset 0), `TextIter::backward_char` returns `false` for convenience when
writing loops.

# Returns

whether movement was possible
<!-- impl TextIter::fn backward_chars -->
Moves `count` characters backward, if possible (if `count` would move
past the start or end of the buffer, moves to the start or end of
the buffer). The return value indicates whether the iterator moved
onto a dereferenceable position; if the iterator didn’t move, or
moved onto the end iterator, then `false` is returned. If `count` is 0,
the function does nothing and returns `false`.
## `count`
number of characters to move

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn backward_cursor_position -->
Like `TextIter::forward_cursor_position`, but moves backward.

# Returns

`true` if we moved
<!-- impl TextIter::fn backward_cursor_positions -->
Moves up to `count` cursor positions. See
`TextIter::forward_cursor_position` for details.
## `count`
number of positions to move

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn backward_find_char -->
Same as `TextIter::forward_find_char`, but goes backward from `self`.
## `pred`
function to be called on each character
## `user_data`
user data for `pred`
## `limit`
search limit, or `None` for none

# Returns

whether a match was found
<!-- impl TextIter::fn backward_line -->
Moves `self` to the start of the previous line. Returns `true` if
`self` could be moved; i.e. if `self` was at character offset 0, this
function returns `false`. Therefore if `self` was already on line 0,
but not at the start of the line, `self` is snapped to the start of
the line and the function returns `true`. (Note that this implies that
in a loop calling this function, the line number may not change on
every iteration, if your first iteration is on line 0.)

# Returns

whether `self` moved
<!-- impl TextIter::fn backward_lines -->
Moves `count` lines backward, if possible (if `count` would move
past the start or end of the buffer, moves to the start or end of
the buffer). The return value indicates whether the iterator moved
onto a dereferenceable position; if the iterator didn’t move, or
moved onto the end iterator, then `false` is returned. If `count` is 0,
the function does nothing and returns `false`. If `count` is negative,
moves forward by 0 - `count` lines.
## `count`
number of lines to move backward

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn backward_search -->
Same as `TextIter::forward_search`, but moves backward.

`match_end` will never be set to a `TextIter` located after `self`, even if
there is a possible `match_start` before or at `self`.
## `str`
search string
## `flags`
bitmask of flags affecting the search
## `match_start`
return location for start of match, or `None`
## `match_end`
return location for end of match, or `None`
## `limit`
location of last possible `match_start`, or `None` for start of buffer

# Returns

whether a match was found
<!-- impl TextIter::fn backward_sentence_start -->
Moves backward to the previous sentence start; if `self` is already at
the start of a sentence, moves backward to the next one. Sentence
boundaries are determined by Pango and should be correct for nearly
any language (if not, the correct fix would be to the Pango text
boundary algorithms).

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn backward_sentence_starts -->
Calls `TextIter::backward_sentence_start` up to `count` times,
or until it returns `false`. If `count` is negative, moves forward
instead of backward.
## `count`
number of sentences to move

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn backward_to_tag_toggle -->
Moves backward to the next toggle (on or off) of the
`TextTag` `tag`, or to the next toggle of any tag if
`tag` is `None`. If no matching tag toggles are found,
returns `false`, otherwise `true`. Does not return toggles
located at `self`, only toggles before `self`. Sets `self`
to the location of the toggle, or the start of the buffer
if no toggle is found.
## `tag`
a `TextTag`, or `None`

# Returns

whether we found a tag toggle before `self`
<!-- impl TextIter::fn backward_visible_cursor_position -->
Moves `self` forward to the previous visible cursor position. See
`TextIter::backward_cursor_position` for details.

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn backward_visible_cursor_positions -->
Moves up to `count` visible cursor positions. See
`TextIter::backward_cursor_position` for details.
## `count`
number of positions to move

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn backward_visible_line -->
Moves `self` to the start of the previous visible line. Returns `true` if
`self` could be moved; i.e. if `self` was at character offset 0, this
function returns `false`. Therefore if `self` was already on line 0,
but not at the start of the line, `self` is snapped to the start of
the line and the function returns `true`. (Note that this implies that
in a loop calling this function, the line number may not change on
every iteration, if your first iteration is on line 0.)

# Returns

whether `self` moved
<!-- impl TextIter::fn backward_visible_lines -->
Moves `count` visible lines backward, if possible (if `count` would move
past the start or end of the buffer, moves to the start or end of
the buffer). The return value indicates whether the iterator moved
onto a dereferenceable position; if the iterator didn’t move, or
moved onto the end iterator, then `false` is returned. If `count` is 0,
the function does nothing and returns `false`. If `count` is negative,
moves forward by 0 - `count` lines.
## `count`
number of lines to move backward

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn backward_visible_word_start -->
Moves backward to the previous visible word start. (If `self` is currently
on a word start, moves backward to the next one after that.) Word breaks
are determined by Pango and should be correct for nearly any
language (if not, the correct fix would be to the Pango word break
algorithms).

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn backward_visible_word_starts -->
Calls `TextIter::backward_visible_word_start` up to `count` times.
## `count`
number of times to move

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn backward_word_start -->
Moves backward to the previous word start. (If `self` is currently on a
word start, moves backward to the next one after that.) Word breaks
are determined by Pango and should be correct for nearly any
language (if not, the correct fix would be to the Pango word break
algorithms).

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn backward_word_starts -->
Calls `TextIter::backward_word_start` up to `count` times.
## `count`
number of times to move

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn begins_tag -->
Returns `true` if `tag` is toggled on at exactly this point. If `tag`
is `None`, returns `true` if any tag is toggled on at this point.

Note that if `TextIter::begins_tag` returns `true`, it means that `self` is
at the beginning of the tagged range, and that the
character at `self` is inside the tagged range. In other
words, unlike `TextIter::ends_tag`, if `TextIter::begins_tag` returns
`true`, `TextIter::has_tag` will also return `true` for the same
parameters.

# Deprecated since 3.20

Use `TextIter::starts_tag` instead.
## `tag`
a `TextTag`, or `None`

# Returns

whether `self` is the start of a range tagged with `tag`
<!-- impl TextIter::fn can_insert -->
Considering the default editability of the buffer, and tags that
affect editability, determines whether text inserted at `self` would
be editable. If text inserted at `self` would be editable then the
user should be allowed to insert text at `self`.
`TextBufferExt::insert_interactive` uses this function to decide
whether insertions are allowed at a given position.
## `default_editability`
`true` if text is editable by default

# Returns

whether text inserted at `self` would be editable
<!-- impl TextIter::fn compare -->
A `qsort`-style function that returns negative if `self` is less than
`rhs`, positive if `self` is greater than `rhs`, and 0 if they’re equal.
Ordering is in character offset order, i.e. the first character in the buffer
is less than the second character in the buffer.
## `rhs`
another `TextIter`

# Returns

-1 if `self` is less than `rhs`, 1 if `self` is greater, 0 if they are equal
<!-- impl TextIter::fn copy -->
Creates a dynamically-allocated copy of an iterator. This function
is not useful in applications, because iterators can be copied with a
simple assignment (`GtkTextIter i = j;`). The
function is used by language bindings.

# Returns

a copy of the `self`, free with `TextIter::free`
<!-- impl TextIter::fn editable -->
Returns whether the character at `self` is within an editable region
of text. Non-editable text is “locked” and can’t be changed by the
user via `TextView`. This function is simply a convenience
wrapper around `TextIter::get_attributes`. If no tags applied
to this text affect editability, `default_setting` will be returned.

You don’t want to use this function to decide whether text can be
inserted at `self`, because for insertion you don’t want to know
whether the char at `self` is inside an editable range, you want to
know whether a new character inserted at `self` would be inside an
editable range. Use `TextIter::can_insert` to handle this
case.
## `default_setting`
`true` if text is editable by default

# Returns

whether `self` is inside an editable range
<!-- impl TextIter::fn ends_line -->
Returns `true` if `self` points to the start of the paragraph
delimiter characters for a line (delimiters will be either a
newline, a carriage return, a carriage return followed by a
newline, or a Unicode paragraph separator character). Note that an
iterator pointing to the \n of a \r\n pair will not be counted as
the end of a line, the line ends before the \r. The end iterator is
considered to be at the end of a line, even though there are no
paragraph delimiter chars there.

# Returns

whether `self` is at the end of a line
<!-- impl TextIter::fn ends_sentence -->
Determines whether `self` ends a sentence. Sentence boundaries are
determined by Pango and should be correct for nearly any language
(if not, the correct fix would be to the Pango text boundary
algorithms).

# Returns

`true` if `self` is at the end of a sentence.
<!-- impl TextIter::fn ends_tag -->
Returns `true` if `tag` is toggled off at exactly this point. If `tag`
is `None`, returns `true` if any tag is toggled off at this point.

Note that if `TextIter::ends_tag` returns `true`, it means that `self` is
at the end of the tagged range, but that the character
at `self` is outside the tagged range. In other words,
unlike `TextIter::starts_tag`, if `TextIter::ends_tag` returns `true`,
`TextIter::has_tag` will return `false` for the same parameters.
## `tag`
a `TextTag`, or `None`

# Returns

whether `self` is the end of a range tagged with `tag`
<!-- impl TextIter::fn ends_word -->
Determines whether `self` ends a natural-language word. Word breaks
are determined by Pango and should be correct for nearly any
language (if not, the correct fix would be to the Pango word break
algorithms).

# Returns

`true` if `self` is at the end of a word
<!-- impl TextIter::fn equal -->
Tests whether two iterators are equal, using the fastest possible
mechanism. This function is very fast; you can expect it to perform
better than e.g. getting the character offset for each iterator and
comparing the offsets yourself. Also, it’s a bit faster than
`TextIter::compare`.
## `rhs`
another `TextIter`

# Returns

`true` if the iterators point to the same place in the buffer
<!-- impl TextIter::fn forward_char -->
Moves `self` forward by one character offset. Note that images
embedded in the buffer occupy 1 character slot, so
`TextIter::forward_char` may actually move onto an image instead
of a character, if you have images in your buffer. If `self` is the
end iterator or one character before it, `self` will now point at
the end iterator, and `TextIter::forward_char` returns `false` for
convenience when writing loops.

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn forward_chars -->
Moves `count` characters if possible (if `count` would move past the
start or end of the buffer, moves to the start or end of the
buffer). The return value indicates whether the new position of
`self` is different from its original position, and dereferenceable
(the last iterator in the buffer is not dereferenceable). If `count`
is 0, the function does nothing and returns `false`.
## `count`
number of characters to move, may be negative

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn forward_cursor_position -->
Moves `self` forward by a single cursor position. Cursor positions
are (unsurprisingly) positions where the cursor can appear. Perhaps
surprisingly, there may not be a cursor position between all
characters. The most common example for European languages would be
a carriage return/newline sequence. For some Unicode characters,
the equivalent of say the letter “a” with an accent mark will be
represented as two characters, first the letter then a "combining
mark" that causes the accent to be rendered; so the cursor can’t go
between those two characters. See also the `pango::LogAttr`-struct and
`pango_break` function.

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn forward_cursor_positions -->
Moves up to `count` cursor positions. See
`TextIter::forward_cursor_position` for details.
## `count`
number of positions to move

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn forward_find_char -->
Advances `self`, calling `pred` on each character. If
`pred` returns `true`, returns `true` and stops scanning.
If `pred` never returns `true`, `self` is set to `limit` if
`limit` is non-`None`, otherwise to the end iterator.
## `pred`
a function to be called on each character
## `user_data`
user data for `pred`
## `limit`
search limit, or `None` for none

# Returns

whether a match was found
<!-- impl TextIter::fn forward_line -->
Moves `self` to the start of the next line. If the iter is already on the
last line of the buffer, moves the iter to the end of the current line.
If after the operation, the iter is at the end of the buffer and not
dereferencable, returns `false`. Otherwise, returns `true`.

# Returns

whether `self` can be dereferenced
<!-- impl TextIter::fn forward_lines -->
Moves `count` lines forward, if possible (if `count` would move
past the start or end of the buffer, moves to the start or end of
the buffer). The return value indicates whether the iterator moved
onto a dereferenceable position; if the iterator didn’t move, or
moved onto the end iterator, then `false` is returned. If `count` is 0,
the function does nothing and returns `false`. If `count` is negative,
moves backward by 0 - `count` lines.
## `count`
number of lines to move forward

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn forward_search -->
Searches forward for `str`. Any match is returned by setting
`match_start` to the first character of the match and `match_end` to the
first character after the match. The search will not continue past
`limit`. Note that a search is a linear or O(n) operation, so you
may wish to use `limit` to avoid locking up your UI on large
buffers.

`match_start` will never be set to a `TextIter` located before `self`, even if
there is a possible `match_end` after or at `self`.
## `str`
a search string
## `flags`
flags affecting how the search is done
## `match_start`
return location for start of match, or `None`
## `match_end`
return location for end of match, or `None`
## `limit`
location of last possible `match_end`, or `None` for the end of the buffer

# Returns

whether a match was found
<!-- impl TextIter::fn forward_sentence_end -->
Moves forward to the next sentence end. (If `self` is at the end of
a sentence, moves to the next end of sentence.) Sentence
boundaries are determined by Pango and should be correct for nearly
any language (if not, the correct fix would be to the Pango text
boundary algorithms).

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn forward_sentence_ends -->
Calls `TextIter::forward_sentence_end` `count` times (or until
`TextIter::forward_sentence_end` returns `false`). If `count` is
negative, moves backward instead of forward.
## `count`
number of sentences to move

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn forward_to_end -->
Moves `self` forward to the “end iterator,” which points one past the last
valid character in the buffer. `TextIter::get_char` called on the
end iterator returns 0, which is convenient for writing loops.
<!-- impl TextIter::fn forward_to_line_end -->
Moves the iterator to point to the paragraph delimiter characters,
which will be either a newline, a carriage return, a carriage
return/newline in sequence, or the Unicode paragraph separator
character. If the iterator is already at the paragraph delimiter
characters, moves to the paragraph delimiter characters for the
next line. If `self` is on the last line in the buffer, which does
not end in paragraph delimiters, moves to the end iterator (end of
the last line), and returns `false`.

# Returns

`true` if we moved and the new location is not the end iterator
<!-- impl TextIter::fn forward_to_tag_toggle -->
Moves forward to the next toggle (on or off) of the
`TextTag` `tag`, or to the next toggle of any tag if
`tag` is `None`. If no matching tag toggles are found,
returns `false`, otherwise `true`. Does not return toggles
located at `self`, only toggles after `self`. Sets `self` to
the location of the toggle, or to the end of the buffer
if no toggle is found.
## `tag`
a `TextTag`, or `None`

# Returns

whether we found a tag toggle after `self`
<!-- impl TextIter::fn forward_visible_cursor_position -->
Moves `self` forward to the next visible cursor position. See
`TextIter::forward_cursor_position` for details.

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn forward_visible_cursor_positions -->
Moves up to `count` visible cursor positions. See
`TextIter::forward_cursor_position` for details.
## `count`
number of positions to move

# Returns

`true` if we moved and the new position is dereferenceable
<!-- impl TextIter::fn forward_visible_line -->
Moves `self` to the start of the next visible line. Returns `true` if there
was a next line to move to, and `false` if `self` was simply moved to
the end of the buffer and is now not dereferenceable, or if `self` was
already at the end of the buffer.

# Returns

whether `self` can be dereferenced
<!-- impl TextIter::fn forward_visible_lines -->
Moves `count` visible lines forward, if possible (if `count` would move
past the start or end of the buffer, moves to the start or end of
the buffer). The return value indicates whether the iterator moved
onto a dereferenceable position; if the iterator didn’t move, or
moved onto the end iterator, then `false` is returned. If `count` is 0,
the function does nothing and returns `false`. If `count` is negative,
moves backward by 0 - `count` lines.
## `count`
number of lines to move forward

# Returns

whether `self` moved and is dereferenceable
<!-- impl TextIter::fn forward_visible_word_end -->
Moves forward to the next visible word end. (If `self` is currently on a
word end, moves forward to the next one after that.) Word breaks
are determined by Pango and should be correct for nearly any
language (if not, the correct fix would be to the Pango word break
algorithms).

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn forward_visible_word_ends -->
Calls `TextIter::forward_visible_word_end` up to `count` times.
## `count`
number of times to move

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn forward_word_end -->
Moves forward to the next word end. (If `self` is currently on a
word end, moves forward to the next one after that.) Word breaks
are determined by Pango and should be correct for nearly any
language (if not, the correct fix would be to the Pango word break
algorithms).

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn forward_word_ends -->
Calls `TextIter::forward_word_end` up to `count` times.
## `count`
number of times to move

# Returns

`true` if `self` moved and is not the end iterator
<!-- impl TextIter::fn free -->
Free an iterator allocated on the heap. This function
is intended for use in language bindings, and is not
especially useful for applications, because iterators can
simply be allocated on the stack.
<!-- impl TextIter::fn get_attributes -->
Computes the effect of any tags applied to this spot in the
text. The `values` parameter should be initialized to the default
settings you wish to use if no tags are in effect. You’d typically
obtain the defaults from `TextViewExt::get_default_attributes`.

`TextIter::get_attributes` will modify `values`, applying the
effects of any tags present at `self`. If any tags affected `values`,
the function returns `true`.
## `values`
a `TextAttributes` to be filled in

# Returns

`true` if `values` was modified
<!-- impl TextIter::fn get_buffer -->
Returns the `TextBuffer` this iterator is associated with.

# Returns

the buffer
<!-- impl TextIter::fn get_bytes_in_line -->
Returns the number of bytes in the line containing `self`,
including the paragraph delimiters.

# Returns

number of bytes in the line
<!-- impl TextIter::fn get_char -->
The Unicode character at this iterator is returned. (Equivalent to
operator* on a C++ iterator.) If the element at this iterator is a
non-character element, such as an image embedded in the buffer, the
Unicode “unknown” character 0xFFFC is returned. If invoked on
the end iterator, zero is returned; zero is not a valid Unicode character.
So you can write a loop which ends when `TextIter::get_char`
returns 0.

# Returns

a Unicode character, or 0 if `self` is not dereferenceable
<!-- impl TextIter::fn get_chars_in_line -->
Returns the number of characters in the line containing `self`,
including the paragraph delimiters.

# Returns

number of characters in the line
<!-- impl TextIter::fn get_child_anchor -->
If the location at `self` contains a child anchor, the
anchor is returned (with no new reference count added). Otherwise,
`None` is returned.

# Returns

the anchor at `self`
<!-- impl TextIter::fn get_language -->
A convenience wrapper around `TextIter::get_attributes`,
which returns the language in effect at `self`. If no tags affecting
language apply to `self`, the return value is identical to that of
`gtk_get_default_language`.

# Returns

language in effect at `self`
<!-- impl TextIter::fn get_line -->
Returns the line number containing the iterator. Lines in
a `TextBuffer` are numbered beginning with 0 for the first
line in the buffer.

# Returns

a line number
<!-- impl TextIter::fn get_line_index -->
Returns the byte index of the iterator, counting
from the start of a newline-terminated line.
Remember that `TextBuffer` encodes text in
UTF-8, and that characters can require a variable
number of bytes to represent.

# Returns

distance from start of line, in bytes
<!-- impl TextIter::fn get_line_offset -->
Returns the character offset of the iterator,
counting from the start of a newline-terminated line.
The first character on the line has offset 0.

# Returns

offset from start of line
<!-- impl TextIter::fn get_marks -->
Returns a list of all `TextMark` at this location. Because marks
are not iterable (they don’t take up any "space" in the buffer,
they are just marks in between iterable locations), multiple marks
can exist in the same place. The returned list is not in any
meaningful order.

# Returns

list of `TextMark`
<!-- impl TextIter::fn get_offset -->
Returns the character offset of an iterator.
Each character in a `TextBuffer` has an offset,
starting with 0 for the first character in the buffer.
Use `TextBufferExt::get_iter_at_offset` to convert an
offset back into an iterator.

# Returns

a character offset
<!-- impl TextIter::fn get_pixbuf -->
If the element at `self` is a pixbuf, the pixbuf is returned
(with no new reference count added). Otherwise,
`None` is returned.

# Returns

the pixbuf at `self`
<!-- impl TextIter::fn get_slice -->
Returns the text in the given range. A “slice” is an array of
characters encoded in UTF-8 format, including the Unicode “unknown”
character 0xFFFC for iterable non-character elements in the buffer,
such as images. Because images are encoded in the slice, byte and
character offsets in the returned array will correspond to byte
offsets in the text buffer. Note that 0xFFFC can occur in normal
text as well, so it is not a reliable indicator that a pixbuf or
widget is in the buffer.
## `end`
iterator at end of a range

# Returns

slice of text from the buffer
<!-- impl TextIter::fn get_tags -->
Returns a list of tags that apply to `self`, in ascending order of
priority (highest-priority tags are last). The `TextTag` in the
list don’t have a reference added, but you have to free the list
itself.

# Returns

list of `TextTag`
<!-- impl TextIter::fn get_text -->
Returns text in the given range. If the range
contains non-text elements such as images, the character and byte
offsets in the returned string will not correspond to character and
byte offsets in the buffer. If you want offsets to correspond, see
`TextIter::get_slice`.
## `end`
iterator at end of a range

# Returns

array of characters from the buffer
<!-- impl TextIter::fn get_toggled_tags -->
Returns a list of `TextTag` that are toggled on or off at this
point. (If `toggled_on` is `true`, the list contains tags that are
toggled on.) If a tag is toggled on at `self`, then some non-empty
range of characters following `self` has that tag applied to it. If
a tag is toggled off, then some non-empty range following `self`
does not have the tag applied to it.
## `toggled_on`
`true` to get toggled-on tags

# Returns

tags toggled at this point
<!-- impl TextIter::fn get_visible_line_index -->
Returns the number of bytes from the start of the
line to the given `self`, not counting bytes that
are invisible due to tags with the “invisible” flag
toggled on.

# Returns

byte index of `self` with respect to the start of the line
<!-- impl TextIter::fn get_visible_line_offset -->
Returns the offset in characters from the start of the
line to the given `self`, not counting characters that
are invisible due to tags with the “invisible” flag
toggled on.

# Returns

offset in visible characters from the start of the line
<!-- impl TextIter::fn get_visible_slice -->
Like `TextIter::get_slice`, but invisible text is not included.
Invisible text is usually invisible because a `TextTag` with the
“invisible” attribute turned on has been applied to it.
## `end`
iterator at end of range

# Returns

slice of text from the buffer
<!-- impl TextIter::fn get_visible_text -->
Like `TextIter::get_text`, but invisible text is not included.
Invisible text is usually invisible because a `TextTag` with the
“invisible” attribute turned on has been applied to it.
## `end`
iterator at end of range

# Returns

string containing visible text in the
range
<!-- impl TextIter::fn has_tag -->
Returns `true` if `self` points to a character that is part of a range tagged
with `tag`. See also `TextIter::starts_tag` and `TextIter::ends_tag`.
## `tag`
a `TextTag`

# Returns

whether `self` is tagged with `tag`
<!-- impl TextIter::fn in_range -->
Checks whether `self` falls in the range [`start`, `end`).
`start` and `end` must be in ascending order.
## `start`
start of range
## `end`
end of range

# Returns

`true` if `self` is in the range
<!-- impl TextIter::fn inside_sentence -->
Determines whether `self` is inside a sentence (as opposed to in
between two sentences, e.g. after a period and before the first
letter of the next sentence). Sentence boundaries are determined
by Pango and should be correct for nearly any language (if not, the
correct fix would be to the Pango text boundary algorithms).

# Returns

`true` if `self` is inside a sentence.
<!-- impl TextIter::fn inside_word -->
Determines whether the character pointed by `self` is part of a
natural-language word (as opposed to say inside some whitespace). Word
breaks are determined by Pango and should be correct for nearly any language
(if not, the correct fix would be to the Pango word break algorithms).

Note that if `TextIter::starts_word` returns `true`, then this function
returns `true` too, since `self` points to the first character of the word.

# Returns

`true` if `self` is inside a word
<!-- impl TextIter::fn is_cursor_position -->
See `TextIter::forward_cursor_position` or `pango::LogAttr` or
`pango_break` for details on what a cursor position is.

# Returns

`true` if the cursor can be placed at `self`
<!-- impl TextIter::fn is_end -->
Returns `true` if `self` is the end iterator, i.e. one past the last
dereferenceable iterator in the buffer. `TextIter::is_end` is
the most efficient way to check whether an iterator is the end
iterator.

# Returns

whether `self` is the end iterator
<!-- impl TextIter::fn is_start -->
Returns `true` if `self` is the first iterator in the buffer, that is
if `self` has a character offset of 0.

# Returns

whether `self` is the first in the buffer
<!-- impl TextIter::fn order -->
Swaps the value of `self` and `second` if `second` comes before
`self` in the buffer. That is, ensures that `self` and `second` are
in sequence. Most text buffer functions that take a range call this
automatically on your behalf, so there’s no real reason to call it yourself
in those cases. There are some exceptions, such as `TextIter::in_range`,
that expect a pre-sorted range.
## `second`
another `TextIter`
<!-- impl TextIter::fn set_line -->
Moves iterator `self` to the start of the line `line_number`. If
`line_number` is negative or larger than the number of lines in the
buffer, moves `self` to the start of the last line in the buffer.
## `line_number`
line number (counted from 0)
<!-- impl TextIter::fn set_line_index -->
Same as `TextIter::set_line_offset`, but works with a
byte index. The given byte index must be at
the start of a character, it can’t be in the middle of a UTF-8
encoded character.
## `byte_on_line`
a byte index relative to the start of `self`’s current line
<!-- impl TextIter::fn set_line_offset -->
Moves `self` within a line, to a new character
(not byte) offset. The given character offset must be less than or
equal to the number of characters in the line; if equal, `self`
moves to the start of the next line. See
`TextIter::set_line_index` if you have a byte index rather than
a character offset.
## `char_on_line`
a character offset relative to the start of `self`’s current line
<!-- impl TextIter::fn set_offset -->
Sets `self` to point to `char_offset`. `char_offset` counts from the start
of the entire text buffer, starting with 0.
## `char_offset`
a character number
<!-- impl TextIter::fn set_visible_line_index -->
Like `TextIter::set_line_index`, but the index is in visible
bytes, i.e. text with a tag making it invisible is not counted
in the index.
## `byte_on_line`
a byte index
<!-- impl TextIter::fn set_visible_line_offset -->
Like `TextIter::set_line_offset`, but the offset is in visible
characters, i.e. text with a tag making it invisible is not
counted in the offset.
## `char_on_line`
a character offset
<!-- impl TextIter::fn starts_line -->
Returns `true` if `self` begins a paragraph,
i.e. if `TextIter::get_line_offset` would return 0.
However this function is potentially more efficient than
`TextIter::get_line_offset` because it doesn’t have to compute
the offset, it just has to see whether it’s 0.

# Returns

whether `self` begins a line
<!-- impl TextIter::fn starts_sentence -->
Determines whether `self` begins a sentence. Sentence boundaries are
determined by Pango and should be correct for nearly any language
(if not, the correct fix would be to the Pango text boundary
algorithms).

# Returns

`true` if `self` is at the start of a sentence.
<!-- impl TextIter::fn starts_tag -->
Returns `true` if `tag` is toggled on at exactly this point. If `tag`
is `None`, returns `true` if any tag is toggled on at this point.

Note that if `TextIter::starts_tag` returns `true`, it means that `self` is
at the beginning of the tagged range, and that the
character at `self` is inside the tagged range. In other
words, unlike `TextIter::ends_tag`, if `TextIter::starts_tag` returns
`true`, `TextIter::has_tag` will also return `true` for the same
parameters.

Feature: `v3_20`

## `tag`
a `TextTag`, or `None`

# Returns

whether `self` is the start of a range tagged with `tag`
<!-- impl TextIter::fn starts_word -->
Determines whether `self` begins a natural-language word. Word
breaks are determined by Pango and should be correct for nearly any
language (if not, the correct fix would be to the Pango word break
algorithms).

# Returns

`true` if `self` is at the start of a word
<!-- impl TextIter::fn toggles_tag -->
This is equivalent to (`TextIter::starts_tag` ||
`TextIter::ends_tag`), i.e. it tells you whether a range with
`tag` applied to it begins or ends at `self`.
## `tag`
a `TextTag`, or `None`

# Returns

whether `tag` is toggled on or off at `self`
<!-- struct TextMark -->
You may wish to begin by reading the
[text widget conceptual overview][TextWidget]
which gives an overview of all the objects and data
types related to the text widget and how they work together.

A `TextMark` is like a bookmark in a text buffer; it preserves a position in
the text. You can convert the mark to an iterator using
`TextBufferExt::get_iter_at_mark`. Unlike iterators, marks remain valid across
buffer mutations, because their behavior is defined when text is inserted or
deleted. When text containing a mark is deleted, the mark remains in the
position originally occupied by the deleted text. When text is inserted at a
mark, a mark with “left gravity” will be moved to the
beginning of the newly-inserted text, and a mark with “right
gravity” will be moved to the end.

Note that “left” and “right” here refer to logical direction (left
is the toward the start of the buffer); in some languages such as
Hebrew the logically-leftmost text is not actually on the left when
displayed.

Marks are reference counted, but the reference count only controls the validity
of the memory; marks can be deleted from the buffer at any time with
`TextBufferExt::delete_mark`. Once deleted from the buffer, a mark is
essentially useless.

Marks optionally have names; these can be convenient to avoid passing the
`TextMark` object around.

Marks are typically created using the `TextBufferExt::create_mark` function.

# Implements

[`TextMarkExt`](trait.TextMarkExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait TextMarkExt -->
Trait containing all `TextMark` methods.

# Implementors

[`TextMark`](struct.TextMark.html)
<!-- impl TextMark::fn new -->
Creates a text mark. Add it to a buffer using `TextBufferExt::add_mark`.
If `name` is `None`, the mark is anonymous; otherwise, the mark can be
retrieved by name using `TextBufferExt::get_mark`. If a mark has left
gravity, and text is inserted at the mark’s current location, the mark
will be moved to the left of the newly-inserted text. If the mark has
right gravity (`left_gravity` = `false`), the mark will end up on the
right of newly-inserted text. The standard left-to-right cursor is a
mark with right gravity (when you type, the cursor stays on the right
side of the text you’re typing).
## `name`
mark name or `None`
## `left_gravity`
whether the mark should have left gravity

# Returns

new `TextMark`
<!-- trait TextMarkExt::fn get_buffer -->
Gets the buffer this mark is located inside,
or `None` if the mark is deleted.

# Returns

the mark’s `TextBuffer`
<!-- trait TextMarkExt::fn get_deleted -->
Returns `true` if the mark has been removed from its buffer
with `TextBufferExt::delete_mark`. See `TextBufferExt::add_mark`
for a way to add it to a buffer again.

# Returns

whether the mark is deleted
<!-- trait TextMarkExt::fn get_left_gravity -->
Determines whether the mark has left gravity.

# Returns

`true` if the mark has left gravity, `false` otherwise
<!-- trait TextMarkExt::fn get_name -->
Returns the mark name; returns NULL for anonymous marks.

# Returns

mark name
<!-- trait TextMarkExt::fn get_visible -->
Returns `true` if the mark is visible (i.e. a cursor is displayed
for it).

# Returns

`true` if visible
<!-- trait TextMarkExt::fn set_visible -->
Sets the visibility of `self`; the insertion point is normally
visible, i.e. you can see it as a vertical bar. Also, the text
widget uses a visible mark to indicate where a drop will occur when
dragging-and-dropping text. Most other marks are not visible.
Marks are not visible by default.
## `setting`
visibility of mark
<!-- trait TextMarkExt::fn get_property_left_gravity -->
Whether the mark has left gravity. When text is inserted at the mark’s
current location, if the mark has left gravity it will be moved
to the left of the newly-inserted text, otherwise to the right.
<!-- trait TextMarkExt::fn set_property_left_gravity -->
Whether the mark has left gravity. When text is inserted at the mark’s
current location, if the mark has left gravity it will be moved
to the left of the newly-inserted text, otherwise to the right.
<!-- trait TextMarkExt::fn get_property_name -->
The name of the mark or `None` if the mark is anonymous.
<!-- trait TextMarkExt::fn set_property_name -->
The name of the mark or `None` if the mark is anonymous.
<!-- struct TextSearchFlags -->
Flags affecting how a search is done.

If neither `TextSearchFlags::VisibleOnly` nor `TextSearchFlags::TextOnly` are
enabled, the match must be exact; the special 0xFFFC character will match
embedded pixbufs or child widgets.
<!-- struct TextSearchFlags::const VISIBLE_ONLY -->
Search only visible data. A search match may
have invisible text interspersed.
<!-- struct TextSearchFlags::const TEXT_ONLY -->
Search only text. A match may have pixbufs or
child widgets mixed inside the matched range.
<!-- struct TextSearchFlags::const CASE_INSENSITIVE -->
The text will be matched regardless of
what case it is in.
<!-- struct TextTag -->
You may wish to begin by reading the
[text widget conceptual overview][TextWidget]
which gives an overview of all the objects and
data types related to the text widget and how they work together.

Tags should be in the `TextTagTable` for a given `TextBuffer`
before using them with that buffer.

`TextBufferExt::create_tag` is the best way to create tags.
See “gtk3-demo” for numerous examples.

For each property of `TextTag`, there is a “set” property, e.g.
“font-set” corresponds to “font”. These “set” properties reflect
whether a property has been set or not.
They are maintained by GTK+ and you should not set them independently.

# Implements

[`TextTagExt`](trait.TextTagExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait TextTagExt -->
Trait containing all `TextTag` methods.

# Implementors

[`TextTag`](struct.TextTag.html)
<!-- impl TextTag::fn new -->
Creates a `TextTag`. Configure the tag using object arguments,
i.e. using `gobject::ObjectExt::set`.
## `name`
tag name, or `None`

# Returns

a new `TextTag`
<!-- trait TextTagExt::fn changed -->
Emits the `TextTagTable::tag-changed` signal on the `TextTagTable` where
the tag is included.

The signal is already emitted when setting a `TextTag` property. This
function is useful for a `TextTag` subclass.

Feature: `v3_20`

## `size_changed`
whether the change affects the `TextView` layout.
<!-- trait TextTagExt::fn event -->
Emits the “event” signal on the `TextTag`.
## `event_object`
object that received the event, such as a widget
## `event`
the event
## `iter`
location where the event was received

# Returns

result of signal emission (whether the event was handled)
<!-- trait TextTagExt::fn get_priority -->
Get the tag priority.

# Returns

The tag’s priority.
<!-- trait TextTagExt::fn set_priority -->
Sets the priority of a `TextTag`. Valid priorities
start at 0 and go to one less than `TextTagTableExt::get_size`.
Each tag in a table has a unique priority; setting the priority
of one tag shifts the priorities of all the other tags in the
table to maintain a unique priority for each tag. Higher priority
tags “win” if two tags both set the same text attribute. When adding
a tag to a tag table, it will be assigned the highest priority in
the table by default; so normally the precedence of a set of tags
is the order in which they were added to the table, or created with
`TextBufferExt::create_tag`, which adds the tag to the buffer’s table
automatically.
## `priority`
the new priority
<!-- trait TextTagExt::fn connect_event -->
The ::event signal is emitted when an event occurs on a region of the
buffer marked with this tag.
## `object`
the object the event was fired from (typically a `TextView`)
## `event`
the event which triggered the signal
## `iter`
a `TextIter` pointing at the location the event occurred

# Returns

`true` to stop other handlers from being invoked for the
event. `false` to propagate the event further.
<!-- trait TextTagExt::fn get_property_accumulative_margin -->
Whether the margins accumulate or override each other.

When set to `true` the margins of this tag are added to the margins
of any other non-accumulative margins present. When set to `false`
the margins override one another (the default).
<!-- trait TextTagExt::fn set_property_accumulative_margin -->
Whether the margins accumulate or override each other.

When set to `true` the margins of this tag are added to the margins
of any other non-accumulative margins present. When set to `false`
the margins override one another (the default).
<!-- trait TextTagExt::fn get_property_background_rgba -->
Background color as a `gdk::RGBA`.
<!-- trait TextTagExt::fn set_property_background_rgba -->
Background color as a `gdk::RGBA`.
<!-- trait TextTagExt::fn get_property_fallback -->
Whether font fallback is enabled.

When set to `true`, other fonts will be substituted
where the current font is missing glyphs.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_fallback -->
Whether font fallback is enabled.

When set to `true`, other fonts will be substituted
where the current font is missing glyphs.

Feature: `v3_16`

<!-- trait TextTagExt::fn get_property_font -->
Font description as string, e.g. \"Sans Italic 12\".

Note that the initial value of this property depends on
the internals of `pango::FontDescription`.
<!-- trait TextTagExt::fn set_property_font -->
Font description as string, e.g. \"Sans Italic 12\".

Note that the initial value of this property depends on
the internals of `pango::FontDescription`.
<!-- trait TextTagExt::fn get_property_font_features -->
OpenType font features, as a string.

Feature: `v3_18`

<!-- trait TextTagExt::fn set_property_font_features -->
OpenType font features, as a string.

Feature: `v3_18`

<!-- trait TextTagExt::fn get_property_foreground_rgba -->
Foreground color as a `gdk::RGBA`.
<!-- trait TextTagExt::fn set_property_foreground_rgba -->
Foreground color as a `gdk::RGBA`.
<!-- trait TextTagExt::fn get_property_invisible -->
Whether this text is hidden.

Note that there may still be problems with the support for invisible
text, in particular when navigating programmatically inside a buffer
containing invisible segments.
<!-- trait TextTagExt::fn set_property_invisible -->
Whether this text is hidden.

Note that there may still be problems with the support for invisible
text, in particular when navigating programmatically inside a buffer
containing invisible segments.
<!-- trait TextTagExt::fn get_property_language -->
The language this text is in, as an ISO code. Pango can use this as a
hint when rendering the text. If not set, an appropriate default will be
used.

Note that the initial value of this property depends on the current
locale, see also `gtk_get_default_language`.
<!-- trait TextTagExt::fn set_property_language -->
The language this text is in, as an ISO code. Pango can use this as a
hint when rendering the text. If not set, an appropriate default will be
used.

Note that the initial value of this property depends on the current
locale, see also `gtk_get_default_language`.
<!-- trait TextTagExt::fn get_property_letter_spacing -->
Extra spacing between graphemes, in Pango units.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_letter_spacing -->
Extra spacing between graphemes, in Pango units.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_paragraph_background -->
The paragraph background color as a string.
<!-- trait TextTagExt::fn get_property_paragraph_background_rgba -->
The paragraph background color as a `gdk::RGBA`.
<!-- trait TextTagExt::fn set_property_paragraph_background_rgba -->
The paragraph background color as a `gdk::RGBA`.
<!-- trait TextTagExt::fn get_property_strikethrough_rgba -->
This property modifies the color of strikeouts. If not set, strikeouts
will use the forground color.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_strikethrough_rgba -->
This property modifies the color of strikeouts. If not set, strikeouts
will use the forground color.

Feature: `v3_16`

<!-- trait TextTagExt::fn get_property_strikethrough_rgba_set -->
If the `TextTag:strikethrough-rgba` property has been set.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_strikethrough_rgba_set -->
If the `TextTag:strikethrough-rgba` property has been set.

Feature: `v3_16`

<!-- trait TextTagExt::fn get_property_underline_rgba -->
This property modifies the color of underlines. If not set, underlines
will use the forground color.

If `TextTag:underline` is set to `pango::Underline::Error`, an alternate
color may be applied instead of the foreground. Setting this property
will always override those defaults.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_underline_rgba -->
This property modifies the color of underlines. If not set, underlines
will use the forground color.

If `TextTag:underline` is set to `pango::Underline::Error`, an alternate
color may be applied instead of the foreground. Setting this property
will always override those defaults.

Feature: `v3_16`

<!-- trait TextTagExt::fn get_property_underline_rgba_set -->
If the `TextTag:underline-rgba` property has been set.

Feature: `v3_16`

<!-- trait TextTagExt::fn set_property_underline_rgba_set -->
If the `TextTag:underline-rgba` property has been set.

Feature: `v3_16`

<!-- struct TextTagTable -->
You may wish to begin by reading the
[text widget conceptual overview][TextWidget]
which gives an overview of all the objects and
data types related to the text widget and how they work together.

# `GtkTextTagTables` as `Buildable`

The `TextTagTable` implementation of the `Buildable` interface
supports adding tags by specifying “tag” as the “type” attribute
of a `<child>` element.

An example of a UI definition fragment specifying tags:

```text
<object class="GtkTextTagTable">
 <child type="tag">
   <object class="GtkTextTag"/>
 </child>
</object>
```

# Implements

[`TextTagTableExt`](trait.TextTagTableExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait TextTagTableExt -->
Trait containing all `TextTagTable` methods.

# Implementors

[`TextTagTable`](struct.TextTagTable.html)
<!-- impl TextTagTable::fn new -->
Creates a new `TextTagTable`. The table contains no tags by
default.

# Returns

a new `TextTagTable`
<!-- trait TextTagTableExt::fn add -->
Add a tag to the table. The tag is assigned the highest priority
in the table.

`tag` must not be in a tag table already, and may not have
the same name as an already-added tag.
## `tag`
a `TextTag`

# Returns

`true` on success.
<!-- trait TextTagTableExt::fn foreach -->
Calls `func` on each tag in `self`, with user data `data`.
Note that the table may not be modified while iterating
over it (you can’t add/remove tags).
## `func`
a function to call on each tag
## `data`
user data
<!-- trait TextTagTableExt::fn get_size -->
Returns the size of the table (number of tags)

# Returns

number of tags in `self`
<!-- trait TextTagTableExt::fn lookup -->
Look up a named tag.
## `name`
name of a tag

# Returns

The tag, or `None` if none by that
name is in the table.
<!-- trait TextTagTableExt::fn remove -->
Remove a tag from the table. If a `TextBuffer` has `self` as its tag table,
the tag is removed from the buffer. The table’s reference to the tag is
removed, so the tag will end up destroyed if you don’t have a reference to
it.
## `tag`
a `TextTag`
<!-- trait TextTagTableExt::fn connect_tag_added -->
## `tag`
the added tag.
<!-- trait TextTagTableExt::fn connect_tag_changed -->
## `tag`
the changed tag.
## `size_changed`
whether the change affects the `TextView` layout.
<!-- trait TextTagTableExt::fn connect_tag_removed -->
## `tag`
the removed tag.
<!-- struct TextView -->
You may wish to begin by reading the
[text widget conceptual overview][TextWidget]
which gives an overview of all the objects and data
types related to the text widget and how they work together.

# CSS nodes


```plain
textview.view
├── border.top
├── border.left
├── text
│   ╰── [selection]
├── border.right
├── border.bottom
╰── [window.popup]
```

`TextView` has a main css node with name textview and style class .view,
and subnodes for each of the border windows, and the main text area,
with names border and text, respectively. The border nodes each get
one of the style classes .left, .right, .top or .bottom.

A node representing the selection will appear below the text node.

If a context menu is opened, the window node will appear as a subnode
of the main node.

# Implements

[`TextViewExt`](trait.TextViewExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ScrollableExt`](trait.ScrollableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait TextViewExt -->
Trait containing all `TextView` methods.

# Implementors

[`TextView`](struct.TextView.html)
<!-- impl TextView::fn new -->
Creates a new `TextView`. If you don’t call `TextViewExt::set_buffer`
before using the text view, an empty default buffer will be created
for you. Get the buffer with `TextViewExt::get_buffer`. If you want
to specify your own buffer, consider `TextView::new_with_buffer`.

# Returns

a new `TextView`
<!-- impl TextView::fn new_with_buffer -->
Creates a new `TextView` widget displaying the buffer
`buffer`. One buffer can be shared among many widgets.
`buffer` may be `None` to create a default buffer, in which case
this function is equivalent to `TextView::new`. The
text view adds its own reference count to the buffer; it does not
take over an existing reference.
## `buffer`
a `TextBuffer`

# Returns

a new `TextView`.
<!-- trait TextViewExt::fn add_child_at_anchor -->
Adds a child widget in the text buffer, at the given `anchor`.
## `child`
a `Widget`
## `anchor`
a `TextChildAnchor` in the `TextBuffer` for `self`
<!-- trait TextViewExt::fn add_child_in_window -->
Adds a child at fixed coordinates in one of the text widget's
windows.

The window must have nonzero size (see
`TextViewExt::set_border_window_size`). Note that the child
coordinates are given relative to scrolling. When
placing a child in `TextWindowType::Widget`, scrolling is
irrelevant, the child floats above all scrollable areas. But when
placing a child in one of the scrollable windows (border windows or
text window) it will move with the scrolling as needed.
## `child`
a `Widget`
## `which_window`
which window the child should appear in
## `xpos`
X position of child in window coordinates
## `ypos`
Y position of child in window coordinates
<!-- trait TextViewExt::fn backward_display_line -->
Moves the given `iter` backward by one display (wrapped) line.
A display line is different from a paragraph. Paragraphs are
separated by newlines or other paragraph separator characters.
Display lines are created by line-wrapping a paragraph. If
wrapping is turned off, display lines and paragraphs will be the
same. Display lines are divided differently for each view, since
they depend on the view’s width; paragraphs are the same in all
views, since they depend on the contents of the `TextBuffer`.
## `iter`
a `TextIter`

# Returns

`true` if `iter` was moved and is not on the end iterator
<!-- trait TextViewExt::fn backward_display_line_start -->
Moves the given `iter` backward to the next display line start.
A display line is different from a paragraph. Paragraphs are
separated by newlines or other paragraph separator characters.
Display lines are created by line-wrapping a paragraph. If
wrapping is turned off, display lines and paragraphs will be the
same. Display lines are divided differently for each view, since
they depend on the view’s width; paragraphs are the same in all
views, since they depend on the contents of the `TextBuffer`.
## `iter`
a `TextIter`

# Returns

`true` if `iter` was moved and is not on the end iterator
<!-- trait TextViewExt::fn buffer_to_window_coords -->
Converts coordinate (`buffer_x`, `buffer_y`) to coordinates for the window
`win`, and stores the result in (`window_x`, `window_y`).

Note that you can’t convert coordinates for a nonexisting window (see
`TextViewExt::set_border_window_size`).
## `win`
a `TextWindowType`, except `TextWindowType::Private`
## `buffer_x`
buffer x coordinate
## `buffer_y`
buffer y coordinate
## `window_x`
window x coordinate return location or `None`
## `window_y`
window y coordinate return location or `None`
<!-- trait TextViewExt::fn forward_display_line -->
Moves the given `iter` forward by one display (wrapped) line.
A display line is different from a paragraph. Paragraphs are
separated by newlines or other paragraph separator characters.
Display lines are created by line-wrapping a paragraph. If
wrapping is turned off, display lines and paragraphs will be the
same. Display lines are divided differently for each view, since
they depend on the view’s width; paragraphs are the same in all
views, since they depend on the contents of the `TextBuffer`.
## `iter`
a `TextIter`

# Returns

`true` if `iter` was moved and is not on the end iterator
<!-- trait TextViewExt::fn forward_display_line_end -->
Moves the given `iter` forward to the next display line end.
A display line is different from a paragraph. Paragraphs are
separated by newlines or other paragraph separator characters.
Display lines are created by line-wrapping a paragraph. If
wrapping is turned off, display lines and paragraphs will be the
same. Display lines are divided differently for each view, since
they depend on the view’s width; paragraphs are the same in all
views, since they depend on the contents of the `TextBuffer`.
## `iter`
a `TextIter`

# Returns

`true` if `iter` was moved and is not on the end iterator
<!-- trait TextViewExt::fn get_accepts_tab -->
Returns whether pressing the Tab key inserts a tab characters.
`TextViewExt::set_accepts_tab`.

# Returns

`true` if pressing the Tab key inserts a tab character,
 `false` if pressing the Tab key moves the keyboard focus.
<!-- trait TextViewExt::fn get_border_window_size -->
Gets the width of the specified border window. See
`TextViewExt::set_border_window_size`.
## `type_`
window to return size from

# Returns

width of window
<!-- trait TextViewExt::fn get_bottom_margin -->
Gets the bottom margin for text in the `self`.

Feature: `v3_18`


# Returns

bottom margin in pixels
<!-- trait TextViewExt::fn get_buffer -->
Returns the `TextBuffer` being displayed by this text view.
The reference count on the buffer is not incremented; the caller
of this function won’t own a new reference.

# Returns

a `TextBuffer`
<!-- trait TextViewExt::fn get_cursor_locations -->
Given an `iter` within a text layout, determine the positions of the
strong and weak cursors if the insertion point is at that
iterator. The position of each cursor is stored as a zero-width
rectangle. The strong cursor location is the location where
characters of the directionality equal to the base direction of the
paragraph are inserted. The weak cursor location is the location
where characters of the directionality opposite to the base
direction of the paragraph are inserted.

If `iter` is `None`, the actual cursor position is used.

Note that if `iter` happens to be the actual cursor position, and
there is currently an IM preedit sequence being entered, the
returned locations will be adjusted to account for the preedit
cursor’s offset within the preedit sequence.

The rectangle position is in buffer coordinates; use
`TextViewExt::buffer_to_window_coords` to convert these
coordinates to coordinates for one of the windows in the text view.
## `iter`
a `TextIter`
## `strong`
location to store the strong
 cursor position (may be `None`)
## `weak`
location to store the weak
 cursor position (may be `None`)
<!-- trait TextViewExt::fn get_cursor_visible -->
Find out whether the cursor should be displayed.

# Returns

whether the insertion mark is visible
<!-- trait TextViewExt::fn get_default_attributes -->
Obtains a copy of the default text attributes. These are the
attributes used for text unless a tag overrides them.
You’d typically pass the default attributes in to
`TextIter::get_attributes` in order to get the
attributes in effect at a given text position.

The return value is a copy owned by the caller of this function,
and should be freed with `TextAttributes::unref`.

# Returns

a new `TextAttributes`
<!-- trait TextViewExt::fn get_editable -->
Returns the default editability of the `TextView`. Tags in the
buffer may override this setting for some ranges of text.

# Returns

whether text is editable by default
<!-- trait TextViewExt::fn get_indent -->
Gets the default indentation of paragraphs in `self`.
Tags in the view’s buffer may override the default.
The indentation may be negative.

# Returns

number of pixels of indentation
<!-- trait TextViewExt::fn get_input_hints -->
Gets the value of the `TextView:input-hints` property.
<!-- trait TextViewExt::fn get_input_purpose -->
Gets the value of the `TextView:input-purpose` property.
<!-- trait TextViewExt::fn get_iter_at_location -->
Retrieves the iterator at buffer coordinates `x` and `y`. Buffer
coordinates are coordinates for the entire buffer, not just the
currently-displayed portion. If you have coordinates from an
event, you have to convert those to buffer coordinates with
`TextViewExt::window_to_buffer_coords`.
## `iter`
a `TextIter`
## `x`
x position, in buffer coordinates
## `y`
y position, in buffer coordinates

# Returns

`true` if the position is over text
<!-- trait TextViewExt::fn get_iter_at_position -->
Retrieves the iterator pointing to the character at buffer
coordinates `x` and `y`. Buffer coordinates are coordinates for
the entire buffer, not just the currently-displayed portion.
If you have coordinates from an event, you have to convert
those to buffer coordinates with
`TextViewExt::window_to_buffer_coords`.

Note that this is different from `TextViewExt::get_iter_at_location`,
which returns cursor locations, i.e. positions between
characters.
## `iter`
a `TextIter`
## `trailing`
if non-`None`, location to store an integer indicating where
 in the grapheme the user clicked. It will either be
 zero, or the number of characters in the grapheme.
 0 represents the trailing edge of the grapheme.
## `x`
x position, in buffer coordinates
## `y`
y position, in buffer coordinates

# Returns

`true` if the position is over text
<!-- trait TextViewExt::fn get_iter_location -->
Gets a rectangle which roughly contains the character at `iter`.
The rectangle position is in buffer coordinates; use
`TextViewExt::buffer_to_window_coords` to convert these
coordinates to coordinates for one of the windows in the text view.
## `iter`
a `TextIter`
## `location`
bounds of the character at `iter`
<!-- trait TextViewExt::fn get_justification -->
Gets the default justification of paragraphs in `self`.
Tags in the buffer may override the default.

# Returns

default justification
<!-- trait TextViewExt::fn get_left_margin -->
Gets the default left margin size of paragraphs in the `self`.
Tags in the buffer may override the default.

# Returns

left margin in pixels
<!-- trait TextViewExt::fn get_line_at_y -->
Gets the `TextIter` at the start of the line containing
the coordinate `y`. `y` is in buffer coordinates, convert from
window coordinates with `TextViewExt::window_to_buffer_coords`.
If non-`None`, `line_top` will be filled with the coordinate of the top
edge of the line.
## `target_iter`
a `TextIter`
## `y`
a y coordinate
## `line_top`
return location for top coordinate of the line
<!-- trait TextViewExt::fn get_line_yrange -->
Gets the y coordinate of the top of the line containing `iter`,
and the height of the line. The coordinate is a buffer coordinate;
convert to window coordinates with `TextViewExt::buffer_to_window_coords`.
## `iter`
a `TextIter`
## `y`
return location for a y coordinate
## `height`
return location for a height
<!-- trait TextViewExt::fn get_monospace -->
Gets the value of the `TextView:monospace` property.

Feature: `v3_16`


# Returns

`true` if monospace fonts are desired
<!-- trait TextViewExt::fn get_overwrite -->
Returns whether the `TextView` is in overwrite mode or not.

# Returns

whether `self` is in overwrite mode or not.
<!-- trait TextViewExt::fn get_pixels_above_lines -->
Gets the default number of pixels to put above paragraphs.
Adding this function with `TextViewExt::get_pixels_below_lines`
is equal to the line space between each paragraph.

# Returns

default number of pixels above paragraphs
<!-- trait TextViewExt::fn get_pixels_below_lines -->
Gets the value set by `TextViewExt::set_pixels_below_lines`.

The line space is the sum of the value returned by this function and the
value returned by `TextViewExt::get_pixels_above_lines`.

# Returns

default number of blank pixels below paragraphs
<!-- trait TextViewExt::fn get_pixels_inside_wrap -->
Gets the value set by `TextViewExt::set_pixels_inside_wrap`.

# Returns

default number of pixels of blank space between wrapped lines
<!-- trait TextViewExt::fn get_right_margin -->
Gets the default right margin for text in `self`. Tags
in the buffer may override the default.

# Returns

right margin in pixels
<!-- trait TextViewExt::fn get_tabs -->
Gets the default tabs for `self`. Tags in the buffer may
override the defaults. The returned array will be `None` if
“standard” (8-space) tabs are used. Free the return value
with `pango::TabArray::free`.

# Returns

copy of default tab array, or `None` if
 “standard" tabs are used; must be freed with `pango::TabArray::free`.
<!-- trait TextViewExt::fn get_top_margin -->
Gets the top margin for text in the `self`.

Feature: `v3_18`


# Returns

top margin in pixels
<!-- trait TextViewExt::fn get_visible_rect -->
Fills `visible_rect` with the currently-visible
region of the buffer, in buffer coordinates. Convert to window coordinates
with `TextViewExt::buffer_to_window_coords`.
## `visible_rect`
rectangle to fill
<!-- trait TextViewExt::fn get_window -->
Retrieves the `gdk::Window` corresponding to an area of the text view;
possible windows include the overall widget window, child windows
on the left, right, top, bottom, and the window that displays the
text buffer. Windows are `None` and nonexistent if their width or
height is 0, and are nonexistent before the widget has been
realized.
## `win`
window to get

# Returns

a `gdk::Window`, or `None`
<!-- trait TextViewExt::fn get_window_type -->
Usually used to find out which window an event corresponds to.

If you connect to an event signal on `self`, this function
should be called on `event->window` to see which window it was.
## `window`
a window type

# Returns

the window type.
<!-- trait TextViewExt::fn get_wrap_mode -->
Gets the line wrapping for the view.

# Returns

the line wrap setting
<!-- trait TextViewExt::fn im_context_filter_keypress -->
Allow the `TextView` input method to internally handle key press
and release events. If this function returns `true`, then no further
processing should be done for this key event. See
`IMContextExt::filter_keypress`.

Note that you are expected to call this function from your handler
when overriding key event handling. This is needed in the case when
you need to insert your own key handling between the input method
and the default key event handling of the `TextView`.


```C
static gboolean
gtk_foo_bar_key_press_event (GtkWidget   *widget,
                             GdkEventKey *event)
{
  guint keyval;

  gdk_event_get_keyval ((GdkEvent*)event, &keyval);

  if (keyval == GDK_KEY_Return || keyval == GDK_KEY_KP_Enter)
    {
      if (gtk_text_view_im_context_filter_keypress (GTK_TEXT_VIEW (widget), event))
        return TRUE;
    }

  // Do some stuff

  return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class)->key_press_event (widget, event);
}
```
## `event`
the key event

# Returns

`true` if the input method handled the key event.
<!-- trait TextViewExt::fn move_child -->
Updates the position of a child, as for `TextViewExt::add_child_in_window`.
## `child`
child widget already added to the text view
## `xpos`
new X position in window coordinates
## `ypos`
new Y position in window coordinates
<!-- trait TextViewExt::fn move_mark_onscreen -->
Moves a mark within the buffer so that it's
located within the currently-visible text area.
## `mark`
a `TextMark`

# Returns

`true` if the mark moved (wasn’t already onscreen)
<!-- trait TextViewExt::fn move_visually -->
Move the iterator a given number of characters visually, treating
it as the strong cursor position. If `count` is positive, then the
new strong cursor position will be `count` positions to the right of
the old cursor position. If `count` is negative then the new strong
cursor position will be `count` positions to the left of the old
cursor position.

In the presence of bi-directional text, the correspondence
between logical and visual order will depend on the direction
of the current run, and there may be jumps when the cursor
is moved off of the end of a run.
## `iter`
a `TextIter`
## `count`
number of characters to move (negative moves left,
 positive moves right)

# Returns

`true` if `iter` moved and is not on the end iterator
<!-- trait TextViewExt::fn place_cursor_onscreen -->
Moves the cursor to the currently visible region of the
buffer, it it isn’t there already.

# Returns

`true` if the cursor had to be moved.
<!-- trait TextViewExt::fn reset_cursor_blink -->
Ensures that the cursor is shown (i.e. not in an 'off' blink
interval) and resets the time that it will stay blinking (or
visible, in case blinking is disabled).

This function should be called in response to user input
(e.g. from derived classes that override the textview's
`Widget::key-press-event` handler).

Feature: `v3_20`

<!-- trait TextViewExt::fn reset_im_context -->
Reset the input method context of the text view if needed.

This can be necessary in the case where modifying the buffer
would confuse on-going input method behavior.
<!-- trait TextViewExt::fn scroll_mark_onscreen -->
Scrolls `self` the minimum distance such that `mark` is contained
within the visible area of the widget.
## `mark`
a mark in the buffer for `self`
<!-- trait TextViewExt::fn scroll_to_iter -->
Scrolls `self` so that `iter` is on the screen in the position
indicated by `xalign` and `yalign`. An alignment of 0.0 indicates
left or top, 1.0 indicates right or bottom, 0.5 means center.
If `use_align` is `false`, the text scrolls the minimal distance to
get the mark onscreen, possibly not scrolling at all. The effective
screen for purposes of this function is reduced by a margin of size
`within_margin`.

Note that this function uses the currently-computed height of the
lines in the text buffer. Line heights are computed in an idle
handler; so this function may not have the desired effect if it’s
called before the height computations. To avoid oddness, consider
using `TextViewExt::scroll_to_mark` which saves a point to be
scrolled to after line validation.
## `iter`
a `TextIter`
## `within_margin`
margin as a [0.0,0.5) fraction of screen size
## `use_align`
whether to use alignment arguments (if `false`,
 just get the mark onscreen)
## `xalign`
horizontal alignment of mark within visible area
## `yalign`
vertical alignment of mark within visible area

# Returns

`true` if scrolling occurred
<!-- trait TextViewExt::fn scroll_to_mark -->
Scrolls `self` so that `mark` is on the screen in the position
indicated by `xalign` and `yalign`. An alignment of 0.0 indicates
left or top, 1.0 indicates right or bottom, 0.5 means center.
If `use_align` is `false`, the text scrolls the minimal distance to
get the mark onscreen, possibly not scrolling at all. The effective
screen for purposes of this function is reduced by a margin of size
`within_margin`.
## `mark`
a `TextMark`
## `within_margin`
margin as a [0.0,0.5) fraction of screen size
## `use_align`
whether to use alignment arguments (if `false`, just
 get the mark onscreen)
## `xalign`
horizontal alignment of mark within visible area
## `yalign`
vertical alignment of mark within visible area
<!-- trait TextViewExt::fn set_accepts_tab -->
Sets the behavior of the text widget when the Tab key is pressed.
If `accepts_tab` is `true`, a tab character is inserted. If `accepts_tab`
is `false` the keyboard focus is moved to the next widget in the focus
chain.
## `accepts_tab`
`true` if pressing the Tab key should insert a tab
 character, `false`, if pressing the Tab key should move the
 keyboard focus.
<!-- trait TextViewExt::fn set_border_window_size -->
Sets the width of `TextWindowType::Left` or `TextWindowType::Right`,
or the height of `TextWindowType::Top` or `TextWindowType::Bottom`.
Automatically destroys the corresponding window if the size is set
to 0, and creates the window if the size is set to non-zero. This
function can only be used for the “border windows”, and it won’t
work with `TextWindowType::Widget`, `TextWindowType::Text`, or
`TextWindowType::Private`.
## `type_`
window to affect
## `size`
width or height of the window
<!-- trait TextViewExt::fn set_bottom_margin -->
Sets the bottom margin for text in `self`.

Note that this function is confusingly named.
In CSS terms, the value set here is padding.

Feature: `v3_18`

## `bottom_margin`
bottom margin in pixels
<!-- trait TextViewExt::fn set_buffer -->
Sets `buffer` as the buffer being displayed by `self`. The previous
buffer displayed by the text view is unreferenced, and a reference is
added to `buffer`. If you owned a reference to `buffer` before passing it
to this function, you must remove that reference yourself; `TextView`
will not “adopt” it.
## `buffer`
a `TextBuffer`
<!-- trait TextViewExt::fn set_cursor_visible -->
Toggles whether the insertion point should be displayed. A buffer with
no editable text probably shouldn’t have a visible cursor, so you may
want to turn the cursor off.

Note that this property may be overridden by the
`Settings:gtk-keynave-use-caret` settings.
## `setting`
whether to show the insertion cursor
<!-- trait TextViewExt::fn set_editable -->
Sets the default editability of the `TextView`. You can override
this default setting with tags in the buffer, using the “editable”
attribute of tags.
## `setting`
whether it’s editable
<!-- trait TextViewExt::fn set_indent -->
Sets the default indentation for paragraphs in `self`.
Tags in the buffer may override the default.
## `indent`
indentation in pixels
<!-- trait TextViewExt::fn set_input_hints -->
Sets the `TextView:input-hints` property, which
allows input methods to fine-tune their behaviour.
## `hints`
the hints
<!-- trait TextViewExt::fn set_input_purpose -->
Sets the `TextView:input-purpose` property which
can be used by on-screen keyboards and other input
methods to adjust their behaviour.
## `purpose`
the purpose
<!-- trait TextViewExt::fn set_justification -->
Sets the default justification of text in `self`.
Tags in the view’s buffer may override the default.
## `justification`
justification
<!-- trait TextViewExt::fn set_left_margin -->
Sets the default left margin for text in `self`.
Tags in the buffer may override the default.

Note that this function is confusingly named.
In CSS terms, the value set here is padding.
## `left_margin`
left margin in pixels
<!-- trait TextViewExt::fn set_monospace -->
Sets the `TextView:monospace` property, which
indicates that the text view should use monospace
fonts.

Feature: `v3_16`

## `monospace`
`true` to request monospace styling
<!-- trait TextViewExt::fn set_overwrite -->
Changes the `TextView` overwrite mode.
## `overwrite`
`true` to turn on overwrite mode, `false` to turn it off
<!-- trait TextViewExt::fn set_pixels_above_lines -->
Sets the default number of blank pixels above paragraphs in `self`.
Tags in the buffer for `self` may override the defaults.
## `pixels_above_lines`
pixels above paragraphs
<!-- trait TextViewExt::fn set_pixels_below_lines -->
Sets the default number of pixels of blank space
to put below paragraphs in `self`. May be overridden
by tags applied to `self`’s buffer.
## `pixels_below_lines`
pixels below paragraphs
<!-- trait TextViewExt::fn set_pixels_inside_wrap -->
Sets the default number of pixels of blank space to leave between
display/wrapped lines within a paragraph. May be overridden by
tags in `self`’s buffer.
## `pixels_inside_wrap`
default number of pixels between wrapped lines
<!-- trait TextViewExt::fn set_right_margin -->
Sets the default right margin for text in the text view.
Tags in the buffer may override the default.

Note that this function is confusingly named.
In CSS terms, the value set here is padding.
## `right_margin`
right margin in pixels
<!-- trait TextViewExt::fn set_tabs -->
Sets the default tab stops for paragraphs in `self`.
Tags in the buffer may override the default.
## `tabs`
tabs as a `pango::TabArray`
<!-- trait TextViewExt::fn set_top_margin -->
Sets the top margin for text in `self`.

Note that this function is confusingly named.
In CSS terms, the value set here is padding.

Feature: `v3_18`

## `top_margin`
top margin in pixels
<!-- trait TextViewExt::fn set_wrap_mode -->
Sets the line wrapping for the view.
## `wrap_mode`
a `WrapMode`
<!-- trait TextViewExt::fn starts_display_line -->
Determines whether `iter` is at the start of a display line.
See `TextViewExt::forward_display_line` for an explanation of
display lines vs. paragraphs.
## `iter`
a `TextIter`

# Returns

`true` if `iter` begins a wrapped line
<!-- trait TextViewExt::fn window_to_buffer_coords -->
Converts coordinates on the window identified by `win` to buffer
coordinates, storing the result in (`buffer_x`,`buffer_y`).

Note that you can’t convert coordinates for a nonexisting window (see
`TextViewExt::set_border_window_size`).
## `win`
a `TextWindowType` except `TextWindowType::Private`
## `window_x`
window x coordinate
## `window_y`
window y coordinate
## `buffer_x`
buffer x coordinate return location or `None`
## `buffer_y`
buffer y coordinate return location or `None`
<!-- trait TextViewExt::fn connect_backspace -->
The ::backspace signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user asks for it.

The default bindings for this signal are
Backspace and Shift-Backspace.
<!-- trait TextViewExt::fn connect_copy_clipboard -->
The ::copy-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to copy the selection to the clipboard.

The default bindings for this signal are
Ctrl-c and Ctrl-Insert.
<!-- trait TextViewExt::fn connect_cut_clipboard -->
The ::cut-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to cut the selection to the clipboard.

The default bindings for this signal are
Ctrl-x and Shift-Delete.
<!-- trait TextViewExt::fn connect_delete_from_cursor -->
The ::delete-from-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a text deletion.

If the `type_` is `DeleteType::Chars`, GTK+ deletes the selection
if there is one, otherwise it deletes the requested number
of characters.

The default bindings for this signal are
Delete for deleting a character, Ctrl-Delete for
deleting a word and Ctrl-Backspace for deleting a word
backwords.
## `type_`
the granularity of the deletion, as a `DeleteType`
## `count`
the number of `type_` units to delete
<!-- trait TextViewExt::fn connect_extend_selection -->
The ::extend-selection signal is emitted when the selection needs to be
extended at `location`.

Feature: `v3_16`

## `granularity`
the granularity type
## `location`
the location where to extend the selection
## `start`
where the selection should start
## `end`
where the selection should end

# Returns

`GDK_EVENT_STOP` to stop other handlers from being invoked for the
 event. `GDK_EVENT_PROPAGATE` to propagate the event further.
<!-- trait TextViewExt::fn connect_insert_at_cursor -->
The ::insert-at-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates the insertion of a
fixed string at the cursor.

This signal has no default bindings.
## `string`
the string to insert
<!-- trait TextViewExt::fn connect_insert_emoji -->
The ::insert-emoji signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to present the Emoji chooser for the `text_view`.

The default bindings for this signal are Ctrl-. and Ctrl-;

Feature: `v3_22_27`

<!-- trait TextViewExt::fn connect_move_cursor -->
The ::move-cursor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates a cursor movement.
If the cursor is not visible in `text_view`, this signal causes
the viewport to be moved instead.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically.

The default bindings for this signal come in two variants,
the variant with the Shift modifier extends the selection,
the variant without the Shift modifer does not.
There are too many key combinations to list them all here.
- Arrow keys move by individual characters/lines
- Ctrl-arrow key combinations move by words/paragraphs
- Home/End keys move to the ends of the buffer
- PageUp/PageDown keys move vertically by pages
- Ctrl-PageUp/PageDown keys move horizontally by pages
## `step`
the granularity of the move, as a `MovementStep`
## `count`
the number of `step` units to move
## `extend_selection`
`true` if the move should extend the selection
<!-- trait TextViewExt::fn connect_move_viewport -->
The ::move-viewport signal is a
[keybinding signal][`BindingSignal`]
which can be bound to key combinations to allow the user
to move the viewport, i.e. change what part of the text view
is visible in a containing scrolled window.

There are no default bindings for this signal.
## `step`
the granularity of the movement, as a `ScrollStep`
## `count`
the number of `step` units to move
<!-- trait TextViewExt::fn connect_paste_clipboard -->
The ::paste-clipboard signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to paste the contents of the clipboard
into the text view.

The default bindings for this signal are
Ctrl-v and Shift-Insert.
<!-- trait TextViewExt::fn connect_populate_popup -->
The ::populate-popup signal gets emitted before showing the
context menu of the text view.

If you need to add items to the context menu, connect
to this signal and append your items to the `popup`, which
will be a `Menu` in this case.

If `TextView:populate-all` is `true`, this signal will
also be emitted to populate touch popups. In this case,
`popup` will be a different container, e.g. a `Toolbar`.

The signal handler should not make assumptions about the
type of `widget`, but check whether `popup` is a `Menu`
or `Toolbar` or another kind of container.
## `popup`
the container that is being populated
<!-- trait TextViewExt::fn connect_preedit_changed -->
If an input method is used, the typed text will not immediately
be committed to the buffer. So if you are interested in the text,
connect to this signal.

This signal is only emitted if the text at the given position
is actually editable.
## `preedit`
the current preedit string
<!-- trait TextViewExt::fn connect_select_all -->
The ::select-all signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to select or unselect the complete
contents of the text view.

The default bindings for this signal are Ctrl-a and Ctrl-/
for selecting and Shift-Ctrl-a and Ctrl-\ for unselecting.
## `select`
`true` to select, `false` to unselect
<!-- trait TextViewExt::fn connect_set_anchor -->
The ::set-anchor signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user initiates setting the "anchor"
mark. The "anchor" mark gets placed at the same position as the
"insert" mark.

This signal has no default bindings.
<!-- trait TextViewExt::fn connect_toggle_cursor_visible -->
The ::toggle-cursor-visible signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to toggle the `TextView:cursor-visible`
property.

The default binding for this signal is F7.
<!-- trait TextViewExt::fn connect_toggle_overwrite -->
The ::toggle-overwrite signal is a
[keybinding signal][`BindingSignal`]
which gets emitted to toggle the overwrite mode of the text view.

The default bindings for this signal is Insert.
<!-- trait TextViewExt::fn get_property_bottom_margin -->
The bottom margin for text in the text view.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-bottom`.

Feature: `v3_18`

<!-- trait TextViewExt::fn set_property_bottom_margin -->
The bottom margin for text in the text view.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-bottom`.

Feature: `v3_18`

<!-- trait TextViewExt::fn get_property_im_module -->
Which IM (input method) module should be used for this text_view.
See `IMContext`.

Setting this to a non-`None` value overrides the
system-wide IM module setting. See the `Settings`
`Settings:gtk-im-module` property.
<!-- trait TextViewExt::fn set_property_im_module -->
Which IM (input method) module should be used for this text_view.
See `IMContext`.

Setting this to a non-`None` value overrides the
system-wide IM module setting. See the `Settings`
`Settings:gtk-im-module` property.
<!-- trait TextViewExt::fn get_property_input_hints -->
Additional hints (beyond `TextView:input-purpose`) that
allow input methods to fine-tune their behaviour.
<!-- trait TextViewExt::fn set_property_input_hints -->
Additional hints (beyond `TextView:input-purpose`) that
allow input methods to fine-tune their behaviour.
<!-- trait TextViewExt::fn get_property_input_purpose -->
The purpose of this text field.

This property can be used by on-screen keyboards and other input
methods to adjust their behaviour.
<!-- trait TextViewExt::fn set_property_input_purpose -->
The purpose of this text field.

This property can be used by on-screen keyboards and other input
methods to adjust their behaviour.
<!-- trait TextViewExt::fn get_property_left_margin -->
The default left margin for text in the text view.
Tags in the buffer may override the default.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-left`.
<!-- trait TextViewExt::fn set_property_left_margin -->
The default left margin for text in the text view.
Tags in the buffer may override the default.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-left`.
<!-- trait TextViewExt::fn get_property_populate_all -->
If :populate-all is `true`, the `TextView::populate-popup`
signal is also emitted for touch popups.
<!-- trait TextViewExt::fn set_property_populate_all -->
If :populate-all is `true`, the `TextView::populate-popup`
signal is also emitted for touch popups.
<!-- trait TextViewExt::fn get_property_right_margin -->
The default right margin for text in the text view.
Tags in the buffer may override the default.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-right`.
<!-- trait TextViewExt::fn set_property_right_margin -->
The default right margin for text in the text view.
Tags in the buffer may override the default.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-right`.
<!-- trait TextViewExt::fn get_property_top_margin -->
The top margin for text in the text view.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-top`.

Feature: `v3_18`

<!-- trait TextViewExt::fn set_property_top_margin -->
The top margin for text in the text view.

Note that this property is confusingly named. In CSS terms,
the value set here is padding, and it is applied in addition
to the padding from the theme.

Don't confuse this property with `Widget:margin-top`.

Feature: `v3_18`

<!-- enum TextViewLayer -->
Used to reference the layers of `TextView` for the purpose of customized
drawing with the ::draw_layer vfunc.
<!-- enum TextViewLayer::variant Below -->
Old deprecated layer, use `TextViewLayer::BelowText` instead
<!-- enum TextViewLayer::variant Above -->
Old deprecated layer, use `TextViewLayer::AboveText` instead
<!-- enum TextViewLayer::variant BelowText -->
The layer rendered below the text (but above the background). Since: 3.20
<!-- enum TextViewLayer::variant AboveText -->
The layer rendered above the text. Since: 3.20
<!-- enum TextWindowType -->
Used to reference the parts of `TextView`.
<!-- enum TextWindowType::variant Private -->
Invalid value, used as a marker
<!-- enum TextWindowType::variant Widget -->
Window that floats over scrolling areas.
<!-- enum TextWindowType::variant Text -->
Scrollable text window.
<!-- enum TextWindowType::variant Left -->
Left side border window.
<!-- enum TextWindowType::variant Right -->
Right side border window.
<!-- enum TextWindowType::variant Top -->
Top border window.
<!-- enum TextWindowType::variant Bottom -->
Bottom border window.
<!-- struct ToggleButton -->
A `ToggleButton` is a `Button` which will remain “pressed-in” when
clicked. Clicking again will cause the toggle button to return to its
normal state.

A toggle button is created by calling either `ToggleButton::new` or
`ToggleButton::new_with_label`. If using the former, it is advisable to
pack a widget, (such as a `Label` and/or a `Image`), into the toggle
button’s container. (See `Button` for more information).

The state of a `ToggleButton` can be set specifically using
`ToggleButtonExt::set_active`, and retrieved using
`ToggleButtonExt::get_active`.

To simply switch the state of a toggle button, use `ToggleButtonExt::toggled`.

# CSS nodes

`ToggleButton` has a single CSS node with name button. To differentiate
it from a plain `Button`, it gets the .toggle style class.

## Creating two `ToggleButton` widgets.


```C
static void output_state (GtkToggleButton *source, gpointer user_data) {
  printf ("Active: %d\n", gtk_toggle_button_get_active (source));
}

void make_toggles (void) {
  GtkWidget *window, *toggle1, *toggle2;
  GtkWidget *box;
  const char *text;

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12);

  text = "Hi, I’m a toggle button.";
  toggle1 = gtk_toggle_button_new_with_label (text);

  // Makes this toggle button invisible
  gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1),
                              TRUE);

  g_signal_connect (toggle1, "toggled",
                    G_CALLBACK (output_state),
                    NULL);
  gtk_container_add (GTK_CONTAINER (box), toggle1);

  text = "Hi, I’m a toggle button.";
  toggle2 = gtk_toggle_button_new_with_label (text);
  gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2),
                              FALSE);
  g_signal_connect (toggle2, "toggled",
                    G_CALLBACK (output_state),
                    NULL);
  gtk_container_add (GTK_CONTAINER (box), toggle2);

  gtk_container_add (GTK_CONTAINER (window), box);
  gtk_widget_show_all (window);
}
```

# Implements

[`ToggleButtonExt`](trait.ToggleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToggleButtonExt -->
Trait containing all `ToggleButton` methods.

# Implementors

[`CheckButton`](struct.CheckButton.html), [`MenuButton`](struct.MenuButton.html), [`ToggleButton`](struct.ToggleButton.html)
<!-- impl ToggleButton::fn new -->
Creates a new toggle button. A widget should be packed into the button, as in `Button::new`.

# Returns

a new toggle button.
<!-- impl ToggleButton::fn new_with_label -->
Creates a new toggle button with a text label.
## `label`
a string containing the message to be placed in the toggle button.

# Returns

a new toggle button.
<!-- impl ToggleButton::fn new_with_mnemonic -->
Creates a new `ToggleButton` containing a label. The label
will be created using `Label::new_with_mnemonic`, so underscores
in `label` indicate the mnemonic for the button.
## `label`
the text of the button, with an underscore in front of the
 mnemonic character

# Returns

a new `ToggleButton`
<!-- trait ToggleButtonExt::fn get_active -->
Queries a `ToggleButton` and returns its current state. Returns `true` if
the toggle button is pressed in and `false` if it is raised.

# Returns

a `gboolean` value.
<!-- trait ToggleButtonExt::fn get_inconsistent -->
Gets the value set by `ToggleButtonExt::set_inconsistent`.

# Returns

`true` if the button is displayed as inconsistent, `false` otherwise
<!-- trait ToggleButtonExt::fn get_mode -->
Retrieves whether the button is displayed as a separate indicator
and label. See `ToggleButtonExt::set_mode`.

# Returns

`true` if the togglebutton is drawn as a separate indicator
 and label.
<!-- trait ToggleButtonExt::fn set_active -->
Sets the status of the toggle button. Set to `true` if you want the
`ToggleButton` to be “pressed in”, and `false` to raise it.
This action causes the `ToggleButton::toggled` signal and the
`Button::clicked` signal to be emitted.
## `is_active`
`true` or `false`.
<!-- trait ToggleButtonExt::fn set_inconsistent -->
If the user has selected a range of elements (such as some text or
spreadsheet cells) that are affected by a toggle button, and the
current values in that range are inconsistent, you may want to
display the toggle in an “in between” state. This function turns on
“in between” display. Normally you would turn off the inconsistent
state again if the user toggles the toggle button. This has to be
done manually, `ToggleButtonExt::set_inconsistent` only affects
visual appearance, it doesn’t affect the semantics of the button.
## `setting`
`true` if state is inconsistent
<!-- trait ToggleButtonExt::fn set_mode -->
Sets whether the button is displayed as a separate indicator and label.
You can call this function on a checkbutton or a radiobutton with
`draw_indicator` = `false` to make the button look like a normal button.

This can be used to create linked strip of buttons that work like
a `StackSwitcher`.

This function only affects instances of classes like `CheckButton`
and `RadioButton` that derive from `ToggleButton`,
not instances of `ToggleButton` itself.
## `draw_indicator`
if `true`, draw the button as a separate indicator
and label; if `false`, draw the button like a normal button
<!-- trait ToggleButtonExt::fn toggled -->
Emits the `ToggleButton::toggled` signal on the
`ToggleButton`. There is no good reason for an
application ever to call this function.
<!-- trait ToggleButtonExt::fn connect_toggled -->
Should be connected if you wish to perform an action whenever the
`ToggleButton`'s state is changed.
<!-- struct ToggleToolButton -->
A `ToggleToolButton` is a `ToolItem` that contains a toggle
button.

Use `ToggleToolButton::new` to create a new `ToggleToolButton`.

# CSS nodes

`ToggleToolButton` has a single CSS node with name togglebutton.

# Implements

[`ToggleToolButtonExt`](trait.ToggleToolButtonExt.html), [`ToolButtonExt`](trait.ToolButtonExt.html), [`ToolItemExt`](trait.ToolItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToggleToolButtonExt -->
Trait containing all `ToggleToolButton` methods.

# Implementors

[`RadioToolButton`](struct.RadioToolButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html)
<!-- impl ToggleToolButton::fn new -->
Returns a new `ToggleToolButton`

# Returns

a newly created `ToggleToolButton`
<!-- trait ToggleToolButtonExt::fn get_active -->
Queries a `ToggleToolButton` and returns its current state.
Returns `true` if the toggle button is pressed in and `false` if it is raised.

# Returns

`true` if the toggle tool button is pressed in, `false` if not
<!-- trait ToggleToolButtonExt::fn set_active -->
Sets the status of the toggle tool button. Set to `true` if you
want the `ToggleButton` to be “pressed in”, and `false` to raise it.
This action causes the toggled signal to be emitted.
## `is_active`
whether `self` should be active
<!-- trait ToggleToolButtonExt::fn connect_toggled -->
Emitted whenever the toggle tool button changes state.
<!-- trait ToggleToolButtonExt::fn get_property_active -->
If the toggle tool button should be pressed in.
<!-- trait ToggleToolButtonExt::fn set_property_active -->
If the toggle tool button should be pressed in.
<!-- struct ToolButton -->
``GtkToolButtons`` are ``GtkToolItems`` containing buttons.

Use `ToolButton::new` to create a new `ToolButton`.

The label of a `ToolButton` is determined by the properties
`ToolButton:label-widget`, `ToolButton:label`, and
`ToolButton:stock-id`. If `ToolButton:label-widget` is
non-`None`, then that widget is used as the label. Otherwise, if
`ToolButton:label` is non-`None`, that string is used as the label.
Otherwise, if `ToolButton:stock-id` is non-`None`, the label is
determined by the stock item. Otherwise, the button does not have a label.

The icon of a `ToolButton` is determined by the properties
`ToolButton:icon-widget` and `ToolButton:stock-id`. If
`ToolButton:icon-widget` is non-`None`, then
that widget is used as the icon. Otherwise, if `ToolButton:stock-id` is
non-`None`, the icon is determined by the stock item. Otherwise,
the button does not have a icon.

# CSS nodes

`ToolButton` has a single CSS node with name toolbutton.

# Implements

[`ToolButtonExt`](trait.ToolButtonExt.html), [`ToolItemExt`](trait.ToolItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToolButtonExt -->
Trait containing all `ToolButton` methods.

# Implementors

[`MenuToolButton`](struct.MenuToolButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html)
<!-- impl ToolButton::fn new -->
Creates a new `ToolButton` using `icon_widget` as contents and `label` as
label.
## `icon_widget`
a widget that will be used as the button contents, or `None`
## `label`
a string that will be used as label, or `None`

# Returns

A new `ToolButton`
<!-- trait ToolButtonExt::fn get_icon_name -->
Returns the name of the themed icon for the tool button,
see `ToolButtonExt::set_icon_name`.

# Returns

the icon name or `None` if the tool button has
no themed icon
<!-- trait ToolButtonExt::fn get_icon_widget -->
Return the widget used as icon widget on `self`.
See `ToolButtonExt::set_icon_widget`.

# Returns

The widget used as icon
 on `self`, or `None`.
<!-- trait ToolButtonExt::fn get_label -->
Returns the label used by the tool button, or `None` if the tool button
doesn’t have a label. or uses a the label from a stock item. The returned
string is owned by GTK+, and must not be modified or freed.

# Returns

The label, or `None`
<!-- trait ToolButtonExt::fn get_label_widget -->
Returns the widget used as label on `self`.
See `ToolButtonExt::set_label_widget`.

# Returns

The widget used as label
 on `self`, or `None`.
<!-- trait ToolButtonExt::fn get_use_underline -->
Returns whether underscores in the label property are used as mnemonics
on menu items on the overflow menu. See `ToolButtonExt::set_use_underline`.

# Returns

`true` if underscores in the label property are used as
mnemonics on menu items on the overflow menu.
<!-- trait ToolButtonExt::fn set_icon_name -->
Sets the icon for the tool button from a named themed icon.
See the docs for `IconTheme` for more details.
The `ToolButton:icon-name` property only has an effect if not
overridden by non-`None` `ToolButton:label-widget`,
`ToolButton:icon-widget` and `ToolButton:stock-id` properties.
## `icon_name`
the name of the themed icon
<!-- trait ToolButtonExt::fn set_icon_widget -->
Sets `icon` as the widget used as icon on `self`. If `icon_widget` is
`None` the icon is determined by the `ToolButton:stock-id` property. If the
`ToolButton:stock-id` property is also `None`, `self` will not have an icon.
## `icon_widget`
the widget used as icon, or `None`
<!-- trait ToolButtonExt::fn set_label -->
Sets `label` as the label used for the tool button. The `ToolButton:label`
property only has an effect if not overridden by a non-`None`
`ToolButton:label-widget` property. If both the `ToolButton:label-widget`
and `ToolButton:label` properties are `None`, the label is determined by the
`ToolButton:stock-id` property. If the `ToolButton:stock-id` property is
also `None`, `self` will not have a label.
## `label`
a string that will be used as label, or `None`.
<!-- trait ToolButtonExt::fn set_label_widget -->
Sets `label_widget` as the widget that will be used as the label
for `self`. If `label_widget` is `None` the `ToolButton:label` property is used
as label. If `ToolButton:label` is also `None`, the label in the stock item
determined by the `ToolButton:stock-id` property is used as label. If
`ToolButton:stock-id` is also `None`, `self` does not have a label.
## `label_widget`
the widget used as label, or `None`
<!-- trait ToolButtonExt::fn set_use_underline -->
If set, an underline in the label property indicates that the next character
should be used for the mnemonic accelerator key in the overflow menu. For
example, if the label property is “_Open” and `use_underline` is `true`,
the label on the tool button will be “Open” and the item on the overflow
menu will have an underlined “O”.

Labels shown on tool buttons never have mnemonics on them; this property
only affects the menu item on the overflow menu.
## `use_underline`
whether the button label has the form “_Open”
<!-- trait ToolButtonExt::fn connect_clicked -->
This signal is emitted when the tool button is clicked with the mouse
or activated with the keyboard.
<!-- trait ToolButtonExt::fn get_property_icon_name -->
The name of the themed icon displayed on the item.
This property only has an effect if not overridden by
`ToolButton:label-widget`, `ToolButton:icon-widget` or
`ToolButton:stock-id` properties.
<!-- trait ToolButtonExt::fn set_property_icon_name -->
The name of the themed icon displayed on the item.
This property only has an effect if not overridden by
`ToolButton:label-widget`, `ToolButton:icon-widget` or
`ToolButton:stock-id` properties.
<!-- struct ToolItem -->
``GtkToolItems`` are widgets that can appear on a toolbar. To
create a toolbar item that contain something else than a button, use
`ToolItem::new`. Use `ContainerExt::add` to add a child
widget to the tool item.

For toolbar items that contain buttons, see the `ToolButton`,
`ToggleToolButton` and `RadioToolButton` classes.

See the `Toolbar` class for a description of the toolbar widget, and
`ToolShell` for a description of the tool shell interface.

# Implements

[`ToolItemExt`](trait.ToolItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToolItemExt -->
Trait containing all `ToolItem` methods.

# Implementors

[`SeparatorToolItem`](struct.SeparatorToolItem.html), [`ToolButton`](struct.ToolButton.html), [`ToolItem`](struct.ToolItem.html)
<!-- impl ToolItem::fn new -->
Creates a new `ToolItem`

# Returns

the new `ToolItem`
<!-- trait ToolItemExt::fn get_ellipsize_mode -->
Returns the ellipsize mode used for `self`. Custom subclasses of
`ToolItem` should call this function to find out how text should
be ellipsized.

# Returns

a `pango::EllipsizeMode` indicating how text in `self`
should be ellipsized.
<!-- trait ToolItemExt::fn get_expand -->
Returns whether `self` is allocated extra space.
See `ToolItemExt::set_expand`.

# Returns

`true` if `self` is allocated extra space.
<!-- trait ToolItemExt::fn get_homogeneous -->
Returns whether `self` is the same size as other homogeneous
items. See `ToolItemExt::set_homogeneous`.

# Returns

`true` if the item is the same size as other homogeneous
items.
<!-- trait ToolItemExt::fn get_icon_size -->
Returns the icon size used for `self`. Custom subclasses of
`ToolItem` should call this function to find out what size icons
they should use.

# Returns

a `IconSize` indicating the icon size
used for `self`
<!-- trait ToolItemExt::fn get_is_important -->
Returns whether `self` is considered important. See
`ToolItemExt::set_is_important`

# Returns

`true` if `self` is considered important.
<!-- trait ToolItemExt::fn get_orientation -->
Returns the orientation used for `self`. Custom subclasses of
`ToolItem` should call this function to find out what size icons
they should use.

# Returns

a `Orientation` indicating the orientation
used for `self`
<!-- trait ToolItemExt::fn get_proxy_menu_item -->
If `menu_item_id` matches the string passed to
`ToolItemExt::set_proxy_menu_item` return the corresponding `MenuItem`.

Custom subclasses of `ToolItem` should use this function to
update their menu item when the `ToolItem` changes. That the
`menu_item_ids` must match ensures that a `ToolItem`
will not inadvertently change a menu item that they did not create.
## `menu_item_id`
a string used to identify the menu item

# Returns

The `MenuItem` passed to
 `ToolItemExt::set_proxy_menu_item`, if the `menu_item_ids`
 match.
<!-- trait ToolItemExt::fn get_relief_style -->
Returns the relief style of `self`. See `ButtonExt::set_relief`.
Custom subclasses of `ToolItem` should call this function in the handler
of the `ToolItem::toolbar_reconfigured` signal to find out the
relief style of buttons.

# Returns

a `ReliefStyle` indicating the relief style used
for `self`.
<!-- trait ToolItemExt::fn get_text_alignment -->
Returns the text alignment used for `self`. Custom subclasses of
`ToolItem` should call this function to find out how text should
be aligned.

# Returns

a `gfloat` indicating the horizontal text alignment
used for `self`
<!-- trait ToolItemExt::fn get_text_orientation -->
Returns the text orientation used for `self`. Custom subclasses of
`ToolItem` should call this function to find out how text should
be orientated.

# Returns

a `Orientation` indicating the text orientation
used for `self`
<!-- trait ToolItemExt::fn get_text_size_group -->
Returns the size group used for labels in `self`.
Custom subclasses of `ToolItem` should call this function
and use the size group for labels.

# Returns

a `SizeGroup`
<!-- trait ToolItemExt::fn get_toolbar_style -->
Returns the toolbar style used for `self`. Custom subclasses of
`ToolItem` should call this function in the handler of the
`ToolItem`::toolbar_reconfigured signal to find out in what style
the toolbar is displayed and change themselves accordingly

Possibilities are:
- `ToolbarStyle::Both`, meaning the tool item should show
 both an icon and a label, stacked vertically
- `ToolbarStyle::Icons`, meaning the toolbar shows only icons
- `ToolbarStyle::Text`, meaning the tool item should only show text
- `ToolbarStyle::BothHoriz`, meaning the tool item should show
 both an icon and a label, arranged horizontally

# Returns

A `ToolbarStyle` indicating the toolbar style used
for `self`.
<!-- trait ToolItemExt::fn get_use_drag_window -->
Returns whether `self` has a drag window. See
`ToolItemExt::set_use_drag_window`.

# Returns

`true` if `self` uses a drag window.
<!-- trait ToolItemExt::fn get_visible_horizontal -->
Returns whether the `self` is visible on toolbars that are
docked horizontally.

# Returns

`true` if `self` is visible on toolbars that are
docked horizontally.
<!-- trait ToolItemExt::fn get_visible_vertical -->
Returns whether `self` is visible when the toolbar is docked vertically.
See `ToolItemExt::set_visible_vertical`.

# Returns

Whether `self` is visible when the toolbar is docked vertically
<!-- trait ToolItemExt::fn rebuild_menu -->
Calling this function signals to the toolbar that the
overflow menu item for `self` has changed. If the
overflow menu is visible when this function it called,
the menu will be rebuilt.

The function must be called when the tool item changes what it
will do in response to the `ToolItem::create-menu-proxy` signal.
<!-- trait ToolItemExt::fn retrieve_proxy_menu_item -->
Returns the `MenuItem` that was last set by
`ToolItemExt::set_proxy_menu_item`, ie. the `MenuItem`
that is going to appear in the overflow menu.

# Returns

The `MenuItem` that is going to appear in the
overflow menu for `self`.
<!-- trait ToolItemExt::fn set_expand -->
Sets whether `self` is allocated extra space when there
is more room on the toolbar then needed for the items. The
effect is that the item gets bigger when the toolbar gets bigger
and smaller when the toolbar gets smaller.
## `expand`
Whether `self` is allocated extra space
<!-- trait ToolItemExt::fn set_homogeneous -->
Sets whether `self` is to be allocated the same size as other
homogeneous items. The effect is that all homogeneous items will have
the same width as the widest of the items.
## `homogeneous`
whether `self` is the same size as other homogeneous items
<!-- trait ToolItemExt::fn set_is_important -->
Sets whether `self` should be considered important. The `ToolButton`
class uses this property to determine whether to show or hide its label
when the toolbar style is `ToolbarStyle::BothHoriz`. The result is that
only tool buttons with the “is_important” property set have labels, an
effect known as “priority text”
## `is_important`
whether the tool item should be considered important
<!-- trait ToolItemExt::fn set_proxy_menu_item -->
Sets the `MenuItem` used in the toolbar overflow menu. The
`menu_item_id` is used to identify the caller of this function and
should also be used with `ToolItemExt::get_proxy_menu_item`.

See also `ToolItem::create-menu-proxy`.
## `menu_item_id`
a string used to identify `menu_item`
## `menu_item`
a `MenuItem` to use in the overflow menu, or `None`
<!-- trait ToolItemExt::fn set_tooltip_markup -->
Sets the markup text to be displayed as tooltip on the item.
See `WidgetExt::set_tooltip_markup`.
## `markup`
markup text to be used as tooltip for `self`
<!-- trait ToolItemExt::fn set_tooltip_text -->
Sets the text to be displayed as tooltip on the item.
See `WidgetExt::set_tooltip_text`.
## `text`
text to be used as tooltip for `self`
<!-- trait ToolItemExt::fn set_use_drag_window -->
Sets whether `self` has a drag window. When `true` the
toolitem can be used as a drag source through `Widget::drag_source_set`.
When `self` has a drag window it will intercept all events,
even those that would otherwise be sent to a child of `self`.
## `use_drag_window`
Whether `self` has a drag window.
<!-- trait ToolItemExt::fn set_visible_horizontal -->
Sets whether `self` is visible when the toolbar is docked horizontally.
## `visible_horizontal`
Whether `self` is visible when in horizontal mode
<!-- trait ToolItemExt::fn set_visible_vertical -->
Sets whether `self` is visible when the toolbar is docked
vertically. Some tool items, such as text entries, are too wide to be
useful on a vertically docked toolbar. If `visible_vertical` is `false`
`self` will not appear on toolbars that are docked vertically.
## `visible_vertical`
whether `self` is visible when the toolbar
is in vertical mode
<!-- trait ToolItemExt::fn toolbar_reconfigured -->
Emits the signal `ToolItem::toolbar_reconfigured` on `self`.
`Toolbar` and other `ToolShell` implementations use this function
to notify children, when some aspect of their configuration changes.
<!-- trait ToolItemExt::fn connect_create_menu_proxy -->
This signal is emitted when the toolbar needs information from `tool_item`
about whether the item should appear in the toolbar overflow menu. In
response the tool item should either

- call `ToolItemExt::set_proxy_menu_item` with a `None`
 pointer and return `true` to indicate that the item should not appear
 in the overflow menu

- call `ToolItemExt::set_proxy_menu_item` with a new menu
 item and return `true`, or

- return `false` to indicate that the signal was not handled by the item.
 This means that the item will not appear in the overflow menu unless
 a later handler installs a menu item.

The toolbar may cache the result of this signal. When the tool item changes
how it will respond to this signal it must call `ToolItemExt::rebuild_menu`
to invalidate the cache and ensure that the toolbar rebuilds its overflow
menu.

# Returns

`true` if the signal was handled, `false` if not
<!-- trait ToolItemExt::fn connect_toolbar_reconfigured -->
This signal is emitted when some property of the toolbar that the
item is a child of changes. For custom subclasses of `ToolItem`,
the default handler of this signal use the functions
- `ToolShell::get_orientation`
- `ToolShell::get_style`
- `ToolShell::get_icon_size`
- `ToolShell::get_relief_style`
to find out what the toolbar should look like and change
themselves accordingly.
<!-- struct ToolItemGroup -->
A `ToolItemGroup` is used together with `ToolPalette` to add
``GtkToolItems`` to a palette like container with different
categories and drag and drop support.

# CSS nodes

`ToolItemGroup` has a single CSS node named toolitemgroup.

# Implements

[`ToolItemGroupExt`](trait.ToolItemGroupExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ToolShellExt`](trait.ToolShellExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToolItemGroupExt -->
Trait containing all `ToolItemGroup` methods.

# Implementors

[`ToolItemGroup`](struct.ToolItemGroup.html)
<!-- impl ToolItemGroup::fn new -->
Creates a new tool item group with label `label`.
## `label`
the label of the new group

# Returns

a new `ToolItemGroup`.
<!-- trait ToolItemGroupExt::fn get_collapsed -->
Gets whether `self` is collapsed or expanded.

# Returns

`true` if `self` is collapsed, `false` if it is expanded
<!-- trait ToolItemGroupExt::fn get_drop_item -->
Gets the tool item at position (x, y).
## `x`
the x position
## `y`
the y position

# Returns

the `ToolItem` at position (x, y)
<!-- trait ToolItemGroupExt::fn get_ellipsize -->
Gets the ellipsization mode of `self`.

# Returns

the `pango::EllipsizeMode` of `self`
<!-- trait ToolItemGroupExt::fn get_header_relief -->
Gets the relief mode of the header button of `self`.

# Returns

the `ReliefStyle`
<!-- trait ToolItemGroupExt::fn get_item_position -->
Gets the position of `item` in `self` as index.
## `item`
a `ToolItem`

# Returns

the index of `item` in `self` or -1 if `item` is no child of `self`
<!-- trait ToolItemGroupExt::fn get_label -->
Gets the label of `self`.

# Returns

the label of `self`. The label is an internal string of `self`
 and must not be modified. Note that `None` is returned if a custom
 label has been set with `ToolItemGroupExt::set_label_widget`
<!-- trait ToolItemGroupExt::fn get_label_widget -->
Gets the label widget of `self`.
See `ToolItemGroupExt::set_label_widget`.

# Returns

the label widget of `self`
<!-- trait ToolItemGroupExt::fn get_n_items -->
Gets the number of tool items in `self`.

# Returns

the number of tool items in `self`
<!-- trait ToolItemGroupExt::fn get_nth_item -->
Gets the tool item at `index` in group.
## `index`
the index

# Returns

the `ToolItem` at index
<!-- trait ToolItemGroupExt::fn insert -->
Inserts `item` at `position` in the list of children of `self`.
## `item`
the `ToolItem` to insert into `self`
## `position`
the position of `item` in `self`, starting with 0.
 The position -1 means end of list.
<!-- trait ToolItemGroupExt::fn set_collapsed -->
Sets whether the `self` should be collapsed or expanded.
## `collapsed`
whether the `self` should be collapsed or expanded
<!-- trait ToolItemGroupExt::fn set_ellipsize -->
Sets the ellipsization mode which should be used by labels in `self`.
## `ellipsize`
the `pango::EllipsizeMode` labels in `self` should use
<!-- trait ToolItemGroupExt::fn set_header_relief -->
Set the button relief of the group header.
See `ButtonExt::set_relief` for details.
## `style`
the `ReliefStyle`
<!-- trait ToolItemGroupExt::fn set_item_position -->
Sets the position of `item` in the list of children of `self`.
## `item`
the `ToolItem` to move to a new position, should
 be a child of `self`.
## `position`
the new position of `item` in `self`, starting with 0.
 The position -1 means end of list.
<!-- trait ToolItemGroupExt::fn set_label -->
Sets the label of the tool item group. The label is displayed in the header
of the group.
## `label`
the new human-readable label of of the group
<!-- trait ToolItemGroupExt::fn set_label_widget -->
Sets the label of the tool item group.
The label widget is displayed in the header of the group, in place
of the usual label.
## `label_widget`
the widget to be displayed in place of the usual label
<!-- struct ToolPalette -->
A `ToolPalette` allows you to add ``GtkToolItems`` to a palette-like
container with different categories and drag and drop support.

A `ToolPalette` is created with a call to `ToolPalette::new`.

``GtkToolItems`` cannot be added directly to a `ToolPalette` -
instead they are added to a `ToolItemGroup` which can than be added
to a `ToolPalette`. To add a `ToolItemGroup` to a `ToolPalette`,
use `ContainerExt::add`.


```C
GtkWidget *palette, *group;
GtkToolItem *item;

palette = gtk_tool_palette_new ();
group = gtk_tool_item_group_new (_("Test Category"));
gtk_container_add (GTK_CONTAINER (palette), group);

item = gtk_tool_button_new (NULL, _("_Open"));
gtk_tool_button_set_icon_name (GTK_TOOL_BUTTON (item), "document-open");
gtk_tool_item_group_insert (GTK_TOOL_ITEM_GROUP (group), item, -1);
```

The easiest way to use drag and drop with `ToolPalette` is to call
`ToolPaletteExt::add_drag_dest` with the desired drag source `palette`
and the desired drag target `widget`. Then `ToolPaletteExt::get_drag_item`
can be used to get the dragged item in the `Widget::drag-data-received`
signal handler of the drag target.


```C
static void
passive_canvas_drag_data_received (GtkWidget        *widget,
                                   GdkDragContext   *context,
                                   gint              x,
                                   gint              y,
                                   GtkSelectionData *selection,
                                   guint             info,
                                   guint             time,
                                   gpointer          data)
{
  GtkWidget *palette;
  GtkWidget *item;

  // Get the dragged item
  palette = gtk_widget_get_ancestor (gtk_drag_get_source_widget (context),
                                     GTK_TYPE_TOOL_PALETTE);
  if (palette != NULL)
    item = gtk_tool_palette_get_drag_item (GTK_TOOL_PALETTE (palette),
                                           selection);

  // Do something with item
}

GtkWidget *target, palette;

palette = gtk_tool_palette_new ();
target = gtk_drawing_area_new ();

g_signal_connect (G_OBJECT (target), "drag-data-received",
                  G_CALLBACK (passive_canvas_drag_data_received), NULL);
gtk_tool_palette_add_drag_dest (GTK_TOOL_PALETTE (palette), target,
                                GTK_DEST_DEFAULT_ALL,
                                GTK_TOOL_PALETTE_DRAG_ITEMS,
                                GDK_ACTION_COPY);
```

# CSS nodes

`ToolPalette` has a single CSS node named toolpalette.

# Implements

[`ToolPaletteExt`](trait.ToolPaletteExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`ScrollableExt`](trait.ScrollableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToolPaletteExt -->
Trait containing all `ToolPalette` methods.

# Implementors

[`ToolPalette`](struct.ToolPalette.html)
<!-- impl ToolPalette::fn new -->
Creates a new tool palette.

# Returns

a new `ToolPalette`
<!-- impl ToolPalette::fn get_drag_target_group -->
Get the target entry for a dragged `ToolItemGroup`.

# Returns

the `TargetEntry` for a dragged group
<!-- impl ToolPalette::fn get_drag_target_item -->
Gets the target entry for a dragged `ToolItem`.

# Returns

the `TargetEntry` for a dragged item.
<!-- trait ToolPaletteExt::fn add_drag_dest -->
Sets `self` as drag source (see `ToolPaletteExt::set_drag_source`)
and sets `widget` as a drag destination for drags from `self`.
See `Widget::drag_dest_set`.
## `widget`
a `Widget` which should be a drag destination for `self`
## `flags`
the flags that specify what actions GTK+ should take for drops
 on that widget
## `targets`
the `ToolPaletteDragTargets` which the widget
 should support
## `actions`
the ``GdkDragActions`` which the widget should suppport
<!-- trait ToolPaletteExt::fn get_drag_item -->
Get the dragged item from the selection.
This could be a `ToolItem` or a `ToolItemGroup`.
## `selection`
a `SelectionData`

# Returns

the dragged item in selection
<!-- trait ToolPaletteExt::fn get_drop_group -->
Gets the group at position (x, y).
## `x`
the x position
## `y`
the y position

# Returns

the `ToolItemGroup` at position
or `None` if there is no such group
<!-- trait ToolPaletteExt::fn get_drop_item -->
Gets the item at position (x, y).
See `ToolPaletteExt::get_drop_group`.
## `x`
the x position
## `y`
the y position

# Returns

the `ToolItem` at position or `None` if there is no such item
<!-- trait ToolPaletteExt::fn get_exclusive -->
Gets whether `group` is exclusive or not.
See `ToolPaletteExt::set_exclusive`.
## `group`
a `ToolItemGroup` which is a child of palette

# Returns

`true` if `group` is exclusive
<!-- trait ToolPaletteExt::fn get_expand -->
Gets whether group should be given extra space.
See `ToolPaletteExt::set_expand`.
## `group`
a `ToolItemGroup` which is a child of palette

# Returns

`true` if group should be given extra space, `false` otherwise
<!-- trait ToolPaletteExt::fn get_group_position -->
Gets the position of `group` in `self` as index.
See `ToolPaletteExt::set_group_position`.
## `group`
a `ToolItemGroup`

# Returns

the index of group or -1 if `group` is not a child of `self`
<!-- trait ToolPaletteExt::fn get_icon_size -->
Gets the size of icons in the tool palette.
See `ToolPaletteExt::set_icon_size`.

# Returns

the `IconSize` of icons in the tool palette
<!-- trait ToolPaletteExt::fn get_style -->
Gets the style (icons, text or both) of items in the tool palette.

# Returns

the `ToolbarStyle` of items in the tool palette.
<!-- trait ToolPaletteExt::fn set_drag_source -->
Sets the tool palette as a drag source.
Enables all groups and items in the tool palette as drag sources
on button 1 and button 3 press with copy and move actions.
See `Widget::drag_source_set`.
## `targets`
the `ToolPaletteDragTargets`
 which the widget should support
<!-- trait ToolPaletteExt::fn set_exclusive -->
Sets whether the group should be exclusive or not.
If an exclusive group is expanded all other groups are collapsed.
## `group`
a `ToolItemGroup` which is a child of palette
## `exclusive`
whether the group should be exclusive or not
<!-- trait ToolPaletteExt::fn set_expand -->
Sets whether the group should be given extra space.
## `group`
a `ToolItemGroup` which is a child of palette
## `expand`
whether the group should be given extra space
<!-- trait ToolPaletteExt::fn set_group_position -->
Sets the position of the group as an index of the tool palette.
If position is 0 the group will become the first child, if position is
-1 it will become the last child.
## `group`
a `ToolItemGroup` which is a child of palette
## `position`
a new index for group
<!-- trait ToolPaletteExt::fn set_icon_size -->
Sets the size of icons in the tool palette.
## `icon_size`
the `IconSize` that icons in the tool
 palette shall have
<!-- trait ToolPaletteExt::fn set_style -->
Sets the style (text, icons or both) of items in the tool palette.
## `style`
the `ToolbarStyle` that items in the tool palette shall have
<!-- trait ToolPaletteExt::fn unset_icon_size -->
Unsets the tool palette icon size set with `ToolPaletteExt::set_icon_size`,
so that user preferences will be used to determine the icon size.
<!-- trait ToolPaletteExt::fn unset_style -->
Unsets a toolbar style set with `ToolPaletteExt::set_style`,
so that user preferences will be used to determine the toolbar style.
<!-- trait ToolPaletteExt::fn get_property_icon_size -->
The size of the icons in a tool palette. When this property is set,
it overrides the default setting.

This should only be used for special-purpose tool palettes, normal
application tool palettes should respect the user preferences for the
size of icons.
<!-- trait ToolPaletteExt::fn set_property_icon_size -->
The size of the icons in a tool palette. When this property is set,
it overrides the default setting.

This should only be used for special-purpose tool palettes, normal
application tool palettes should respect the user preferences for the
size of icons.
<!-- trait ToolPaletteExt::fn get_property_icon_size_set -->
Is `true` if the `ToolPalette:icon-size` property has been set.
<!-- trait ToolPaletteExt::fn set_property_icon_size_set -->
Is `true` if the `ToolPalette:icon-size` property has been set.
<!-- trait ToolPaletteExt::fn get_property_toolbar_style -->
The style of items in the tool palette.
<!-- trait ToolPaletteExt::fn set_property_toolbar_style -->
The style of items in the tool palette.
<!-- struct ToolPaletteDragTargets -->
Flags used to specify the supported drag targets.
<!-- struct ToolPaletteDragTargets::const ITEMS -->
Support drag of items.
<!-- struct ToolPaletteDragTargets::const GROUPS -->
Support drag of groups.
<!-- struct ToolShell -->
The `ToolShell` interface allows container widgets to provide additional
information when embedding `ToolItem` widgets.

# Implements

[`ToolShellExt`](trait.ToolShellExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToolShellExt -->
Trait containing all `ToolShell` methods.

# Implementors

[`ToolItemGroup`](struct.ToolItemGroup.html), [`ToolShell`](struct.ToolShell.html), [`Toolbar`](struct.Toolbar.html)
<!-- trait ToolShellExt::fn get_ellipsize_mode -->
Retrieves the current ellipsize mode for the tool shell. Tool items must not
call this function directly, but rely on `ToolItemExt::get_ellipsize_mode`
instead.

# Returns

the current ellipsize mode of `self`
<!-- trait ToolShellExt::fn get_icon_size -->
Retrieves the icon size for the tool shell. Tool items must not call this
function directly, but rely on `ToolItemExt::get_icon_size` instead.

# Returns

the current size (`IconSize`) for icons of `self`
<!-- trait ToolShellExt::fn get_orientation -->
Retrieves the current orientation for the tool shell. Tool items must not
call this function directly, but rely on `ToolItemExt::get_orientation`
instead.

# Returns

the current orientation of `self`
<!-- trait ToolShellExt::fn get_relief_style -->
Returns the relief style of buttons on `self`. Tool items must not call this
function directly, but rely on `ToolItemExt::get_relief_style` instead.

# Returns

The relief style of buttons on `self`.
<!-- trait ToolShellExt::fn get_style -->
Retrieves whether the tool shell has text, icons, or both. Tool items must
not call this function directly, but rely on `ToolItemExt::get_toolbar_style`
instead.

# Returns

the current style of `self`
<!-- trait ToolShellExt::fn get_text_alignment -->
Retrieves the current text alignment for the tool shell. Tool items must not
call this function directly, but rely on `ToolItemExt::get_text_alignment`
instead.

# Returns

the current text alignment of `self`
<!-- trait ToolShellExt::fn get_text_orientation -->
Retrieves the current text orientation for the tool shell. Tool items must not
call this function directly, but rely on `ToolItemExt::get_text_orientation`
instead.

# Returns

the current text orientation of `self`
<!-- trait ToolShellExt::fn get_text_size_group -->
Retrieves the current text size group for the tool shell. Tool items must not
call this function directly, but rely on `ToolItemExt::get_text_size_group`
instead.

# Returns

the current text size group of `self`
<!-- trait ToolShellExt::fn rebuild_menu -->
Calling this function signals the tool shell that the overflow menu item for
tool items have changed. If there is an overflow menu and if it is visible
when this function it called, the menu will be rebuilt.

Tool items must not call this function directly, but rely on
`ToolItemExt::rebuild_menu` instead.
<!-- struct Toolbar -->
A toolbar is created with a call to `Toolbar::new`.

A toolbar can contain instances of a subclass of `ToolItem`. To add
a `ToolItem` to the a toolbar, use `ToolbarExt::insert`. To remove
an item from the toolbar use `ContainerExt::remove`. To add a button
to the toolbar, add an instance of `ToolButton`.

Toolbar items can be visually grouped by adding instances of
`SeparatorToolItem` to the toolbar. If the `Toolbar` child property
“expand” is `true` and the property `SeparatorToolItem:draw` is set to
`false`, the effect is to force all following items to the end of the toolbar.

By default, a toolbar can be shrunk, upon which it will add an arrow button
to show an overflow menu offering access to any `ToolItem` child that has
a proxy menu item. To disable this and request enough size for all children,
call `ToolbarExt::set_show_arrow` to set `Toolbar:show-arrow` to `false`.

Creating a context menu for the toolbar can be done by connecting to
the `Toolbar::popup-context-menu` signal.

# CSS nodes

`Toolbar` has a single CSS node with name toolbar.

# Implements

[`ToolbarExt`](trait.ToolbarExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`ToolShellExt`](trait.ToolShellExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ToolbarExt -->
Trait containing all `Toolbar` methods.

# Implementors

[`Toolbar`](struct.Toolbar.html)
<!-- impl Toolbar::fn new -->
Creates a new toolbar.

# Returns

the newly-created toolbar.
<!-- trait ToolbarExt::fn get_drop_index -->
Returns the position corresponding to the indicated point on
`self`. This is useful when dragging items to the toolbar:
this function returns the position a new item should be
inserted.

`x` and `y` are in `self` coordinates.
## `x`
x coordinate of a point on the toolbar
## `y`
y coordinate of a point on the toolbar

# Returns

The position corresponding to the point (`x`, `y`) on the toolbar.
<!-- trait ToolbarExt::fn get_icon_size -->
Retrieves the icon size for the toolbar. See `ToolbarExt::set_icon_size`.

# Returns

the current icon size for the icons on the toolbar.
<!-- trait ToolbarExt::fn get_item_index -->
Returns the position of `item` on the toolbar, starting from 0.
It is an error if `item` is not a child of the toolbar.
## `item`
a `ToolItem` that is a child of `self`

# Returns

the position of item on the toolbar.
<!-- trait ToolbarExt::fn get_n_items -->
Returns the number of items on the toolbar.

# Returns

the number of items on the toolbar
<!-- trait ToolbarExt::fn get_nth_item -->
Returns the `n`'th item on `self`, or `None` if the
toolbar does not contain an `n`'th item.
## `n`
A position on the toolbar

# Returns

The `n`'th `ToolItem` on `self`,
 or `None` if there isn’t an `n`'th item.
<!-- trait ToolbarExt::fn get_relief_style -->
Returns the relief style of buttons on `self`. See
`ButtonExt::set_relief`.

# Returns

The relief style of buttons on `self`.
<!-- trait ToolbarExt::fn get_show_arrow -->
Returns whether the toolbar has an overflow menu.
See `ToolbarExt::set_show_arrow`.

# Returns

`true` if the toolbar has an overflow menu.
<!-- trait ToolbarExt::fn get_style -->
Retrieves whether the toolbar has text, icons, or both . See
`ToolbarExt::set_style`.

# Returns

the current style of `self`
<!-- trait ToolbarExt::fn insert -->
Insert a `ToolItem` into the toolbar at position `pos`. If `pos` is
0 the item is prepended to the start of the toolbar. If `pos` is
negative, the item is appended to the end of the toolbar.
## `item`
a `ToolItem`
## `pos`
the position of the new item
<!-- trait ToolbarExt::fn set_drop_highlight_item -->
Highlights `self` to give an idea of what it would look like
if `item` was added to `self` at the position indicated by `index_`.
If `item` is `None`, highlighting is turned off. In that case `index_`
is ignored.

The `tool_item` passed to this function must not be part of any widget
hierarchy. When an item is set as drop highlight item it can not
added to any widget hierarchy or used as highlight item for another
toolbar.
## `tool_item`
a `ToolItem`, or `None` to turn of highlighting
## `index_`
a position on `self`
<!-- trait ToolbarExt::fn set_icon_size -->
This function sets the size of stock icons in the toolbar. You
can call it both before you add the icons and after they’ve been
added. The size you set will override user preferences for the default
icon size.

This should only be used for special-purpose toolbars, normal
application toolbars should respect the user preferences for the
size of icons.
## `icon_size`
The `IconSize` that stock icons in the toolbar shall have.
<!-- trait ToolbarExt::fn set_show_arrow -->
Sets whether to show an overflow menu when `self` isn’t allocated enough
size to show all of its items. If `true`, items which can’t fit in `self`,
and which have a proxy menu item set by `ToolItemExt::set_proxy_menu_item`
or `ToolItem::create-menu-proxy`, will be available in an overflow menu,
which can be opened by an added arrow button. If `false`, `self` will
request enough size to fit all of its child items without any overflow.
## `show_arrow`
Whether to show an overflow menu
<!-- trait ToolbarExt::fn set_style -->
Alters the view of `self` to display either icons only, text only, or both.
## `style`
the new style for `self`.
<!-- trait ToolbarExt::fn unset_icon_size -->
Unsets toolbar icon size set with `ToolbarExt::set_icon_size`, so that
user preferences will be used to determine the icon size.
<!-- trait ToolbarExt::fn unset_style -->
Unsets a toolbar style set with `ToolbarExt::set_style`, so that
user preferences will be used to determine the toolbar style.
<!-- trait ToolbarExt::fn connect_focus_home_or_end -->
A keybinding signal used internally by GTK+. This signal can't
be used in application code
## `focus_home`
`true` if the first item should be focused

# Returns

`true` if the signal was handled, `false` if not
<!-- trait ToolbarExt::fn connect_orientation_changed -->
Emitted when the orientation of the toolbar changes.
## `orientation`
the new `Orientation` of the toolbar
<!-- trait ToolbarExt::fn connect_popup_context_menu -->
Emitted when the user right-clicks the toolbar or uses the
keybinding to display a popup menu.

Application developers should handle this signal if they want
to display a context menu on the toolbar. The context-menu should
appear at the coordinates given by `x` and `y`. The mouse button
number is given by the `button` parameter. If the menu was popped
up using the keybaord, `button` is -1.
## `x`
the x coordinate of the point where the menu should appear
## `y`
the y coordinate of the point where the menu should appear
## `button`
the mouse button the user pressed, or -1

# Returns

return `true` if the signal was handled, `false` if not
<!-- trait ToolbarExt::fn connect_style_changed -->
Emitted when the style of the toolbar changes.
## `style`
the new `ToolbarStyle` of the toolbar
<!-- trait ToolbarExt::fn get_property_icon_size -->
The size of the icons in a toolbar is normally determined by
the toolbar-icon-size setting. When this property is set, it
overrides the setting.

This should only be used for special-purpose toolbars, normal
application toolbars should respect the user preferences for the
size of icons.
<!-- trait ToolbarExt::fn set_property_icon_size -->
The size of the icons in a toolbar is normally determined by
the toolbar-icon-size setting. When this property is set, it
overrides the setting.

This should only be used for special-purpose toolbars, normal
application toolbars should respect the user preferences for the
size of icons.
<!-- trait ToolbarExt::fn get_property_icon_size_set -->
Is `true` if the icon-size property has been set.
<!-- trait ToolbarExt::fn set_property_icon_size_set -->
Is `true` if the icon-size property has been set.
<!-- enum ToolbarStyle -->
Used to customize the appearance of a `Toolbar`. Note that
setting the toolbar style overrides the user’s preferences
for the default toolbar style. Note that if the button has only
a label set and GTK_TOOLBAR_ICONS is used, the label will be
visible, and vice versa.
<!-- enum ToolbarStyle::variant Icons -->
Buttons display only icons in the toolbar.
<!-- enum ToolbarStyle::variant Text -->
Buttons display only text labels in the toolbar.
<!-- enum ToolbarStyle::variant Both -->
Buttons display text and icons in the toolbar.
<!-- enum ToolbarStyle::variant BothHoriz -->
Buttons display icons and text alongside each
 other, rather than vertically stacked
<!-- struct Tooltip -->
Basic tooltips can be realized simply by using `WidgetExt::set_tooltip_text`
or `WidgetExt::set_tooltip_markup` without any explicit tooltip object.

When you need a tooltip with a little more fancy contents, like adding an
image, or you want the tooltip to have different contents per `TreeView`
row or cell, you will have to do a little more work:

- Set the `Widget:has-tooltip` property to `true`, this will make GTK+
 monitor the widget for motion and related events which are needed to
 determine when and where to show a tooltip.

- Connect to the `Widget::query-tooltip` signal. This signal will be
 emitted when a tooltip is supposed to be shown. One of the arguments passed
 to the signal handler is a `Tooltip` object. This is the object that we
 are about to display as a tooltip, and can be manipulated in your callback
 using functions like `Tooltip::set_icon`. There are functions for setting
 the tooltip’s markup, setting an image from a named icon, or even putting in
 a custom widget.

 Return `true` from your query-tooltip handler. This causes the tooltip to be
 show. If you return `false`, it will not be shown.

In the probably rare case where you want to have even more control over the
tooltip that is about to be shown, you can set your own `Window` which
will be used as tooltip window. This works as follows:

- Set `Widget:has-tooltip` and connect to `Widget::query-tooltip` as before.
 Use `WidgetExt::set_tooltip_window` to set a `Window` created by you as
 tooltip window.

- In the `Widget::query-tooltip` callback you can access your window using
 `WidgetExt::get_tooltip_window` and manipulate as you wish. The semantics of
 the return value are exactly as before, return `true` to show the window,
 `false` to not show it.

# Implements

[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl Tooltip::fn trigger_tooltip_query -->
Triggers a new tooltip query on `display`, in order to update the current
visible tooltip, or to show/hide the current tooltip. This function is
useful to call when, for example, the state of the widget changed by a
key press.
## `display`
a `gdk::Display`
<!-- impl Tooltip::fn set_custom -->
Replaces the widget packed into the tooltip with
`custom_widget`. `custom_widget` does not get destroyed when the tooltip goes
away.
By default a box with a `Image` and `Label` is embedded in
the tooltip, which can be configured using `Tooltip::set_markup`
and `Tooltip::set_icon`.
## `custom_widget`
a `Widget`, or `None` to unset the old custom widget.
<!-- impl Tooltip::fn set_icon -->
Sets the icon of the tooltip (which is in front of the text) to be
`pixbuf`. If `pixbuf` is `None`, the image will be hidden.
## `pixbuf`
a `gdk_pixbuf::Pixbuf`, or `None`
<!-- impl Tooltip::fn set_icon_from_gicon -->
Sets the icon of the tooltip (which is in front of the text)
to be the icon indicated by `gicon` with the size indicated
by `size`. If `gicon` is `None`, the image will be hidden.
## `gicon`
a `gio::Icon` representing the icon, or `None`
## `size`
a stock icon size (`IconSize`)
<!-- impl Tooltip::fn set_icon_from_icon_name -->
Sets the icon of the tooltip (which is in front of the text) to be
the icon indicated by `icon_name` with the size indicated
by `size`. If `icon_name` is `None`, the image will be hidden.
## `icon_name`
an icon name, or `None`
## `size`
a stock icon size (`IconSize`)
<!-- impl Tooltip::fn set_markup -->
Sets the text of the tooltip to be `markup`, which is marked up
with the [Pango text markup language][PangoMarkupFormat].
If `markup` is `None`, the label will be hidden.
## `markup`
a markup string (see [Pango markup format][PangoMarkupFormat]) or `None`
<!-- impl Tooltip::fn set_text -->
Sets the text of the tooltip to be `text`. If `text` is `None`, the label
will be hidden. See also `Tooltip::set_markup`.
## `text`
a text string or `None`
<!-- impl Tooltip::fn set_tip_area -->
Sets the area of the widget, where the contents of this tooltip apply,
to be `rect` (in widget coordinates). This is especially useful for
properly setting tooltips on `TreeView` rows and cells, ``GtkIconViews``,
etc.

For setting tooltips on `TreeView`, please refer to the convenience
functions for this: `TreeViewExt::set_tooltip_row` and
`TreeViewExt::set_tooltip_cell`.
## `rect`
a `gdk::Rectangle`
<!-- struct TreeDragDest -->


# Implements

[`TreeDragDestExt`](trait.TreeDragDestExt.html)
<!-- trait TreeDragDestExt -->
Trait containing all `TreeDragDest` methods.

# Implementors

[`ListStore`](struct.ListStore.html), [`TreeDragDest`](struct.TreeDragDest.html), [`TreeStore`](struct.TreeStore.html)
<!-- trait TreeDragDestExt::fn drag_data_received -->
Asks the `TreeDragDest` to insert a row before the path `dest`,
deriving the contents of the row from `selection_data`. If `dest` is
outside the tree so that inserting before it is impossible, `false`
will be returned. Also, `false` may be returned if the new row is
not created for some model-specific reason. Should robustly handle
a `dest` no longer found in the model!
## `dest`
row to drop in front of
## `selection_data`
data to drop

# Returns

whether a new row was created before position `dest`
<!-- trait TreeDragDestExt::fn row_drop_possible -->
Determines whether a drop is possible before the given `dest_path`,
at the same depth as `dest_path`. i.e., can we drop the data in
`selection_data` at that location. `dest_path` does not have to
exist; the return value will almost certainly be `false` if the
parent of `dest_path` doesn’t exist, though.
## `dest_path`
destination row
## `selection_data`
the data being dragged

# Returns

`true` if a drop is possible before `dest_path`
<!-- struct TreeDragSource -->


# Implements

[`TreeDragSourceExt`](trait.TreeDragSourceExt.html)
<!-- trait TreeDragSourceExt -->
Trait containing all `TreeDragSource` methods.

# Implementors

[`ListStore`](struct.ListStore.html), [`TreeDragSource`](struct.TreeDragSource.html), [`TreeModelFilter`](struct.TreeModelFilter.html), [`TreeModelSort`](struct.TreeModelSort.html), [`TreeStore`](struct.TreeStore.html)
<!-- trait TreeDragSourceExt::fn drag_data_delete -->
Asks the `TreeDragSource` to delete the row at `path`, because
it was moved somewhere else via drag-and-drop. Returns `false`
if the deletion fails because `path` no longer exists, or for
some model-specific reason. Should robustly handle a `path` no
longer found in the model!
## `path`
row that was being dragged

# Returns

`true` if the row was successfully deleted
<!-- trait TreeDragSourceExt::fn drag_data_get -->
Asks the `TreeDragSource` to fill in `selection_data` with a
representation of the row at `path`. `selection_data`->target gives
the required type of the data. Should robustly handle a `path` no
longer found in the model!
## `path`
row that was dragged
## `selection_data`
a `SelectionData` to fill with data
 from the dragged row

# Returns

`true` if data of the required type was provided
<!-- trait TreeDragSourceExt::fn row_draggable -->
Asks the `TreeDragSource` whether a particular row can be used as
the source of a DND operation. If the source doesn’t implement
this interface, the row is assumed draggable.
## `path`
row on which user is initiating a drag

# Returns

`true` if the row can be dragged
<!-- struct TreeIter -->
The `TreeIter` is the primary structure
for accessing a `TreeModel`. Models are expected to put a unique
integer in the `stamp` member, and put
model-specific data in the three `user_data`
members.
<!-- impl TreeIter::fn copy -->
Creates a dynamically allocated tree iterator as a copy of `self`.

This function is not intended for use in applications,
because you can just copy the structs by value
(`GtkTreeIter new_iter = iter;`).
You must free this iter with `TreeIter::free`.

# Returns

a newly-allocated copy of `self`
<!-- impl TreeIter::fn free -->
Frees an iterator that has been allocated by `TreeIter::copy`.

This function is mainly used for language bindings.
<!-- struct TreeModel -->
The `TreeModel` interface defines a generic tree interface for
use by the `TreeView` widget. It is an abstract interface, and
is designed to be usable with any appropriate data structure. The
programmer just has to implement this interface on their own data
type for it to be viewable by a `TreeView` widget.

The model is represented as a hierarchical tree of strongly-typed,
columned data. In other words, the model can be seen as a tree where
every node has different values depending on which column is being
queried. The type of data found in a column is determined by using
the GType system (ie. `G_TYPE_INT`, `GTK_TYPE_BUTTON`, `G_TYPE_POINTER`,
etc). The types are homogeneous per column across all nodes. It is
important to note that this interface only provides a way of examining
a model and observing changes. The implementation of each individual
model decides how and if changes are made.

In order to make life simpler for programmers who do not need to
write their own specialized model, two generic models are provided
— the `TreeStore` and the `ListStore`. To use these, the
developer simply pushes data into these models as necessary. These
models provide the data structure as well as all appropriate tree
interfaces. As a result, implementing drag and drop, sorting, and
storing data is trivial. For the vast majority of trees and lists,
these two models are sufficient.

Models are accessed on a node/column level of granularity. One can
query for the value of a model at a certain node and a certain
column on that node. There are two structures used to reference a
particular node in a model. They are the `TreePath`-struct and
the `TreeIter`-struct (“iter” is short for iterator). Most of the
interface consists of operations on a `TreeIter`-struct.

A path is essentially a potential node. It is a location on a model
that may or may not actually correspond to a node on a specific
model. The `TreePath`-struct can be converted into either an
array of unsigned integers or a string. The string form is a list
of numbers separated by a colon. Each number refers to the offset
at that level. Thus, the path `0` refers to the root
node and the path `2:4` refers to the fifth child of
the third node.

By contrast, a `TreeIter`-struct is a reference to a specific node on
a specific model. It is a generic struct with an integer and three
generic pointers. These are filled in by the model in a model-specific
way. One can convert a path to an iterator by calling
`TreeModel::get_iter`. These iterators are the primary way
of accessing a model and are similar to the iterators used by
`TextBuffer`. They are generally statically allocated on the
stack and only used for a short time. The model interface defines
a set of operations using them for navigating the model.

It is expected that models fill in the iterator with private data.
For example, the `ListStore` model, which is internally a simple
linked list, stores a list node in one of the pointers. The
`TreeModelSort` stores an array and an offset in two of the
pointers. Additionally, there is an integer field. This field is
generally filled with a unique stamp per model. This stamp is for
catching errors resulting from using invalid iterators with a model.

The lifecycle of an iterator can be a little confusing at first.
Iterators are expected to always be valid for as long as the model
is unchanged (and doesn’t emit a signal). The model is considered
to own all outstanding iterators and nothing needs to be done to
free them from the user’s point of view. Additionally, some models
guarantee that an iterator is valid for as long as the node it refers
to is valid (most notably the `TreeStore` and `ListStore`).
Although generally uninteresting, as one always has to allow for
the case where iterators do not persist beyond a signal, some very
important performance enhancements were made in the sort model.
As a result, the `TreeModelFlags::ItersPersist` flag was added to
indicate this behavior.

To help show some common operation of a model, some examples are
provided. The first example shows three ways of getting the iter at
the location `3:2:5`. While the first method shown is
easier, the second is much more common, as you often get paths from
callbacks.

## Acquiring a `TreeIter`-struct


```C
// Three ways of getting the iter pointing to the location
GtkTreePath *path;
GtkTreeIter iter;
GtkTreeIter parent_iter;

// get the iterator from a string
gtk_tree_model_get_iter_from_string (model,
                                     &iter,
                                     "3:2:5");

// get the iterator from a path
path = gtk_tree_path_new_from_string ("3:2:5");
gtk_tree_model_get_iter (model, &iter, path);
gtk_tree_path_free (path);

// walk the tree to find the iterator
gtk_tree_model_iter_nth_child (model, &iter,
                               NULL, 3);
parent_iter = iter;
gtk_tree_model_iter_nth_child (model, &iter,
                               &parent_iter, 2);
parent_iter = iter;
gtk_tree_model_iter_nth_child (model, &iter,
                               &parent_iter, 5);
```

This second example shows a quick way of iterating through a list
and getting a string and an integer from each row. The
`populate_model` function used below is not
shown, as it is specific to the `ListStore`. For information on
how to write such a function, see the `ListStore` documentation.

## Reading data from a `TreeModel`


```C
enum
{
  STRING_COLUMN,
  INT_COLUMN,
  N_COLUMNS
};

...

GtkTreeModel *list_store;
GtkTreeIter iter;
gboolean valid;
gint row_count = 0;

// make a new list_store
list_store = gtk_list_store_new (N_COLUMNS,
                                 G_TYPE_STRING,
                                 G_TYPE_INT);

// Fill the list store with data
populate_model (list_store);

// Get the first iter in the list, check it is valid and walk
// through the list, reading each row.

valid = gtk_tree_model_get_iter_first (list_store,
                                       &iter);
while (valid)
 {
   gchar *str_data;
   gint   int_data;

   // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value
   gtk_tree_model_get (list_store, &iter,
                       STRING_COLUMN, &str_data,
                       INT_COLUMN, &int_data,
                       -1);

   // Do something with the data
   g_print ("Row %d: (%s,%d)\n",
            row_count, str_data, int_data);
   g_free (str_data);

   valid = gtk_tree_model_iter_next (list_store,
                                     &iter);
   row_count++;
 }
```

The `TreeModel` interface contains two methods for reference
counting: `TreeModel::ref_node` and `TreeModel::unref_node`.
These two methods are optional to implement. The reference counting
is meant as a way for views to let models know when nodes are being
displayed. `TreeView` will take a reference on a node when it is
visible, which means the node is either in the toplevel or expanded.
Being displayed does not mean that the node is currently directly
visible to the user in the viewport. Based on this reference counting
scheme a caching model, for example, can decide whether or not to cache
a node based on the reference count. A file-system based model would
not want to keep the entire file hierarchy in memory, but just the
folders that are currently expanded in every current view.

When working with reference counting, the following rules must be taken
into account:

- Never take a reference on a node without owning a reference on its parent.
 This means that all parent nodes of a referenced node must be referenced
 as well.

- Outstanding references on a deleted node are not released. This is not
 possible because the node has already been deleted by the time the
 row-deleted signal is received.

- Models are not obligated to emit a signal on rows of which none of its
 siblings are referenced. To phrase this differently, signals are only
 required for levels in which nodes are referenced. For the root level
 however, signals must be emitted at all times (however the root level
 is always referenced when any view is attached).

# Implements

[`TreeModelExt`](trait.TreeModelExt.html)
<!-- trait TreeModelExt -->
Trait containing all `TreeModel` methods.

# Implementors

[`ListStore`](struct.ListStore.html), [`TreeModelFilter`](struct.TreeModelFilter.html), [`TreeModelSort`](struct.TreeModelSort.html), [`TreeModel`](struct.TreeModel.html), [`TreeSortable`](struct.TreeSortable.html), [`TreeStore`](struct.TreeStore.html)
<!-- trait TreeModelExt::fn filter_new -->
Creates a new `TreeModel`, with `self` as the child_model
and `root` as the virtual root.
## `root`
A `TreePath` or `None`.

# Returns

A new `TreeModel`.
<!-- trait TreeModelExt::fn foreach -->
Calls func on each node in model in a depth-first fashion.

If `func` returns `true`, then the tree ceases to be walked,
and `TreeModel::foreach` returns.
## `func`
a function to be called on each row
## `user_data`
user data to passed to `func`
<!-- trait TreeModelExt::fn get -->
Gets the value of one or more cells in the row referenced by `iter`.
The variable argument list should contain integer column numbers,
each column number followed by a place to store the value being
retrieved. The list is terminated by a -1. For example, to get a
value from column 0 with type `G_TYPE_STRING`, you would
write: `gtk_tree_model_get (model, iter, 0, &place_string_here, -1)`,
where `place_string_here` is a `gchararray`
to be filled with the string.

Returned values with type `G_TYPE_OBJECT` have to be unreferenced,
values with type `G_TYPE_STRING` or `G_TYPE_BOXED` have to be freed.
Other values are passed by value.
## `iter`
a row in `self`
<!-- trait TreeModelExt::fn get_column_type -->
Returns the type of the column.
## `index_`
the column index

# Returns

the type of the column
<!-- trait TreeModelExt::fn get_flags -->
Returns a set of flags supported by this interface.

The flags are a bitwise combination of `TreeModelFlags`.
The flags supported should not change during the lifetime
of the `self`.

# Returns

the flags supported by this interface
<!-- trait TreeModelExt::fn get_iter -->
Sets `iter` to a valid iterator pointing to `path`. If `path` does
not exist, `iter` is set to an invalid iterator and `false` is returned.
## `iter`
the uninitialized `TreeIter`-struct
## `path`
the `TreePath`-struct

# Returns

`true`, if `iter` was set
<!-- trait TreeModelExt::fn get_iter_first -->
Initializes `iter` with the first iterator in the tree
(the one at the path "0") and returns `true`. Returns
`false` if the tree is empty.
## `iter`
the uninitialized `TreeIter`-struct

# Returns

`true`, if `iter` was set
<!-- trait TreeModelExt::fn get_iter_from_string -->
Sets `iter` to a valid iterator pointing to `path_string`, if it
exists. Otherwise, `iter` is left invalid and `false` is returned.
## `iter`
an uninitialized `TreeIter`-struct
## `path_string`
a string representation of a `TreePath`-struct

# Returns

`true`, if `iter` was set
<!-- trait TreeModelExt::fn get_n_columns -->
Returns the number of columns supported by `self`.

# Returns

the number of columns
<!-- trait TreeModelExt::fn get_path -->
Returns a newly-created `TreePath`-struct referenced by `iter`.

This path should be freed with `TreePath::free`.
## `iter`
the `TreeIter`-struct

# Returns

a newly-created `TreePath`-struct
<!-- trait TreeModelExt::fn get_string_from_iter -->
Generates a string representation of the iter.

This string is a “:” separated list of numbers.
For example, “4:10:0:3” would be an acceptable
return value for this string.
## `iter`
a `TreeIter`-struct

# Returns

a newly-allocated string.
 Must be freed with `g_free`.
<!-- trait TreeModelExt::fn get_valist -->
See `TreeModel::get`, this version takes a va_list
for language bindings to use.
## `iter`
a row in `self`
## `var_args`
va_list of column/return location pairs
<!-- trait TreeModelExt::fn get_value -->
Initializes and sets `value` to that at `column`.

When done with `value`, `gobject::Value::unset` needs to be called
to free any allocated memory.
## `iter`
the `TreeIter`-struct
## `column`
the column to lookup the value at
## `value`
an empty `gobject::Value` to set
<!-- trait TreeModelExt::fn iter_children -->
Sets `iter` to point to the first child of `parent`.

If `parent` has no children, `false` is returned and `iter` is
set to be invalid. `parent` will remain a valid node after this
function has been called.

If `parent` is `None` returns the first node, equivalent to
`gtk_tree_model_get_iter_first (tree_model, iter);`
## `iter`
the new `TreeIter`-struct to be set to the child
## `parent`
the `TreeIter`-struct, or `None`

# Returns

`true`, if `iter` has been set to the first child
<!-- trait TreeModelExt::fn iter_has_child -->
Returns `true` if `iter` has children, `false` otherwise.
## `iter`
the `TreeIter`-struct to test for children

# Returns

`true` if `iter` has children
<!-- trait TreeModelExt::fn iter_n_children -->
Returns the number of children that `iter` has.

As a special case, if `iter` is `None`, then the number
of toplevel nodes is returned.
## `iter`
the `TreeIter`-struct, or `None`

# Returns

the number of children of `iter`
<!-- trait TreeModelExt::fn iter_next -->
Sets `iter` to point to the node following it at the current level.

If there is no next `iter`, `false` is returned and `iter` is set
to be invalid.
## `iter`
the `TreeIter`-struct

# Returns

`true` if `iter` has been changed to the next node
<!-- trait TreeModelExt::fn iter_nth_child -->
Sets `iter` to be the child of `parent`, using the given index.

The first index is 0. If `n` is too big, or `parent` has no children,
`iter` is set to an invalid iterator and `false` is returned. `parent`
will remain a valid node after this function has been called. As a
special case, if `parent` is `None`, then the `n`-th root node
is set.
## `iter`
the `TreeIter`-struct to set to the nth child
## `parent`
the `TreeIter`-struct to get the child from, or `None`.
## `n`
the index of the desired child

# Returns

`true`, if `parent` has an `n`-th child
<!-- trait TreeModelExt::fn iter_parent -->
Sets `iter` to be the parent of `child`.

If `child` is at the toplevel, and doesn’t have a parent, then
`iter` is set to an invalid iterator and `false` is returned.
`child` will remain a valid node after this function has been
called.

`iter` will be initialized before the lookup is performed, so `child`
and `iter` cannot point to the same memory location.
## `iter`
the new `TreeIter`-struct to set to the parent
## `child`
the `TreeIter`-struct

# Returns

`true`, if `iter` is set to the parent of `child`
<!-- trait TreeModelExt::fn iter_previous -->
Sets `iter` to point to the previous node at the current level.

If there is no previous `iter`, `false` is returned and `iter` is
set to be invalid.
## `iter`
the `TreeIter`-struct

# Returns

`true` if `iter` has been changed to the previous node
<!-- trait TreeModelExt::fn ref_node -->
Lets the tree ref the node.

This is an optional method for models to implement.
To be more specific, models may ignore this call as it exists
primarily for performance reasons.

This function is primarily meant as a way for views to let
caching models know when nodes are being displayed (and hence,
whether or not to cache that node). Being displayed means a node
is in an expanded branch, regardless of whether the node is currently
visible in the viewport. For example, a file-system based model
would not want to keep the entire file-hierarchy in memory,
just the sections that are currently being displayed by
every current view.

A model should be expected to be able to get an iter independent
of its reffed state.
## `iter`
the `TreeIter`-struct
<!-- trait TreeModelExt::fn row_changed -->
Emits the `TreeModel::row-changed` signal on `self`.
## `path`
a `TreePath`-struct pointing to the changed row
## `iter`
a valid `TreeIter`-struct pointing to the changed row
<!-- trait TreeModelExt::fn row_deleted -->
Emits the `TreeModel::row-deleted` signal on `self`.

This should be called by models after a row has been removed.
The location pointed to by `path` should be the location that
the row previously was at. It may not be a valid location anymore.

Nodes that are deleted are not unreffed, this means that any
outstanding references on the deleted node should not be released.
## `path`
a `TreePath`-struct pointing to the previous location of
 the deleted row
<!-- trait TreeModelExt::fn row_has_child_toggled -->
Emits the `TreeModel::row-has-child-toggled` signal on
`self`. This should be called by models after the child
state of a node changes.
## `path`
a `TreePath`-struct pointing to the changed row
## `iter`
a valid `TreeIter`-struct pointing to the changed row
<!-- trait TreeModelExt::fn row_inserted -->
Emits the `TreeModel::row-inserted` signal on `self`.
## `path`
a `TreePath`-struct pointing to the inserted row
## `iter`
a valid `TreeIter`-struct pointing to the inserted row
<!-- trait TreeModelExt::fn rows_reordered -->
Emits the `TreeModel::rows-reordered` signal on `self`.

This should be called by models when their rows have been
reordered.
## `path`
a `TreePath`-struct pointing to the tree node whose children
 have been reordered
## `iter`
a valid `TreeIter`-struct pointing to the node whose children
 have been reordered, or `None` if the depth of `path` is 0
## `new_order`
an array of integers mapping the current position of
 each child to its old position before the re-ordering,
 i.e. `new_order``[newpos] = oldpos`
<!-- trait TreeModelExt::fn rows_reordered_with_length -->
Emits the `TreeModel::rows-reordered` signal on `self`.

This should be called by models when their rows have been
reordered.
## `path`
a `TreePath`-struct pointing to the tree node whose children
 have been reordered
## `iter`
a valid `TreeIter`-struct pointing to the node
 whose children have been reordered, or `None` if the depth
 of `path` is 0
## `new_order`
an array of integers
 mapping the current position of each child to its old
 position before the re-ordering,
 i.e. `new_order``[newpos] = oldpos`
## `length`
length of `new_order` array
<!-- trait TreeModelExt::fn unref_node -->
Lets the tree unref the node.

This is an optional method for models to implement.
To be more specific, models may ignore this call as it exists
primarily for performance reasons. For more information on what
this means, see `TreeModel::ref_node`.

Please note that nodes that are deleted are not unreffed.
## `iter`
the `TreeIter`-struct
<!-- trait TreeModelExt::fn connect_row_changed -->
This signal is emitted when a row in the model has changed.
## `path`
a `TreePath`-struct identifying the changed row
## `iter`
a valid `TreeIter`-struct pointing to the changed row
<!-- trait TreeModelExt::fn connect_row_deleted -->
This signal is emitted when a row has been deleted.

Note that no iterator is passed to the signal handler,
since the row is already deleted.

This should be called by models after a row has been removed.
The location pointed to by `path` should be the location that
the row previously was at. It may not be a valid location anymore.
## `path`
a `TreePath`-struct identifying the row
<!-- trait TreeModelExt::fn connect_row_has_child_toggled -->
This signal is emitted when a row has gotten the first child
row or lost its last child row.
## `path`
a `TreePath`-struct identifying the row
## `iter`
a valid `TreeIter`-struct pointing to the row
<!-- trait TreeModelExt::fn connect_row_inserted -->
This signal is emitted when a new row has been inserted in
the model.

Note that the row may still be empty at this point, since
it is a common pattern to first insert an empty row, and
then fill it with the desired values.
## `path`
a `TreePath`-struct identifying the new row
## `iter`
a valid `TreeIter`-struct pointing to the new row
<!-- trait TreeModelExt::fn connect_rows_reordered -->
This signal is emitted when the children of a node in the
`TreeModel` have been reordered.

Note that this signal is not emitted
when rows are reordered by DND, since this is implemented
by removing and then reinserting the row.
## `path`
a `TreePath`-struct identifying the tree node whose children
 have been reordered
## `iter`
a valid `TreeIter`-struct pointing to the node whose children
 have been reordered, or `None` if the depth of `path` is 0
## `new_order`
an array of integers mapping the current position
 of each child to its old position before the re-ordering,
 i.e. `new_order``[newpos] = oldpos`
<!-- struct TreeModelFilter -->
A `TreeModelFilter` is a tree model which wraps another tree model,
and can do the following things:

- Filter specific rows, based on data from a “visible column”, a column
 storing booleans indicating whether the row should be filtered or not,
 or based on the return value of a “visible function”, which gets a
 model, iter and user_data and returns a boolean indicating whether the
 row should be filtered or not.

- Modify the “appearance” of the model, using a modify function.
 This is extremely powerful and allows for just changing some
 values and also for creating a completely different model based
 on the given child model.

- Set a different root node, also known as a “virtual root”. You can pass
 in a `TreePath` indicating the root node for the filter at construction
 time.

The basic API is similar to `TreeModelSort`. For an example on its usage,
see the section on `TreeModelSort`.

When using `TreeModelFilter`, it is important to realize that
`TreeModelFilter` maintains an internal cache of all nodes which are
visible in its clients. The cache is likely to be a subtree of the tree
exposed by the child model. `TreeModelFilter` will not cache the entire
child model when unnecessary to not compromise the caching mechanism
that is exposed by the reference counting scheme. If the child model
implements reference counting, unnecessary signals may not be emitted
because of reference counting rule 3, see the `TreeModel`
documentation. (Note that e.g. `TreeStore` does not implement
reference counting and will always emit all signals, even when
the receiving node is not visible).

Because of this, limitations for possible visible functions do apply.
In general, visible functions should only use data or properties from
the node for which the visibility state must be determined, its siblings
or its parents. Usually, having a dependency on the state of any child
node is not possible, unless references are taken on these explicitly.
When no such reference exists, no signals may be received for these child
nodes (see reference couting rule number 3 in the `TreeModel` section).

Determining the visibility state of a given node based on the state
of its child nodes is a frequently occurring use case. Therefore,
`TreeModelFilter` explicitly supports this. For example, when a node
does not have any children, you might not want the node to be visible.
As soon as the first row is added to the node’s child level (or the
last row removed), the node’s visibility should be updated.

This introduces a dependency from the node on its child nodes. In order
to accommodate this, `TreeModelFilter` must make sure the necessary
signals are received from the child model. This is achieved by building,
for all nodes which are exposed as visible nodes to `TreeModelFilter`'s
clients, the child level (if any) and take a reference on the first node
in this level. Furthermore, for every row-inserted, row-changed or
row-deleted signal (also these which were not handled because the node
was not cached), `TreeModelFilter` will check if the visibility state
of any parent node has changed.

Beware, however, that this explicit support is limited to these two
cases. For example, if you want a node to be visible only if two nodes
in a child’s child level (2 levels deeper) are visible, you are on your
own. In this case, either rely on `TreeStore` to emit all signals
because it does not implement reference counting, or for models that
do implement reference counting, obtain references on these child levels
yourself.

# Implements

[`TreeModelFilterExt`](trait.TreeModelFilterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`TreeDragSourceExt`](trait.TreeDragSourceExt.html), [`TreeModelExt`](trait.TreeModelExt.html)
<!-- trait TreeModelFilterExt -->
Trait containing all `TreeModelFilter` methods.

# Implementors

[`TreeModelFilter`](struct.TreeModelFilter.html)
<!-- trait TreeModelFilterExt::fn clear_cache -->
This function should almost never be called. It clears the `self`
of any cached iterators that haven’t been reffed with
`TreeModel::ref_node`. This might be useful if the child model
being filtered is static (and doesn’t change often) and there has been
a lot of unreffed access to nodes. As a side effect of this function,
all unreffed iters will be invalid.
<!-- trait TreeModelFilterExt::fn convert_child_iter_to_iter -->
Sets `filter_iter` to point to the row in `self` that corresponds to the
row pointed at by `child_iter`. If `filter_iter` was not set, `false` is
returned.
## `filter_iter`
An uninitialized `TreeIter`.
## `child_iter`
A valid `TreeIter` pointing to a row on the child model.

# Returns

`true`, if `filter_iter` was set, i.e. if `child_iter` is a
valid iterator pointing to a visible row in child model.
<!-- trait TreeModelFilterExt::fn convert_child_path_to_path -->
Converts `child_path` to a path relative to `self`. That is, `child_path`
points to a path in the child model. The rerturned path will point to the
same row in the filtered model. If `child_path` isn’t a valid path on the
child model or points to a row which is not visible in `self`, then `None`
is returned.
## `child_path`
A `TreePath` to convert.

# Returns

A newly allocated `TreePath`, or `None`.
<!-- trait TreeModelFilterExt::fn convert_iter_to_child_iter -->
Sets `child_iter` to point to the row pointed to by `filter_iter`.
## `child_iter`
An uninitialized `TreeIter`.
## `filter_iter`
A valid `TreeIter` pointing to a row on `self`.
<!-- trait TreeModelFilterExt::fn convert_path_to_child_path -->
Converts `filter_path` to a path on the child model of `self`. That is,
`filter_path` points to a location in `self`. The returned path will
point to the same location in the model not being filtered. If `filter_path`
does not point to a location in the child model, `None` is returned.
## `filter_path`
A `TreePath` to convert.

# Returns

A newly allocated `TreePath`, or `None`.
<!-- trait TreeModelFilterExt::fn get_model -->
Returns a pointer to the child model of `self`.

# Returns

A pointer to a `TreeModel`.
<!-- trait TreeModelFilterExt::fn refilter -->
Emits ::row_changed for each row in the child model, which causes
the filter to re-evaluate whether a row is visible or not.
<!-- trait TreeModelFilterExt::fn set_modify_func -->
With the `n_columns` and `types` parameters, you give an array of column
types for this model (which will be exposed to the parent model/view).
The `func`, `data` and `destroy` parameters are for specifying the modify
function. The modify function will get called for each
data access, the goal of the modify function is to return the data which
should be displayed at the location specified using the parameters of the
modify function.

Note that `TreeModelFilterExt::set_modify_func`
can only be called once for a given filter model.
## `n_columns`
The number of columns in the filter model.
## `types`
The `GTypes` of the columns.
## `func`
A ``GtkTreeModelFilterModifyFunc``
## `data`
User data to pass to the modify function, or `None`.
## `destroy`
Destroy notifier of `data`, or `None`.
<!-- trait TreeModelFilterExt::fn set_visible_column -->
Sets `column` of the child_model to be the column where `self` should
look for visibility information. `columns` should be a column of type
`G_TYPE_BOOLEAN`, where `true` means that a row is visible, and `false`
if not.

Note that `TreeModelFilterExt::set_visible_func` or
`TreeModelFilterExt::set_visible_column` can only be called
once for a given filter model.
## `column`
A `gint` which is the column containing the visible information
<!-- trait TreeModelFilterExt::fn set_visible_func -->
Sets the visible function used when filtering the `self` to be `func`.
The function should return `true` if the given row should be visible and
`false` otherwise.

If the condition calculated by the function changes over time (e.g.
because it depends on some global parameters), you must call
`TreeModelFilterExt::refilter` to keep the visibility information
of the model up-to-date.

Note that `func` is called whenever a row is inserted, when it may still
be empty. The visible function should therefore take special care of empty
rows, like in the example below.


```C
static gboolean
visible_func (GtkTreeModel *model,
              GtkTreeIter  *iter,
              gpointer      data)
{
  // Visible if row is non-empty and first column is “HI”
  gchar *str;
  gboolean visible = FALSE;

  gtk_tree_model_get (model, iter, 0, &str, -1);
  if (str && strcmp (str, "HI") == 0)
    visible = TRUE;
  g_free (str);

  return visible;
}
```

Note that `TreeModelFilterExt::set_visible_func` or
`TreeModelFilterExt::set_visible_column` can only be called
once for a given filter model.
## `func`
A ``GtkTreeModelFilterVisibleFunc``, the visible function
## `data`
User data to pass to the visible function, or `None`
## `destroy`
Destroy notifier of `data`, or `None`
<!-- struct TreeModelFlags -->
These flags indicate various properties of a `TreeModel`.

They are returned by `TreeModel::get_flags`, and must be
static for the lifetime of the object. A more complete description
of `TreeModelFlags::ItersPersist` can be found in the overview of
this section.
<!-- struct TreeModelFlags::const ITERS_PERSIST -->
iterators survive all signals
 emitted by the tree
<!-- struct TreeModelFlags::const LIST_ONLY -->
the model is a list only, and never
 has children
<!-- struct TreeModelSort -->
The `TreeModelSort` is a model which implements the `TreeSortable`
interface. It does not hold any data itself, but rather is created with
a child model and proxies its data. It has identical column types to
this child model, and the changes in the child are propagated. The
primary purpose of this model is to provide a way to sort a different
model without modifying it. Note that the sort function used by
`TreeModelSort` is not guaranteed to be stable.

The use of this is best demonstrated through an example. In the
following sample code we create two `TreeView` widgets each with a
view of the same data. As the model is wrapped here by a
`TreeModelSort`, the two ``GtkTreeViews`` can each sort their
view of the data without affecting the other. By contrast, if we
simply put the same model in each widget, then sorting the first would
sort the second.

## Using a `TreeModelSort`


```C
{
  GtkTreeView *tree_view1;
  GtkTreeView *tree_view2;
  GtkTreeModel *sort_model1;
  GtkTreeModel *sort_model2;
  GtkTreeModel *child_model;

  // get the child model
  child_model = get_my_model ();

  // Create the first tree
  sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
  tree_view1 = gtk_tree_view_new_with_model (sort_model1);

  // Create the second tree
  sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
  tree_view2 = gtk_tree_view_new_with_model (sort_model2);

  // Now we can sort the two models independently
  gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
                                        COLUMN_1, GTK_SORT_ASCENDING);
  gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
                                        COLUMN_1, GTK_SORT_DESCENDING);
}
```

To demonstrate how to access the underlying child model from the sort
model, the next example will be a callback for the `TreeSelection`
`TreeSelection::changed` signal. In this callback, we get a string
from COLUMN_1 of the model. We then modify the string, find the same
selected row on the child model, and change the row there.

## Accessing the child model of in a selection changed callback


```C
void
selection_changed (GtkTreeSelection *selection, gpointer data)
{
  GtkTreeModel *sort_model = NULL;
  GtkTreeModel *child_model;
  GtkTreeIter sort_iter;
  GtkTreeIter child_iter;
  char *some_data = NULL;
  char *modified_data;

  // Get the current selected row and the model.
  if (! gtk_tree_selection_get_selected (selection,
                                         &sort_model,
                                         &sort_iter))
    return;

  // Look up the current value on the selected row and get
  // a new value to change it to.
  gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
                      COLUMN_1, &some_data,
                      -1);

  modified_data = change_the_data (some_data);
  g_free (some_data);

  // Get an iterator on the child model, instead of the sort model.
  gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
                                                  &child_iter,
                                                  &sort_iter);

  // Get the child model and change the value of the row. In this
  // example, the child model is a GtkListStore. It could be any other
  // type of model, though.
  child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
  gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
                      COLUMN_1, &modified_data,
                      -1);
  g_free (modified_data);
}
```

# Implements

[`TreeModelSortExt`](trait.TreeModelSortExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`TreeDragSourceExt`](trait.TreeDragSourceExt.html), [`TreeModelExt`](trait.TreeModelExt.html), [`TreeSortableExt`](trait.TreeSortableExt.html), [`TreeSortableExtManual`](prelude/trait.TreeSortableExtManual.html)
<!-- trait TreeModelSortExt -->
Trait containing all `TreeModelSort` methods.

# Implementors

[`TreeModelSort`](struct.TreeModelSort.html)
<!-- impl TreeModelSort::fn new -->
Creates a new `TreeModelSort`, with `child_model` as the child model.
## `child_model`
A `TreeModel`

# Returns

A new `TreeModelSort`.
<!-- trait TreeModelSortExt::fn clear_cache -->
This function should almost never be called. It clears the `self`
of any cached iterators that haven’t been reffed with
`TreeModel::ref_node`. This might be useful if the child model being
sorted is static (and doesn’t change often) and there has been a lot of
unreffed access to nodes. As a side effect of this function, all unreffed
iters will be invalid.
<!-- trait TreeModelSortExt::fn convert_child_iter_to_iter -->
Sets `sort_iter` to point to the row in `self` that corresponds to
the row pointed at by `child_iter`. If `sort_iter` was not set, `false`
is returned. Note: a boolean is only returned since 2.14.
## `sort_iter`
An uninitialized `TreeIter`.
## `child_iter`
A valid `TreeIter` pointing to a row on the child model

# Returns

`true`, if `sort_iter` was set, i.e. if `sort_iter` is a
valid iterator pointer to a visible row in the child model.
<!-- trait TreeModelSortExt::fn convert_child_path_to_path -->
Converts `child_path` to a path relative to `self`. That is,
`child_path` points to a path in the child model. The returned path will
point to the same row in the sorted model. If `child_path` isn’t a valid
path on the child model, then `None` is returned.
## `child_path`
A `TreePath` to convert

# Returns

A newly allocated `TreePath`, or `None`
<!-- trait TreeModelSortExt::fn convert_iter_to_child_iter -->
Sets `child_iter` to point to the row pointed to by `sorted_iter`.
## `child_iter`
An uninitialized `TreeIter`
## `sorted_iter`
A valid `TreeIter` pointing to a row on `self`.
<!-- trait TreeModelSortExt::fn convert_path_to_child_path -->
Converts `sorted_path` to a path on the child model of `self`.
That is, `sorted_path` points to a location in `self`. The
returned path will point to the same location in the model not being
sorted. If `sorted_path` does not point to a location in the child model,
`None` is returned.
## `sorted_path`
A `TreePath` to convert

# Returns

A newly allocated `TreePath`, or `None`
<!-- trait TreeModelSortExt::fn get_model -->
Returns the model the `TreeModelSort` is sorting.

# Returns

the "child model" being sorted
<!-- trait TreeModelSortExt::fn iter_is_valid -->
> This function is slow. Only use it for debugging and/or testing
> purposes.

Checks if the given iter is a valid iter for this `TreeModelSort`.
## `iter`
A `TreeIter`.

# Returns

`true` if the iter is valid, `false` if the iter is invalid.
<!-- trait TreeModelSortExt::fn reset_default_sort_func -->
This resets the default sort function to be in the “unsorted” state. That
is, it is in the same order as the child model. It will re-sort the model
to be in the same order as the child model only if the `TreeModelSort`
is in “unsorted” state.
<!-- struct TreePath -->
<!-- impl TreePath::fn new -->
Creates a new `TreePath`-struct.
This refers to a row.

# Returns

A newly created `TreePath`-struct.
<!-- impl TreePath::fn new_first -->
Creates a new `TreePath`-struct.

The string representation of this path is “0”.

# Returns

A new `TreePath`-struct
<!-- impl TreePath::fn new_from_indices -->
Creates a new path with `first_index` and `varargs` as indices.
## `first_index`
first integer

# Returns

A newly created `TreePath`-struct
<!-- impl TreePath::fn new_from_indicesv -->
Creates a new path with the given `indices` array of `length`.
## `indices`
array of indices
## `length`
length of `indices` array

# Returns

A newly created `TreePath`-struct
<!-- impl TreePath::fn new_from_string -->
Creates a new `TreePath`-struct initialized to `path`.

`path` is expected to be a colon separated list of numbers.
For example, the string “10:4:0” would create a path of depth
3 pointing to the 11th child of the root node, the 5th
child of that 11th child, and the 1st child of that 5th child.
If an invalid path string is passed in, `None` is returned.
## `path`
The string representation of a path

# Returns

A newly-created `TreePath`-struct, or `None`
<!-- impl TreePath::fn append_index -->
Appends a new index to a path.

As a result, the depth of the path is increased.
## `index_`
the index
<!-- impl TreePath::fn compare -->
Compares two paths.

If `self` appears before `b` in a tree, then -1 is returned.
If `b` appears before `self`, then 1 is returned.
If the two nodes are equal, then 0 is returned.
## `b`
a `TreePath`-struct to compare with

# Returns

the relative positions of `self` and `b`
<!-- impl TreePath::fn copy -->
Creates a new `TreePath`-struct as a copy of `self`.

# Returns

a new `TreePath`-struct
<!-- impl TreePath::fn down -->
Moves `self` to point to the first child of the current path.
<!-- impl TreePath::fn free -->
Frees `self`. If `self` is `None`, it simply returns.
<!-- impl TreePath::fn get_depth -->
Returns the current depth of `self`.

# Returns

The depth of `self`
<!-- impl TreePath::fn get_indices -->
Returns the current indices of `self`.

This is an array of integers, each representing a node in a tree.
This value should not be freed.

The length of the array can be obtained with `TreePath::get_depth`.

# Returns

The current indices, or `None`
<!-- impl TreePath::fn get_indices_with_depth -->
Returns the current indices of `self`.

This is an array of integers, each representing a node in a tree.
It also returns the number of elements in the array.
The array should not be freed.
## `depth`
return location for number of elements
 returned in the integer array, or `None`

# Returns

The current
 indices, or `None`
<!-- impl TreePath::fn is_ancestor -->
Returns `true` if `descendant` is a descendant of `self`.
## `descendant`
another `TreePath`-struct

# Returns

`true` if `descendant` is contained inside `self`
<!-- impl TreePath::fn is_descendant -->
Returns `true` if `self` is a descendant of `ancestor`.
## `ancestor`
another `TreePath`-struct

# Returns

`true` if `ancestor` contains `self` somewhere below it
<!-- impl TreePath::fn next -->
Moves the `self` to point to the next node at the current depth.
<!-- impl TreePath::fn prepend_index -->
Prepends a new index to a path.

As a result, the depth of the path is increased.
## `index_`
the index
<!-- impl TreePath::fn prev -->
Moves the `self` to point to the previous node at the
current depth, if it exists.

# Returns

`true` if `self` has a previous node, and
 the move was made
<!-- impl TreePath::fn to_string -->
Generates a string representation of the path.

This string is a “:” separated list of numbers.
For example, “4:10:0:3” would be an acceptable
return value for this string.

# Returns

A newly-allocated string.
 Must be freed with `g_free`.
<!-- impl TreePath::fn up -->
Moves the `self` to point to its parent node, if it has a parent.

# Returns

`true` if `self` has a parent, and the move was made
<!-- struct TreeRowReference -->
A `TreeRowReference` tracks model changes so that it always refers to the
same row (a `TreePath` refers to a position, not a fixed row). Create a
new `TreeRowReference` with `TreeRowReference::new`.
<!-- impl TreeRowReference::fn new -->
Creates a row reference based on `path`.

This reference will keep pointing to the node pointed to
by `path`, so long as it exists. Any changes that occur on `model` are
propagated, and the path is updated appropriately. If
`path` isn’t a valid path in `model`, then `None` is returned.
## `model`
a `TreeModel`
## `path`
a valid `TreePath`-struct to monitor

# Returns

a newly allocated `TreeRowReference`, or `None`
<!-- impl TreeRowReference::fn new_proxy -->
You do not need to use this function.

Creates a row reference based on `path`.

This reference will keep pointing to the node pointed to
by `path`, so long as it exists. If `path` isn’t a valid
path in `model`, then `None` is returned. However, unlike
references created with `TreeRowReference::new`, it
does not listen to the model for changes. The creator of
the row reference must do this explicitly using
`TreeRowReference::inserted`, `TreeRowReference::deleted`,
`TreeRowReference::reordered`.

These functions must be called exactly once per proxy when the
corresponding signal on the model is emitted. This single call
updates all row references for that proxy. Since built-in GTK+
objects like `TreeView` already use this mechanism internally,
using them as the proxy object will produce unpredictable results.
Further more, passing the same object as `model` and `proxy`
doesn’t work for reasons of internal implementation.

This type of row reference is primarily meant by structures that
need to carefully monitor exactly when a row reference updates
itself, and is not generally needed by most applications.
## `proxy`
a proxy `gobject::Object`
## `model`
a `TreeModel`
## `path`
a valid `TreePath`-struct to monitor

# Returns

a newly allocated `TreeRowReference`, or `None`
<!-- impl TreeRowReference::fn copy -->
Copies a `TreeRowReference`.

# Returns

a copy of `self`
<!-- impl TreeRowReference::fn free -->
Free’s `self`. `self` may be `None`
<!-- impl TreeRowReference::fn get_model -->
Returns the model that the row reference is monitoring.

# Returns

the model
<!-- impl TreeRowReference::fn get_path -->
Returns a path that the row reference currently points to,
or `None` if the path pointed to is no longer valid.

# Returns

a current path, or `None`
<!-- impl TreeRowReference::fn valid -->
Returns `true` if the `self` is non-`None` and refers to
a current valid path.

# Returns

`true` if `self` points to a valid path
<!-- impl TreeRowReference::fn deleted -->
Lets a set of row reference created by
`TreeRowReference::new_proxy` know that the
model emitted the `TreeModel::row-deleted` signal.
## `proxy`
a `gobject::Object`
## `path`
the path position that was deleted
<!-- impl TreeRowReference::fn inserted -->
Lets a set of row reference created by
`TreeRowReference::new_proxy` know that the
model emitted the `TreeModel::row-inserted` signal.
## `proxy`
a `gobject::Object`
## `path`
the row position that was inserted
<!-- impl TreeRowReference::fn reordered -->
Lets a set of row reference created by
`TreeRowReference::new_proxy` know that the
model emitted the `TreeModel::rows-reordered` signal.
## `proxy`
a `gobject::Object`
## `path`
the parent path of the reordered signal
## `iter`
the iter pointing to the parent of the reordered
## `new_order`
the new order of rows
<!-- struct TreeSelection -->
The `TreeSelection` object is a helper object to manage the selection
for a `TreeView` widget. The `TreeSelection` object is
automatically created when a new `TreeView` widget is created, and
cannot exist independently of this widget. The primary reason the
`TreeSelection` objects exists is for cleanliness of code and API.
That is, there is no conceptual reason all these functions could not be
methods on the `TreeView` widget instead of a separate function.

The `TreeSelection` object is gotten from a `TreeView` by calling
`TreeViewExt::get_selection`. It can be manipulated to check the
selection status of the tree, as well as select and deselect individual
rows. Selection is done completely view side. As a result, multiple
views of the same model can have completely different selections.
Additionally, you cannot change the selection of a row on the model that
is not currently displayed by the view without expanding its parents
first.

One of the important things to remember when monitoring the selection of
a view is that the `TreeSelection::changed` signal is mostly a hint.
That is, it may only emit one signal when a range of rows is selected.
Additionally, it may on occasion emit a `TreeSelection::changed` signal
when nothing has happened (mostly as a result of programmers calling
select_row on an already selected row).

# Implements

[`TreeSelectionExt`](trait.TreeSelectionExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait TreeSelectionExt -->
Trait containing all `TreeSelection` methods.

# Implementors

[`TreeSelection`](struct.TreeSelection.html)
<!-- trait TreeSelectionExt::fn count_selected_rows -->
Returns the number of rows that have been selected in `tree`.

# Returns

The number of rows selected.
<!-- trait TreeSelectionExt::fn get_mode -->
Gets the selection mode for `self`. See
`TreeSelectionExt::set_mode`.

# Returns

the current selection mode
<!-- trait TreeSelectionExt::fn get_select_function -->
Returns the current selection function.

# Returns

The function.
<!-- trait TreeSelectionExt::fn get_selected -->
Sets `iter` to the currently selected node if `self` is set to
`SelectionMode::Single` or `SelectionMode::Browse`. `iter` may be NULL if you
just want to test if `self` has any selected nodes. `model` is filled
with the current model as a convenience. This function will not work if you
use `self` is `SelectionMode::Multiple`.
## `model`
A pointer to set to the `TreeModel`, or NULL.
## `iter`
The `TreeIter`, or NULL.

# Returns

TRUE, if there is a selected node.
<!-- trait TreeSelectionExt::fn get_selected_rows -->
Creates a list of path of all selected rows. Additionally, if you are
planning on modifying the model after calling this function, you may
want to convert the returned list into a list of ``GtkTreeRowReferences``.
To do this, you can use `TreeRowReference::new`.

To free the return value, use:

```C
g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free);
```
## `model`
A pointer to set to the `TreeModel`, or `None`.

# Returns

A `glib::List` containing a `TreePath` for each selected row.
<!-- trait TreeSelectionExt::fn get_tree_view -->
Returns the tree view associated with `self`.

# Returns

A `TreeView`
<!-- trait TreeSelectionExt::fn get_user_data -->
Returns the user data for the selection function.

# Returns

The user data.
<!-- trait TreeSelectionExt::fn iter_is_selected -->
Returns `true` if the row at `iter` is currently selected.
## `iter`
A valid `TreeIter`

# Returns

`true`, if `iter` is selected
<!-- trait TreeSelectionExt::fn path_is_selected -->
Returns `true` if the row pointed to by `path` is currently selected. If `path`
does not point to a valid location, `false` is returned
## `path`
A `TreePath` to check selection on.

# Returns

`true` if `path` is selected.
<!-- trait TreeSelectionExt::fn select_all -->
Selects all the nodes. `self` must be set to `SelectionMode::Multiple`
mode.
<!-- trait TreeSelectionExt::fn select_iter -->
Selects the specified iterator.
## `iter`
The `TreeIter` to be selected.
<!-- trait TreeSelectionExt::fn select_path -->
Select the row at `path`.
## `path`
The `TreePath` to be selected.
<!-- trait TreeSelectionExt::fn select_range -->
Selects a range of nodes, determined by `start_path` and `end_path` inclusive.
`self` must be set to `SelectionMode::Multiple` mode.
## `start_path`
The initial node of the range.
## `end_path`
The final node of the range.
<!-- trait TreeSelectionExt::fn selected_foreach -->
Calls a function for each selected node. Note that you cannot modify
the tree or selection from within this function. As a result,
`TreeSelectionExt::get_selected_rows` might be more useful.
## `func`
The function to call for each selected node.
## `data`
user data to pass to the function.
<!-- trait TreeSelectionExt::fn set_mode -->
Sets the selection mode of the `self`. If the previous type was
`SelectionMode::Multiple`, then the anchor is kept selected, if it was
previously selected.
## `type_`
The selection mode
<!-- trait TreeSelectionExt::fn set_select_function -->
Sets the selection function.

If set, this function is called before any node is selected or unselected,
giving some control over which nodes are selected. The select function
should return `true` if the state of the node may be toggled, and `false`
if the state of the node should be left unchanged.
## `func`
The selection function. May be `None`
## `data`
The selection function’s data. May be `None`
## `destroy`
The destroy function for user data. May be `None`
<!-- trait TreeSelectionExt::fn unselect_all -->
Unselects all the nodes.
<!-- trait TreeSelectionExt::fn unselect_iter -->
Unselects the specified iterator.
## `iter`
The `TreeIter` to be unselected.
<!-- trait TreeSelectionExt::fn unselect_path -->
Unselects the row at `path`.
## `path`
The `TreePath` to be unselected.
<!-- trait TreeSelectionExt::fn unselect_range -->
Unselects a range of nodes, determined by `start_path` and `end_path`
inclusive.
## `start_path`
The initial node of the range.
## `end_path`
The initial node of the range.
<!-- trait TreeSelectionExt::fn connect_changed -->
Emitted whenever the selection has (possibly) changed. Please note that
this signal is mostly a hint. It may only be emitted once when a range
of rows are selected, and it may occasionally be emitted when nothing
has happened.
<!-- trait TreeSelectionExt::fn get_property_mode -->
Selection mode.
See `TreeSelectionExt::set_mode` for more information on this property.
<!-- trait TreeSelectionExt::fn set_property_mode -->
Selection mode.
See `TreeSelectionExt::set_mode` for more information on this property.
<!-- struct TreeSortable -->
`TreeSortable` is an interface to be implemented by tree models which
support sorting. The `TreeView` uses the methods provided by this interface
to sort the model.

# Implements

[`TreeSortableExt`](trait.TreeSortableExt.html), [`TreeModelExt`](trait.TreeModelExt.html), [`TreeSortableExtManual`](prelude/trait.TreeSortableExtManual.html)
<!-- trait TreeSortableExt -->
Trait containing all `TreeSortable` methods.

# Implementors

[`ListStore`](struct.ListStore.html), [`TreeModelSort`](struct.TreeModelSort.html), [`TreeSortable`](struct.TreeSortable.html), [`TreeStore`](struct.TreeStore.html)
<!-- trait TreeSortableExtManual::fn get_sort_column_id -->
Fills in `sort_column_id` and `order` with the current sort column and the
order. It returns `true` unless the `sort_column_id` is
`GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID` or
`GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID`.
## `sort_column_id`
The sort column id to be filled in
## `order`
The `SortType` to be filled in

# Returns

`true` if the sort column is not one of the special sort
 column ids.
<!-- trait TreeSortableExt::fn has_default_sort_func -->
Returns `true` if the model has a default sort function. This is used
primarily by `GtkTreeViewColumns` in order to determine if a model can
go back to the default state, or not.

# Returns

`true`, if the model has a default sort function
<!-- trait TreeSortableExtManual::fn set_default_sort_func -->
Sets the default comparison function used when sorting to be `sort_func`.
If the current sort column id of `self` is
`GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID`, then the model will sort using
this function.

If `sort_func` is `None`, then there will be no default comparison function.
This means that once the model has been sorted, it can’t go back to the
default state. In this case, when the current sort column id of `self`
is `GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID`, the model will be unsorted.
## `sort_func`
The comparison function
## `user_data`
User data to pass to `sort_func`, or `None`
## `destroy`
Destroy notifier of `user_data`, or `None`
<!-- trait TreeSortableExtManual::fn set_sort_column_id -->
Sets the current sort column to be `sort_column_id`. The `self` will
resort itself to reflect this change, after emitting a
`TreeSortable::sort-column-changed` signal. `sort_column_id` may either be
a regular column id, or one of the following special values:

- `GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID`: the default sort function
 will be used, if it is set

- `GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID`: no sorting will occur
## `sort_column_id`
the sort column id to set
## `order`
The sort order of the column
<!-- trait TreeSortableExtManual::fn set_sort_func -->
Sets the comparison function used when sorting to be `sort_func`. If the
current sort column id of `self` is the same as `sort_column_id`, then
the model will sort using this function.
## `sort_column_id`
the sort column id to set the function for
## `sort_func`
The comparison function
## `user_data`
User data to pass to `sort_func`, or `None`
## `destroy`
Destroy notifier of `user_data`, or `None`
<!-- trait TreeSortableExt::fn sort_column_changed -->
Emits a `TreeSortable::sort-column-changed` signal on `self`.
<!-- trait TreeSortableExt::fn connect_sort_column_changed -->
The ::sort-column-changed signal is emitted when the sort column
or sort order of `sortable` is changed. The signal is emitted before
the contents of `sortable` are resorted.
<!-- struct TreeStore -->
The `TreeStore` object is a list model for use with a `TreeView`
widget. It implements the `TreeModel` interface, and consequentially,
can use all of the methods available there. It also implements the
`TreeSortable` interface so it can be sorted by the view. Finally,
it also implements the tree
[drag and drop][gtk3-`TreeView`-drag-and-drop]
interfaces.

# `TreeStore` as `Buildable`

The `TreeStore` implementation of the `Buildable` interface allows
to specify the model columns with a `<columns>` element that may contain
multiple `<column>` elements, each specifying one model column. The “type”
attribute specifies the data type for the column.

An example of a UI Definition fragment for a tree store:

```text
<object class="GtkTreeStore">
  <columns>
    <column type="gchararray"/>
    <column type="gchararray"/>
    <column type="gint"/>
  </columns>
</object>
```

# Implements

[`TreeStoreExt`](trait.TreeStoreExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`TreeDragDestExt`](trait.TreeDragDestExt.html), [`TreeDragSourceExt`](trait.TreeDragSourceExt.html), [`TreeModelExt`](trait.TreeModelExt.html), [`TreeSortableExt`](trait.TreeSortableExt.html), [`TreeStoreExtManual`](prelude/trait.TreeStoreExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html), [`TreeSortableExtManual`](prelude/trait.TreeSortableExtManual.html)
<!-- trait TreeStoreExt -->
Trait containing all `TreeStore` methods.

# Implementors

[`TreeStore`](struct.TreeStore.html)
<!-- impl TreeStore::fn new -->
Creates a new tree store as with `n_columns` columns each of the types passed
in. Note that only types derived from standard GObject fundamental types
are supported.

As an example, `gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
GDK_TYPE_PIXBUF);` will create a new `TreeStore` with three columns, of type
`gint`, `gchararray`, and `gdk_pixbuf::Pixbuf` respectively.
## `n_columns`
number of columns in the tree store

# Returns

a new `TreeStore`
<!-- impl TreeStore::fn newv -->
Non vararg creation function. Used primarily by language bindings.
## `n_columns`
number of columns in the tree store
## `types`
an array of `glib::Type` types for the columns, from first to last

# Returns

a new `TreeStore`
<!-- trait TreeStoreExt::fn append -->
Appends a new row to `self`. If `parent` is non-`None`, then it will append the
new row after the last child of `parent`, otherwise it will append a row to
the top level. `iter` will be changed to point to this new row. The row will
be empty after this function is called. To fill in values, you need to call
`TreeStoreExt::set` or `TreeStore::set_value`.
## `iter`
An unset `TreeIter` to set to the appended row
## `parent`
A valid `TreeIter`, or `None`
<!-- trait TreeStoreExt::fn clear -->
Removes all rows from `self`
<!-- trait TreeStoreExt::fn insert -->
Creates a new row at `position`. If parent is non-`None`, then the row will be
made a child of `parent`. Otherwise, the row will be created at the toplevel.
If `position` is -1 or is larger than the number of rows at that level, then
the new row will be inserted to the end of the list. `iter` will be changed
to point to this new row. The row will be empty after this function is
called. To fill in values, you need to call `TreeStoreExt::set` or
`TreeStore::set_value`.
## `iter`
An unset `TreeIter` to set to the new row
## `parent`
A valid `TreeIter`, or `None`
## `position`
position to insert the new row, or -1 for last
<!-- trait TreeStoreExt::fn insert_after -->
Inserts a new row after `sibling`. If `sibling` is `None`, then the row will be
prepended to `parent` ’s children. If `parent` and `sibling` are `None`, then
the row will be prepended to the toplevel. If both `sibling` and `parent` are
set, then `parent` must be the parent of `sibling`. When `sibling` is set,
`parent` is optional.

`iter` will be changed to point to this new row. The row will be empty after
this function is called. To fill in values, you need to call
`TreeStoreExt::set` or `TreeStore::set_value`.
## `iter`
An unset `TreeIter` to set to the new row
## `parent`
A valid `TreeIter`, or `None`
## `sibling`
A valid `TreeIter`, or `None`
<!-- trait TreeStoreExt::fn insert_before -->
Inserts a new row before `sibling`. If `sibling` is `None`, then the row will
be appended to `parent` ’s children. If `parent` and `sibling` are `None`, then
the row will be appended to the toplevel. If both `sibling` and `parent` are
set, then `parent` must be the parent of `sibling`. When `sibling` is set,
`parent` is optional.

`iter` will be changed to point to this new row. The row will be empty after
this function is called. To fill in values, you need to call
`TreeStoreExt::set` or `TreeStore::set_value`.
## `iter`
An unset `TreeIter` to set to the new row
## `parent`
A valid `TreeIter`, or `None`
## `sibling`
A valid `TreeIter`, or `None`
<!-- trait TreeStoreExt::fn insert_with_values -->
Creates a new row at `position`. `iter` will be changed to point to this
new row. If `position` is -1, or larger than the number of rows on the list, then
the new row will be appended to the list. The row will be filled with
the values given to this function.

Calling
`gtk_tree_store_insert_with_values (tree_store, iter, position, ...)`
has the same effect as calling

```C
gtk_tree_store_insert (tree_store, iter, position);
gtk_tree_store_set (tree_store, iter, ...);
```
with the different that the former will only emit a row_inserted signal,
while the latter will emit row_inserted, row_changed and if the tree store
is sorted, rows_reordered. Since emitting the rows_reordered signal
repeatedly can affect the performance of the program,
`TreeStoreExt::insert_with_values` should generally be preferred when
inserting rows in a sorted tree store.
## `iter`
An unset `TreeIter` to set the new row, or `None`.
## `parent`
A valid `TreeIter`, or `None`
## `position`
position to insert the new row, or -1 to append after existing rows
<!-- trait TreeStoreExt::fn insert_with_valuesv -->
A variant of `TreeStoreExt::insert_with_values` which takes
the columns and values as two arrays, instead of varargs. This
function is mainly intended for language bindings.
## `iter`
An unset `TreeIter` to set the new row, or `None`.
## `parent`
A valid `TreeIter`, or `None`
## `position`
position to insert the new row, or -1 for last
## `columns`
an array of column numbers
## `values`
an array of GValues
## `n_values`
the length of the `columns` and `values` arrays
<!-- trait TreeStoreExt::fn is_ancestor -->
Returns `true` if `iter` is an ancestor of `descendant`. That is, `iter` is the
parent (or grandparent or great-grandparent) of `descendant`.
## `iter`
A valid `TreeIter`
## `descendant`
A valid `TreeIter`

# Returns

`true`, if `iter` is an ancestor of `descendant`
<!-- trait TreeStoreExt::fn iter_depth -->
Returns the depth of `iter`. This will be 0 for anything on the root level, 1
for anything down a level, etc.
## `iter`
A valid `TreeIter`

# Returns

The depth of `iter`
<!-- trait TreeStoreExt::fn iter_is_valid -->
WARNING: This function is slow. Only use it for debugging and/or testing
purposes.

Checks if the given iter is a valid iter for this `TreeStore`.
## `iter`
A `TreeIter`.

# Returns

`true` if the iter is valid, `false` if the iter is invalid.
<!-- trait TreeStoreExt::fn move_after -->
Moves `iter` in `self` to the position after `position`. `iter` and
`position` should be in the same level. Note that this function only
works with unsorted stores. If `position` is `None`, `iter` will be moved
to the start of the level.
## `iter`
A `TreeIter`.
## `position`
A `TreeIter`.
<!-- trait TreeStoreExt::fn move_before -->
Moves `iter` in `self` to the position before `position`. `iter` and
`position` should be in the same level. Note that this function only
works with unsorted stores. If `position` is `None`, `iter` will be
moved to the end of the level.
## `iter`
A `TreeIter`.
## `position`
A `TreeIter` or `None`.
<!-- trait TreeStoreExt::fn prepend -->
Prepends a new row to `self`. If `parent` is non-`None`, then it will prepend
the new row before the first child of `parent`, otherwise it will prepend a row
to the top level. `iter` will be changed to point to this new row. The row
will be empty after this function is called. To fill in values, you need to
call `TreeStoreExt::set` or `TreeStore::set_value`.
## `iter`
An unset `TreeIter` to set to the prepended row
## `parent`
A valid `TreeIter`, or `None`
<!-- trait TreeStoreExt::fn remove -->
Removes `iter` from `self`. After being removed, `iter` is set to the
next valid row at that level, or invalidated if it previously pointed to the
last one.
## `iter`
A valid `TreeIter`

# Returns

`true` if `iter` is still valid, `false` if not.
<!-- trait TreeStoreExtManual::fn reorder -->
Reorders the children of `parent` in `self` to follow the order
indicated by `new_order`. Note that this function only works with
unsorted stores.
## `parent`
A `TreeIter`, or `None`
## `new_order`
an array of integers mapping the new position of each child
 to its old position before the re-ordering,
 i.e. `new_order``[newpos] = oldpos`.
<!-- trait TreeStoreExt::fn set -->
Sets the value of one or more cells in the row referenced by `iter`.
The variable argument list should contain integer column numbers,
each column number followed by the value to be set.
The list is terminated by a -1. For example, to set column 0 with type
`G_TYPE_STRING` to “Foo”, you would write
`gtk_tree_store_set (store, iter, 0, "Foo", -1)`.

The value will be referenced by the store if it is a `G_TYPE_OBJECT`, and it
will be copied if it is a `G_TYPE_STRING` or `G_TYPE_BOXED`.
## `iter`
A valid `TreeIter` for the row being modified
<!-- trait TreeStoreExt::fn set_column_types -->
This function is meant primarily for `GObjects` that inherit from
`TreeStore`, and should only be used when constructing a new
`TreeStore`. It will not function after a row has been added,
or a method on the `TreeModel` interface is called.
## `n_columns`
Number of columns for the tree store
## `types`
An array of `glib::Type` types, one for each column
<!-- trait TreeStoreExt::fn set_valist -->
See `TreeStoreExt::set`; this version takes a va_list for
use by language bindings.
## `iter`
A valid `TreeIter` for the row being modified
## `var_args`
va_list of column/value pairs
<!-- trait TreeStoreExtManual::fn set_value -->
Sets the data in the cell specified by `iter` and `column`.
The type of `value` must be convertible to the type of the
column.
## `iter`
A valid `TreeIter` for the row being modified
## `column`
column number to modify
## `value`
new value for the cell
<!-- trait TreeStoreExt::fn set_valuesv -->
A variant of `TreeStoreExt::set_valist` which takes
the columns and values as two arrays, instead of varargs. This
function is mainly intended for language bindings or in case
the number of columns to change is not known until run-time.
## `iter`
A valid `TreeIter` for the row being modified
## `columns`
an array of column numbers
## `values`
an array of GValues
## `n_values`
the length of the `columns` and `values` arrays
<!-- trait TreeStoreExt::fn swap -->
Swaps `a` and `b` in the same level of `self`. Note that this function
only works with unsorted stores.
## `a`
A `TreeIter`.
## `b`
Another `TreeIter`.
<!-- struct TreeView -->
Widget that displays any object that implements the `TreeModel` interface.

Please refer to the
[tree widget conceptual overview][TreeWidget]
for an overview of all the objects and data types related
to the tree widget and how they work together.

Several different coordinate systems are exposed in the `TreeView` API.
These are:

![](tree-view-coordinates.png)

Coordinate systems in `TreeView` API:

- Widget coordinates: Coordinates relative to the widget (usually `widget->window`).

- Bin window coordinates: Coordinates relative to the window that `TreeView` renders to.

- Tree coordinates: Coordinates relative to the entire scrollable area of `TreeView`. These
 coordinates start at (0, 0) for row 0 of the tree.

Several functions are available for converting between the different
coordinate systems. The most common translations are between widget and bin
window coordinates and between bin window and tree coordinates. For the
former you can use `TreeViewExt::convert_widget_to_bin_window_coords`
(and vice versa), for the latter `TreeViewExt::convert_bin_window_to_tree_coords`
(and vice versa).

# `TreeView` as `Buildable`

The `TreeView` implementation of the `Buildable` interface accepts
`TreeViewColumn` objects as `<child>` elements and exposes the internal
`TreeSelection` in UI definitions.

An example of a UI definition fragment with `TreeView`:

```plain
treeview.view
├── header
│   ├── <column header>
┊   ┊
│   ╰── <column header>
│
╰── [rubberband]
```

`TreeView` has a main CSS node with name treeview and style class .view.
It has a subnode with name header, which is the parent for all the column
header widgets' CSS nodes.
For rubberband selection, a subnode with name rubberband is used.

# Implements

[`TreeViewExt`](trait.TreeViewExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ScrollableExt`](trait.ScrollableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait TreeViewExt -->
Trait containing all `TreeView` methods.

# Implementors

[`TreeView`](struct.TreeView.html)
<!-- impl TreeView::fn new -->
Creates a new `TreeView` widget.

# Returns

A newly created `TreeView` widget.
<!-- impl TreeView::fn new_with_model -->
Creates a new `TreeView` widget with the model initialized to `model`.
## `model`
the model.

# Returns

A newly created `TreeView` widget.
<!-- trait TreeViewExt::fn append_column -->
Appends `column` to the list of columns. If `self` has “fixed_height”
mode enabled, then `column` must have its “sizing” property set to be
GTK_TREE_VIEW_COLUMN_FIXED.
## `column`
The `TreeViewColumn` to add.

# Returns

The number of columns in `self` after appending.
<!-- trait TreeViewExt::fn collapse_all -->
Recursively collapses all visible, expanded nodes in `self`.
<!-- trait TreeViewExt::fn collapse_row -->
Collapses a row (hides its child rows, if they exist).
## `path`
path to a row in the `self`

# Returns

`true` if the row was collapsed.
<!-- trait TreeViewExt::fn columns_autosize -->
Resizes all columns to their optimal width. Only works after the
treeview has been realized.
<!-- trait TreeViewExt::fn convert_bin_window_to_tree_coords -->
Converts bin_window coordinates to coordinates for the
tree (the full scrollable area of the tree).
## `bx`
X coordinate relative to bin_window
## `by`
Y coordinate relative to bin_window
## `tx`
return location for tree X coordinate
## `ty`
return location for tree Y coordinate
<!-- trait TreeViewExt::fn convert_bin_window_to_widget_coords -->
Converts bin_window coordinates (see `TreeViewExt::get_bin_window`)
to widget relative coordinates.
## `bx`
bin_window X coordinate
## `by`
bin_window Y coordinate
## `wx`
return location for widget X coordinate
## `wy`
return location for widget Y coordinate
<!-- trait TreeViewExt::fn convert_tree_to_bin_window_coords -->
Converts tree coordinates (coordinates in full scrollable area of the tree)
to bin_window coordinates.
## `tx`
tree X coordinate
## `ty`
tree Y coordinate
## `bx`
return location for X coordinate relative to bin_window
## `by`
return location for Y coordinate relative to bin_window
<!-- trait TreeViewExt::fn convert_tree_to_widget_coords -->
Converts tree coordinates (coordinates in full scrollable area of the tree)
to widget coordinates.
## `tx`
X coordinate relative to the tree
## `ty`
Y coordinate relative to the tree
## `wx`
return location for widget X coordinate
## `wy`
return location for widget Y coordinate
<!-- trait TreeViewExt::fn convert_widget_to_bin_window_coords -->
Converts widget coordinates to coordinates for the bin_window
(see `TreeViewExt::get_bin_window`).
## `wx`
X coordinate relative to the widget
## `wy`
Y coordinate relative to the widget
## `bx`
return location for bin_window X coordinate
## `by`
return location for bin_window Y coordinate
<!-- trait TreeViewExt::fn convert_widget_to_tree_coords -->
Converts widget coordinates to coordinates for the
tree (the full scrollable area of the tree).
## `wx`
X coordinate relative to the widget
## `wy`
Y coordinate relative to the widget
## `tx`
return location for tree X coordinate
## `ty`
return location for tree Y coordinate
<!-- trait TreeViewExt::fn create_row_drag_icon -->
Creates a `cairo::Surface` representation of the row at `path`.
This image is used for a drag icon.
## `path`
a `TreePath` in `self`

# Returns

a newly-allocated surface of the drag icon.
<!-- trait TreeViewExt::fn enable_model_drag_dest -->
Turns `self` into a drop destination for automatic DND. Calling
this method sets `TreeView:reorderable` to `false`.
## `targets`
the table of targets that
 the drag will support
## `n_targets`
the number of items in `targets`
## `actions`
the bitmask of possible actions for a drag from this
 widget
<!-- trait TreeViewExt::fn enable_model_drag_source -->
Turns `self` into a drag source for automatic DND. Calling this
method sets `TreeView:reorderable` to `false`.
## `start_button_mask`
Mask of allowed buttons to start drag
## `targets`
the table of targets that the drag will support
## `n_targets`
the number of items in `targets`
## `actions`
the bitmask of possible actions for a drag from this
 widget
<!-- trait TreeViewExt::fn expand_all -->
Recursively expands all nodes in the `self`.
<!-- trait TreeViewExt::fn expand_row -->
Opens the row so its children are visible.
## `path`
path to a row
## `open_all`
whether to recursively expand, or just expand immediate children

# Returns

`true` if the row existed and had children
<!-- trait TreeViewExt::fn expand_to_path -->
Expands the row at `path`. This will also expand all parent rows of
`path` as necessary.
## `path`
path to a row.
<!-- trait TreeViewExt::fn get_activate_on_single_click -->
Gets the setting set by `TreeViewExt::set_activate_on_single_click`.

# Returns

`true` if row-activated will be emitted on a single click
<!-- trait TreeViewExt::fn get_background_area -->
Fills the bounding rectangle in bin_window coordinates for the cell at the
row specified by `path` and the column specified by `column`. If `path` is
`None`, or points to a node not found in the tree, the `y` and `height` fields of
the rectangle will be filled with 0. If `column` is `None`, the `x` and `width`
fields will be filled with 0. The returned rectangle is equivalent to the
`background_area` passed to `CellRendererExt::render`. These background
areas tile to cover the entire bin window. Contrast with the `cell_area`,
returned by `TreeViewExt::get_cell_area`, which returns only the cell
itself, excluding surrounding borders and the tree expander area.
## `path`
a `TreePath` for the row, or `None` to get only horizontal coordinates
## `column`
a `TreeViewColumn` for the column, or `None` to get only vertical coordiantes
## `rect`
rectangle to fill with cell background rect
<!-- trait TreeViewExt::fn get_bin_window -->
Returns the window that `self` renders to.
This is used primarily to compare to `event->window`
to confirm that the event on `self` is on the right window.

# Returns

A `gdk::Window`, or `None` when `self`
hasn’t been realized yet.
<!-- trait TreeViewExt::fn get_cell_area -->
Fills the bounding rectangle in bin_window coordinates for the cell at the
row specified by `path` and the column specified by `column`. If `path` is
`None`, or points to a path not currently displayed, the `y` and `height` fields
of the rectangle will be filled with 0. If `column` is `None`, the `x` and `width`
fields will be filled with 0. The sum of all cell rects does not cover the
entire tree; there are extra pixels in between rows, for example. The
returned rectangle is equivalent to the `cell_area` passed to
`CellRendererExt::render`. This function is only valid if `self` is
realized.
## `path`
a `TreePath` for the row, or `None` to get only horizontal coordinates
## `column`
a `TreeViewColumn` for the column, or `None` to get only vertical coordinates
## `rect`
rectangle to fill with cell rect
<!-- trait TreeViewExt::fn get_column -->
Gets the `TreeViewColumn` at the given position in the `tree_view`.
## `n`
The position of the column, counting from 0.

# Returns

The `TreeViewColumn`, or `None` if the
position is outside the range of columns.
<!-- trait TreeViewExt::fn get_columns -->
Returns a `glib::List` of all the `TreeViewColumn` s currently in `self`.
The returned list must be freed with g_list_free ().

# Returns

A list of `TreeViewColumn` s
<!-- trait TreeViewExt::fn get_cursor -->
Fills in `path` and `focus_column` with the current path and focus column. If
the cursor isn’t currently set, then *`path` will be `None`. If no column
currently has focus, then *`focus_column` will be `None`.

The returned `TreePath` must be freed with `TreePath::free` when
you are done with it.
## `path`
A pointer to be
 filled with the current cursor path, or `None`
## `focus_column`
A
 pointer to be filled with the current focus column, or `None`
<!-- trait TreeViewExt::fn get_dest_row_at_pos -->
Determines the destination row for a given position. `drag_x` and
`drag_y` are expected to be in widget coordinates. This function is only
meaningful if `self` is realized. Therefore this function will always
return `false` if `self` is not realized or does not have a model.
## `drag_x`
the position to determine the destination row for
## `drag_y`
the position to determine the destination row for
## `path`
Return location for the path of
 the highlighted row, or `None`.
## `pos`
Return location for the drop position, or
 `None`

# Returns

whether there is a row at the given position, `true` if this
is indeed the case.
<!-- trait TreeViewExt::fn get_drag_dest_row -->
Gets information about the row that is highlighted for feedback.
## `path`
Return location for the path of the highlighted row, or `None`.
## `pos`
Return location for the drop position, or `None`
<!-- trait TreeViewExt::fn get_enable_search -->
Returns whether or not the tree allows to start interactive searching
by typing in text.

# Returns

whether or not to let the user search interactively
<!-- trait TreeViewExt::fn get_enable_tree_lines -->
Returns whether or not tree lines are drawn in `self`.

# Returns

`true` if tree lines are drawn in `self`, `false`
otherwise.
<!-- trait TreeViewExt::fn get_expander_column -->
Returns the column that is the current expander column.
This column has the expander arrow drawn next to it.

# Returns

The expander column.
<!-- trait TreeViewExt::fn get_fixed_height_mode -->
Returns whether fixed height mode is turned on for `self`.

# Returns

`true` if `self` is in fixed height mode
<!-- trait TreeViewExt::fn get_grid_lines -->
Returns which grid lines are enabled in `self`.

# Returns

a `TreeViewGridLines` value indicating which grid lines
are enabled.
<!-- trait TreeViewExt::fn get_headers_clickable -->
Returns whether all header columns are clickable.

# Returns

`true` if all header columns are clickable, otherwise `false`
<!-- trait TreeViewExt::fn get_headers_visible -->
Returns `true` if the headers on the `self` are visible.

# Returns

Whether the headers are visible or not.
<!-- trait TreeViewExt::fn get_hover_expand -->
Returns whether hover expansion mode is turned on for `self`.

# Returns

`true` if `self` is in hover expansion mode
<!-- trait TreeViewExt::fn get_hover_selection -->
Returns whether hover selection mode is turned on for `self`.

# Returns

`true` if `self` is in hover selection mode
<!-- trait TreeViewExt::fn get_level_indentation -->
Returns the amount, in pixels, of extra indentation for child levels
in `self`.

# Returns

the amount of extra indentation for child levels in
`self`. A return value of 0 means that this feature is disabled.
<!-- trait TreeViewExt::fn get_model -->
Returns the model the `TreeView` is based on. Returns `None` if the
model is unset.

# Returns

A `TreeModel`, or `None` if
none is currently being used.
<!-- trait TreeViewExt::fn get_n_columns -->
Queries the number of columns in the given `self`.

# Returns

The number of columns in the `self`
<!-- trait TreeViewExt::fn get_path_at_pos -->
Finds the path at the point (`x`, `y`), relative to bin_window coordinates
(please see `TreeViewExt::get_bin_window`).
That is, `x` and `y` are relative to an events coordinates. `x` and `y` must
come from an event on the `self` only where `event->window ==
gtk_tree_view_get_bin_window ()`. It is primarily for
things like popup menus. If `path` is non-`None`, then it will be filled
with the `TreePath` at that point. This path should be freed with
`TreePath::free`. If `column` is non-`None`, then it will be filled
with the column at that point. `cell_x` and `cell_y` return the coordinates
relative to the cell background (i.e. the `background_area` passed to
`CellRendererExt::render`). This function is only meaningful if
`self` is realized. Therefore this function will always return `false`
if `self` is not realized or does not have a model.

For converting widget coordinates (eg. the ones you get from
`Widget`::query-tooltip), please see
`TreeViewExt::convert_widget_to_bin_window_coords`.
## `x`
The x position to be identified (relative to bin_window).
## `y`
The y position to be identified (relative to bin_window).
## `path`
A pointer to a `TreePath`
 pointer to be filled in, or `None`
## `column`
A pointer to
 a `TreeViewColumn` pointer to be filled in, or `None`
## `cell_x`
A pointer where the X coordinate
 relative to the cell can be placed, or `None`
## `cell_y`
A pointer where the Y coordinate
 relative to the cell can be placed, or `None`

# Returns

`true` if a row exists at that coordinate.
<!-- trait TreeViewExt::fn get_reorderable -->
Retrieves whether the user can reorder the tree via drag-and-drop. See
`TreeViewExt::set_reorderable`.

# Returns

`true` if the tree can be reordered.
<!-- trait TreeViewExt::fn get_row_separator_func -->
Returns the current row separator function.

# Returns

the current row separator function.
<!-- trait TreeViewExt::fn get_rubber_banding -->
Returns whether rubber banding is turned on for `self`. If the
selection mode is `SelectionMode::Multiple`, rubber banding will allow the
user to select multiple rows by dragging the mouse.

# Returns

`true` if rubber banding in `self` is enabled.
<!-- trait TreeViewExt::fn get_search_column -->
Gets the column searched on by the interactive search code.

# Returns

the column the interactive search code searches in.
<!-- trait TreeViewExt::fn get_search_entry -->
Returns the `Entry` which is currently in use as interactive search
entry for `self`. In case the built-in entry is being used, `None`
will be returned.

# Returns

the entry currently in use as search entry.
<!-- trait TreeViewExt::fn get_search_equal_func -->
Returns the compare function currently in use.

# Returns

the currently used compare function for the search code.
<!-- trait TreeViewExt::fn get_search_position_func -->
Returns the positioning function currently in use.

# Returns

the currently used function for positioning the search dialog.
<!-- trait TreeViewExt::fn get_selection -->
Gets the `TreeSelection` associated with `self`.

# Returns

A `TreeSelection` object.
<!-- trait TreeViewExt::fn get_show_expanders -->
Returns whether or not expanders are drawn in `self`.

# Returns

`true` if expanders are drawn in `self`, `false`
otherwise.
<!-- trait TreeViewExt::fn get_tooltip_column -->
Returns the column of `self`’s model which is being used for
displaying tooltips on `self`’s rows.

# Returns

the index of the tooltip column that is currently being
used, or -1 if this is disabled.
<!-- trait TreeViewExt::fn get_tooltip_context -->
This function is supposed to be used in a `Widget::query-tooltip`
signal handler for `TreeView`. The `x`, `y` and `keyboard_tip` values
which are received in the signal handler, should be passed to this
function without modification.

The return value indicates whether there is a tree view row at the given
coordinates (`true`) or not (`false`) for mouse tooltips. For keyboard
tooltips the row returned will be the cursor row. When `true`, then any of
`model`, `path` and `iter` which have been provided will be set to point to
that row and the corresponding model. `x` and `y` will always be converted
to be relative to `self`’s bin_window if `keyboard_tooltip` is `false`.
## `x`
the x coordinate (relative to widget coordinates)
## `y`
the y coordinate (relative to widget coordinates)
## `keyboard_tip`
whether this is a keyboard tooltip or not
## `model`
a pointer to
 receive a `TreeModel` or `None`
## `path`
a pointer to receive a `TreePath` or `None`
## `iter`
a pointer to receive a `TreeIter` or `None`

# Returns

whether or not the given tooltip context points to a row.
<!-- trait TreeViewExt::fn get_visible_range -->
Sets `start_path` and `end_path` to be the first and last visible path.
Note that there may be invisible paths in between.

The paths should be freed with `TreePath::free` after use.
## `start_path`
Return location for start of region,
 or `None`.
## `end_path`
Return location for end of region, or `None`.

# Returns

`true`, if valid paths were placed in `start_path` and `end_path`.
<!-- trait TreeViewExt::fn get_visible_rect -->
Fills `visible_rect` with the currently-visible region of the
buffer, in tree coordinates. Convert to bin_window coordinates with
`TreeViewExt::convert_tree_to_bin_window_coords`.
Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire
scrollable area of the tree.
## `visible_rect`
rectangle to fill
<!-- trait TreeViewExt::fn insert_column -->
This inserts the `column` into the `self` at `position`. If `position` is
-1, then the column is inserted at the end. If `self` has
“fixed_height” mode enabled, then `column` must have its “sizing” property
set to be GTK_TREE_VIEW_COLUMN_FIXED.
## `column`
The `TreeViewColumn` to be inserted.
## `position`
The position to insert `column` in.

# Returns

The number of columns in `self` after insertion.
<!-- trait TreeViewExt::fn insert_column_with_attributes -->
Creates a new `TreeViewColumn` and inserts it into the `self` at
`position`. If `position` is -1, then the newly created column is inserted at
the end. The column is initialized with the attributes given. If `self`
has “fixed_height” mode enabled, then the new column will have its sizing
property set to be GTK_TREE_VIEW_COLUMN_FIXED.
## `position`
The position to insert the new column in
## `title`
The title to set the header to
## `cell`
The `CellRenderer`

# Returns

The number of columns in `self` after insertion.
<!-- trait TreeViewExt::fn insert_column_with_data_func -->
Convenience function that inserts a new column into the `TreeView`
with the given cell renderer and a ``GtkTreeCellDataFunc`` to set cell renderer
attributes (normally using data from the model). See also
`TreeViewColumnExt::set_cell_data_func`, `TreeViewColumn::pack_start`.
If `self` has “fixed_height” mode enabled, then the new column will have its
“sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED.
## `position`
Position to insert, -1 for append
## `title`
column title
## `cell`
cell renderer for column
## `func`
function to set attributes of cell renderer
## `data`
data for `func`
## `dnotify`
destroy notifier for `data`

# Returns

number of columns in the tree view post-insert
<!-- trait TreeViewExt::fn is_blank_at_pos -->
Determine whether the point (`x`, `y`) in `self` is blank, that is no
cell content nor an expander arrow is drawn at the location. If so, the
location can be considered as the background. You might wish to take
special action on clicks on the background, such as clearing a current
selection, having a custom context menu or starting rubber banding.

The `x` and `y` coordinate that are provided must be relative to bin_window
coordinates. That is, `x` and `y` must come from an event on `self`
where `event->window == gtk_tree_view_get_bin_window ()`.

For converting widget coordinates (eg. the ones you get from
`Widget`::query-tooltip), please see
`TreeViewExt::convert_widget_to_bin_window_coords`.

The `path`, `column`, `cell_x` and `cell_y` arguments will be filled in
likewise as for `TreeViewExt::get_path_at_pos`. Please see
`TreeViewExt::get_path_at_pos` for more information.
## `x`
The x position to be identified (relative to bin_window)
## `y`
The y position to be identified (relative to bin_window)
## `path`
A pointer to a `TreePath` pointer to
 be filled in, or `None`
## `column`
A pointer to a
 `TreeViewColumn` pointer to be filled in, or `None`
## `cell_x`
A pointer where the X coordinate relative to the
 cell can be placed, or `None`
## `cell_y`
A pointer where the Y coordinate relative to the
 cell can be placed, or `None`

# Returns

`true` if the area at the given coordinates is blank,
`false` otherwise.
<!-- trait TreeViewExt::fn is_rubber_banding_active -->
Returns whether a rubber banding operation is currently being done
in `self`.

# Returns

`true` if a rubber banding operation is currently being
done in `self`.
<!-- trait TreeViewExt::fn map_expanded_rows -->
Calls `func` on all expanded rows.
## `func`
A function to be called
## `data`
User data to be passed to the function.
<!-- trait TreeViewExt::fn move_column_after -->
Moves `column` to be after to `base_column`. If `base_column` is `None`, then
`column` is placed in the first position.
## `column`
The `TreeViewColumn` to be moved.
## `base_column`
The `TreeViewColumn` to be moved relative to, or `None`.
<!-- trait TreeViewExt::fn remove_column -->
Removes `column` from `self`.
## `column`
The `TreeViewColumn` to remove.

# Returns

The number of columns in `self` after removing.
<!-- trait TreeViewExt::fn row_activated -->
Activates the cell determined by `path` and `column`.
## `path`
The `TreePath` to be activated.
## `column`
The `TreeViewColumn` to be activated.
<!-- trait TreeViewExt::fn row_expanded -->
Returns `true` if the node pointed to by `path` is expanded in `self`.
## `path`
A `TreePath` to test expansion state.

# Returns

`true` if `path` is expanded.
<!-- trait TreeViewExt::fn scroll_to_cell -->
Moves the alignments of `self` to the position specified by `column` and
`path`. If `column` is `None`, then no horizontal scrolling occurs. Likewise,
if `path` is `None` no vertical scrolling occurs. At a minimum, one of `column`
or `path` need to be non-`None`. `row_align` determines where the row is
placed, and `col_align` determines where `column` is placed. Both are expected
to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means
right/bottom alignment, 0.5 means center.

If `use_align` is `false`, then the alignment arguments are ignored, and the
tree does the minimum amount of work to scroll the cell onto the screen.
This means that the cell will be scrolled to the edge closest to its current
position. If the cell is currently visible on the screen, nothing is done.

This function only works if the model is set, and `path` is a valid row on the
model. If the model changes before the `self` is realized, the centered
path will be modified to reflect this change.
## `path`
The path of the row to move to, or `None`.
## `column`
The `TreeViewColumn` to move horizontally to, or `None`.
## `use_align`
whether to use alignment arguments, or `false`.
## `row_align`
The vertical alignment of the row specified by `path`.
## `col_align`
The horizontal alignment of the column specified by `column`.
<!-- trait TreeViewExt::fn scroll_to_point -->
Scrolls the tree view such that the top-left corner of the visible
area is `tree_x`, `tree_y`, where `tree_x` and `tree_y` are specified
in tree coordinates. The `self` must be realized before
this function is called. If it isn't, you probably want to be
using `TreeViewExt::scroll_to_cell`.

If either `tree_x` or `tree_y` are -1, then that direction isn’t scrolled.
## `tree_x`
X coordinate of new top-left pixel of visible area, or -1
## `tree_y`
Y coordinate of new top-left pixel of visible area, or -1
<!-- trait TreeViewExt::fn set_activate_on_single_click -->
Cause the `TreeView::row-activated` signal to be emitted
on a single click instead of a double click.
## `single`
`true` to emit row-activated on a single click
<!-- trait TreeViewExt::fn set_column_drag_function -->
Sets a user function for determining where a column may be dropped when
dragged. This function is called on every column pair in turn at the
beginning of a column drag to determine where a drop can take place. The
arguments passed to `func` are: the `self`, the `TreeViewColumn` being
dragged, the two `TreeViewColumn` s determining the drop spot, and
`user_data`. If either of the `TreeViewColumn` arguments for the drop spot
are `None`, then they indicate an edge. If `func` is set to be `None`, then
`self` reverts to the default behavior of allowing all columns to be
dropped everywhere.
## `func`
A function to determine which columns are reorderable, or `None`.
## `user_data`
User data to be passed to `func`, or `None`
## `destroy`
Destroy notifier for `user_data`, or `None`
<!-- trait TreeViewExt::fn set_cursor -->
Sets the current keyboard focus to be at `path`, and selects it. This is
useful when you want to focus the user’s attention on a particular row. If
`focus_column` is not `None`, then focus is given to the column specified by
it. Additionally, if `focus_column` is specified, and `start_editing` is
`true`, then editing should be started in the specified cell.
This function is often followed by `WidgetExt::grab_focus` (`self`)
in order to give keyboard focus to the widget. Please note that editing
can only happen when the widget is realized.

If `path` is invalid for `model`, the current cursor (if any) will be unset
and the function will return without failing.
## `path`
A `TreePath`
## `focus_column`
A `TreeViewColumn`, or `None`
## `start_editing`
`true` if the specified cell should start being edited.
<!-- trait TreeViewExt::fn set_cursor_on_cell -->
Sets the current keyboard focus to be at `path`, and selects it. This is
useful when you want to focus the user’s attention on a particular row. If
`focus_column` is not `None`, then focus is given to the column specified by
it. If `focus_column` and `focus_cell` are not `None`, and `focus_column`
contains 2 or more editable or activatable cells, then focus is given to
the cell specified by `focus_cell`. Additionally, if `focus_column` is
specified, and `start_editing` is `true`, then editing should be started in
the specified cell. This function is often followed by
`WidgetExt::grab_focus` (`self`) in order to give keyboard focus to the
widget. Please note that editing can only happen when the widget is
realized.

If `path` is invalid for `model`, the current cursor (if any) will be unset
and the function will return without failing.
## `path`
A `TreePath`
## `focus_column`
A `TreeViewColumn`, or `None`
## `focus_cell`
A `CellRenderer`, or `None`
## `start_editing`
`true` if the specified cell should start being edited.
<!-- trait TreeViewExt::fn set_drag_dest_row -->
Sets the row that is highlighted for feedback.
If `path` is `None`, an existing highlight is removed.
## `path`
The path of the row to highlight, or `None`
## `pos`
Specifies whether to drop before, after or into the row
<!-- trait TreeViewExt::fn set_enable_search -->
If `enable_search` is set, then the user can type in text to search through
the tree interactively (this is sometimes called "typeahead find").

Note that even if this is `false`, the user can still initiate a search
using the “start-interactive-search” key binding.
## `enable_search`
`true`, if the user can search interactively
<!-- trait TreeViewExt::fn set_enable_tree_lines -->
Sets whether to draw lines interconnecting the expanders in `self`.
This does not have any visible effects for lists.
## `enabled`
`true` to enable tree line drawing, `false` otherwise.
<!-- trait TreeViewExt::fn set_expander_column -->
Sets the column to draw the expander arrow at. It must be in `self`.
If `column` is `None`, then the expander arrow is always at the first
visible column.

If you do not want expander arrow to appear in your tree, set the
expander column to a hidden column.
## `column`
`None`, or the column to draw the expander arrow at.
<!-- trait TreeViewExt::fn set_fixed_height_mode -->
Enables or disables the fixed height mode of `self`.
Fixed height mode speeds up `TreeView` by assuming that all
rows have the same height.
Only enable this option if all rows are the same height and all
columns are of type `TreeViewColumnSizing::Fixed`.
## `enable`
`true` to enable fixed height mode
<!-- trait TreeViewExt::fn set_grid_lines -->
Sets which grid lines to draw in `self`.
## `grid_lines`
a `TreeViewGridLines` value indicating which grid lines to
enable.
<!-- trait TreeViewExt::fn set_headers_clickable -->
Allow the column title buttons to be clicked.
## `setting`
`true` if the columns are clickable.
<!-- trait TreeViewExt::fn set_headers_visible -->
Sets the visibility state of the headers.
## `headers_visible`
`true` if the headers are visible
<!-- trait TreeViewExt::fn set_hover_expand -->
Enables or disables the hover expansion mode of `self`.
Hover expansion makes rows expand or collapse if the pointer
moves over them.
## `expand`
`true` to enable hover selection mode
<!-- trait TreeViewExt::fn set_hover_selection -->
Enables or disables the hover selection mode of `self`.
Hover selection makes the selected row follow the pointer.
Currently, this works only for the selection modes
`SelectionMode::Single` and `SelectionMode::Browse`.
## `hover`
`true` to enable hover selection mode
<!-- trait TreeViewExt::fn set_level_indentation -->
Sets the amount of extra indentation for child levels to use in `self`
in addition to the default indentation. The value should be specified in
pixels, a value of 0 disables this feature and in this case only the default
indentation will be used.
This does not have any visible effects for lists.
## `indentation`
the amount, in pixels, of extra indentation in `self`.
<!-- trait TreeViewExt::fn set_model -->
Sets the model for a `TreeView`. If the `self` already has a model
set, it will remove it before setting the new model. If `model` is `None`,
then it will unset the old model.
## `model`
The model.
<!-- trait TreeViewExt::fn set_reorderable -->
This function is a convenience function to allow you to reorder
models that support the `TreeDragSourceIface` and the
`TreeDragDestIface`. Both `TreeStore` and `ListStore` support
these. If `reorderable` is `true`, then the user can reorder the
model by dragging and dropping rows. The developer can listen to
these changes by connecting to the model’s `TreeModel::row-inserted`
and `TreeModel::row-deleted` signals. The reordering is implemented
by setting up the tree view as a drag source and destination.
Therefore, drag and drop can not be used in a reorderable view for any
other purpose.

This function does not give you any degree of control over the order -- any
reordering is allowed. If more control is needed, you should probably
handle drag and drop manually.
## `reorderable`
`true`, if the tree can be reordered.
<!-- trait TreeViewExt::fn set_row_separator_func -->
Sets the row separator function, which is used to determine
whether a row should be drawn as a separator. If the row separator
function is `None`, no separators are drawn. This is the default value.
## `func`
a ``GtkTreeViewRowSeparatorFunc``
## `data`
user data to pass to `func`, or `None`
## `destroy`
destroy notifier for `data`, or `None`
<!-- trait TreeViewExt::fn set_rubber_banding -->
Enables or disables rubber banding in `self`. If the selection mode
is `SelectionMode::Multiple`, rubber banding will allow the user to select
multiple rows by dragging the mouse.
## `enable`
`true` to enable rubber banding
<!-- trait TreeViewExt::fn set_search_column -->
Sets `column` as the column where the interactive search code should
search in for the current model.

If the search column is set, users can use the “start-interactive-search”
key binding to bring up search popup. The enable-search property controls
whether simply typing text will also start an interactive search.

Note that `column` refers to a column of the current model. The search
column is reset to -1 when the model is changed.
## `column`
the column of the model to search in, or -1 to disable searching
<!-- trait TreeViewExt::fn set_search_entry -->
Sets the entry which the interactive search code will use for this
`self`. This is useful when you want to provide a search entry
in our interface at all time at a fixed position. Passing `None` for
`entry` will make the interactive search code use the built-in popup
entry again.
## `entry`
the entry the interactive search code of `self` should use or `None`
<!-- trait TreeViewExt::fn set_search_equal_func -->
Sets the compare function for the interactive search capabilities; note
that somewhat like `strcmp` returning 0 for equality
``GtkTreeViewSearchEqualFunc`` returns `false` on matches.
## `search_equal_func`
the compare function to use during the search
## `search_user_data`
user data to pass to `search_equal_func`, or `None`
## `search_destroy`
Destroy notifier for `search_user_data`, or `None`
<!-- trait TreeViewExt::fn set_search_position_func -->
Sets the function to use when positioning the search dialog.
## `func`
the function to use to position the search dialog, or `None`
 to use the default search position function
## `data`
user data to pass to `func`, or `None`
## `destroy`
Destroy notifier for `data`, or `None`
<!-- trait TreeViewExt::fn set_show_expanders -->
Sets whether to draw and enable expanders and indent child rows in
`self`. When disabled there will be no expanders visible in trees
and there will be no way to expand and collapse rows by default. Also
note that hiding the expanders will disable the default indentation. You
can set a custom indentation in this case using
`TreeViewExt::set_level_indentation`.
This does not have any visible effects for lists.
## `enabled`
`true` to enable expander drawing, `false` otherwise.
<!-- trait TreeViewExt::fn set_tooltip_cell -->
Sets the tip area of `tooltip` to the area `path`, `column` and `cell` have
in common. For example if `path` is `None` and `column` is set, the tip
area will be set to the full area covered by `column`. See also
`Tooltip::set_tip_area`.

Note that if `path` is not specified and `cell` is set and part of a column
containing the expander, the tooltip might not show and hide at the correct
position. In such cases `path` must be set to the current node under the
mouse cursor for this function to operate correctly.

See also `TreeViewExt::set_tooltip_column` for a simpler alternative.
## `tooltip`
a `Tooltip`
## `path`
a `TreePath` or `None`
## `column`
a `TreeViewColumn` or `None`
## `cell`
a `CellRenderer` or `None`
<!-- trait TreeViewExt::fn set_tooltip_column -->
If you only plan to have simple (text-only) tooltips on full rows, you
can use this function to have `TreeView` handle these automatically
for you. `column` should be set to the column in `self`’s model
containing the tooltip texts, or -1 to disable this feature.

When enabled, `Widget:has-tooltip` will be set to `true` and
`self` will connect a `Widget::query-tooltip` signal handler.

Note that the signal handler sets the text with `Tooltip::set_markup`,
so &, <, etc have to be escaped in the text.
## `column`
an integer, which is a valid column number for `self`’s model
<!-- trait TreeViewExt::fn set_tooltip_row -->
Sets the tip area of `tooltip` to be the area covered by the row at `path`.
See also `TreeViewExt::set_tooltip_column` for a simpler alternative.
See also `Tooltip::set_tip_area`.
## `tooltip`
a `Tooltip`
## `path`
a `TreePath`
<!-- trait TreeViewExt::fn unset_rows_drag_dest -->
Undoes the effect of
`TreeView::enable_model_drag_dest`. Calling this method sets
`TreeView:reorderable` to `false`.
<!-- trait TreeViewExt::fn unset_rows_drag_source -->
Undoes the effect of
`TreeView::enable_model_drag_source`. Calling this method sets
`TreeView:reorderable` to `false`.
<!-- trait TreeViewExt::fn connect_columns_changed -->
The number of columns of the treeview has changed.
<!-- trait TreeViewExt::fn connect_cursor_changed -->
The position of the cursor (focused cell) has changed.
<!-- trait TreeViewExt::fn connect_move_cursor -->
The `TreeView::move-cursor` signal is a [keybinding
signal][`BindingSignal`] which gets emitted when the user
presses one of the cursor keys.

Applications should not connect to it, but may emit it with
`g_signal_emit_by_name` if they need to control the cursor
programmatically. In contrast to `TreeViewExt::set_cursor` and
`TreeViewExt::set_cursor_on_cell` when moving horizontally
`TreeView::move-cursor` does not reset the current selection.
## `step`
the granularity of the move, as a
`MovementStep`. `MovementStep::LogicalPositions`,
`MovementStep::VisualPositions`, `MovementStep::DisplayLines`,
`MovementStep::Pages` and `MovementStep::BufferEnds` are
supported. `MovementStep::LogicalPositions` and
`MovementStep::VisualPositions` are treated identically.
## `direction`
the direction to move: +1 to move forwards;
-1 to move backwards. The resulting movement is
undefined for all other values.

# Returns

`true` if `step` is supported, `false` otherwise.
<!-- trait TreeViewExt::fn connect_row_activated -->
The "row-activated" signal is emitted when the method
`TreeViewExt::row_activated` is called, when the user double
clicks a treeview row with the "activate-on-single-click"
property set to `false`, or when the user single clicks a row when
the "activate-on-single-click" property set to `true`. It is also
emitted when a non-editable row is selected and one of the keys:
Space, Shift+Space, Return or Enter is pressed.

For selection handling refer to the
[tree widget conceptual overview][TreeWidget]
as well as `TreeSelection`.
## `path`
the `TreePath` for the activated row
## `column`
the `TreeViewColumn` in which the activation occurred
<!-- trait TreeViewExt::fn connect_row_collapsed -->
The given row has been collapsed (child nodes are hidden).
## `iter`
the tree iter of the collapsed row
## `path`
a tree path that points to the row
<!-- trait TreeViewExt::fn connect_row_expanded -->
The given row has been expanded (child nodes are shown).
## `iter`
the tree iter of the expanded row
## `path`
a tree path that points to the row
<!-- trait TreeViewExt::fn connect_test_collapse_row -->
The given row is about to be collapsed (hide its children nodes). Use this
signal if you need to control the collapsibility of individual rows.
## `iter`
the tree iter of the row to collapse
## `path`
a tree path that points to the row

# Returns

`false` to allow collapsing, `true` to reject
<!-- trait TreeViewExt::fn connect_test_expand_row -->
The given row is about to be expanded (show its children nodes). Use this
signal if you need to control the expandability of individual rows.
## `iter`
the tree iter of the row to expand
## `path`
a tree path that points to the row

# Returns

`false` to allow expansion, `true` to reject
<!-- trait TreeViewExt::fn get_property_activate_on_single_click -->
The activate-on-single-click property specifies whether the "row-activated" signal
will be emitted after a single click.
<!-- trait TreeViewExt::fn set_property_activate_on_single_click -->
The activate-on-single-click property specifies whether the "row-activated" signal
will be emitted after a single click.
<!-- trait TreeViewExt::fn get_property_fixed_height_mode -->
Setting the ::fixed-height-mode property to `true` speeds up
`TreeView` by assuming that all rows have the same height.
Only enable this option if all rows are the same height.
Please see `TreeViewExt::set_fixed_height_mode` for more
information on this option.
<!-- trait TreeViewExt::fn set_property_fixed_height_mode -->
Setting the ::fixed-height-mode property to `true` speeds up
`TreeView` by assuming that all rows have the same height.
Only enable this option if all rows are the same height.
Please see `TreeViewExt::set_fixed_height_mode` for more
information on this option.
<!-- trait TreeViewExt::fn get_property_hover_expand -->
Enables or disables the hover expansion mode of `tree_view`.
Hover expansion makes rows expand or collapse if the pointer moves
over them.

This mode is primarily intended for treeviews in popups, e.g.
in `ComboBox` or `EntryCompletion`.
<!-- trait TreeViewExt::fn set_property_hover_expand -->
Enables or disables the hover expansion mode of `tree_view`.
Hover expansion makes rows expand or collapse if the pointer moves
over them.

This mode is primarily intended for treeviews in popups, e.g.
in `ComboBox` or `EntryCompletion`.
<!-- trait TreeViewExt::fn get_property_hover_selection -->
Enables or disables the hover selection mode of `tree_view`.
Hover selection makes the selected row follow the pointer.
Currently, this works only for the selection modes
`SelectionMode::Single` and `SelectionMode::Browse`.

This mode is primarily intended for treeviews in popups, e.g.
in `ComboBox` or `EntryCompletion`.
<!-- trait TreeViewExt::fn set_property_hover_selection -->
Enables or disables the hover selection mode of `tree_view`.
Hover selection makes the selected row follow the pointer.
Currently, this works only for the selection modes
`SelectionMode::Single` and `SelectionMode::Browse`.

This mode is primarily intended for treeviews in popups, e.g.
in `ComboBox` or `EntryCompletion`.
<!-- trait TreeViewExt::fn get_property_level_indentation -->
Extra indentation for each level.
<!-- trait TreeViewExt::fn set_property_level_indentation -->
Extra indentation for each level.
<!-- trait TreeViewExt::fn get_property_show_expanders -->
`true` if the view has expanders.
<!-- trait TreeViewExt::fn set_property_show_expanders -->
`true` if the view has expanders.
<!-- struct TreeViewColumn -->
The `TreeViewColumn` object represents a visible column in a `TreeView` widget.
It allows to set properties of the column header, and functions as a holding pen for
the cell renderers which determine how the data in the column is displayed.

Please refer to the [tree widget conceptual overview][TreeWidget]
for an overview of all the objects and data types related to the tree widget and how
they work together.

# Implements

[`TreeViewColumnExt`](trait.TreeViewColumnExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait TreeViewColumnExt -->
Trait containing all `TreeViewColumn` methods.

# Implementors

[`TreeViewColumn`](struct.TreeViewColumn.html)
<!-- impl TreeViewColumn::fn new -->
Creates a new `TreeViewColumn`.

# Returns

A newly created `TreeViewColumn`.
<!-- impl TreeViewColumn::fn new_with_area -->
Creates a new `TreeViewColumn` using `area` to render its cells.
## `area`
the `CellArea` that the newly created column should use to layout cells.

# Returns

A newly created `TreeViewColumn`.
<!-- impl TreeViewColumn::fn new_with_attributes -->
Creates a new `TreeViewColumn` with a number of default values.
This is equivalent to calling `TreeViewColumnExt::set_title`,
`TreeViewColumn::pack_start`, and
`TreeViewColumn::set_attributes` on the newly created `TreeViewColumn`.

Here’s a simple example:

```C
 enum { TEXT_COLUMN, COLOR_COLUMN, N_COLUMNS };
 // ...
 {
   GtkTreeViewColumn *column;
   GtkCellRenderer   *renderer = gtk_cell_renderer_text_new ();
 
   column = gtk_tree_view_column_new_with_attributes ("Title",
                                                      renderer,
                                                      "text", TEXT_COLUMN,
                                                      "foreground", COLOR_COLUMN,
                                                      NULL);
 }
```
## `title`
The title to set the header to
## `cell`
The `CellRenderer`

# Returns

A newly created `TreeViewColumn`.
<!-- trait TreeViewColumnExt::fn add_attribute -->
Adds an attribute mapping to the list in `self`. The `column` is the
column of the model to get a value from, and the `attribute` is the
parameter on `cell_renderer` to be set from the value. So for example
if column 2 of the model contains strings, you could have the
“text” attribute of a `CellRendererText` get its values from
column 2.
## `cell_renderer`
the `CellRenderer` to set attributes on
## `attribute`
An attribute on the renderer
## `column`
The column position on the model to get the attribute from.
<!-- trait TreeViewColumnExt::fn cell_get_position -->
Obtains the horizontal position and size of a cell in a column. If the
cell is not found in the column, `start_pos` and `width` are not changed and
`false` is returned.
## `cell_renderer`
a `CellRenderer`
## `x_offset`
return location for the horizontal
 position of `cell` within `self`, may be `None`
## `width`
return location for the width of `cell`,
 may be `None`

# Returns

`true` if `cell` belongs to `self`.
<!-- trait TreeViewColumnExt::fn cell_get_size -->
Obtains the width and height needed to render the column. This is used
primarily by the `TreeView`.
## `cell_area`
The area a cell in the column will be allocated, or `None`
## `x_offset`
location to return x offset of a cell relative to `cell_area`, or `None`
## `y_offset`
location to return y offset of a cell relative to `cell_area`, or `None`
## `width`
location to return width needed to render a cell, or `None`
## `height`
location to return height needed to render a cell, or `None`
<!-- trait TreeViewColumnExt::fn cell_is_visible -->
Returns `true` if any of the cells packed into the `self` are visible.
For this to be meaningful, you must first initialize the cells with
`TreeViewColumnExt::cell_set_cell_data`

# Returns

`true`, if any of the cells packed into the `self` are currently visible
<!-- trait TreeViewColumnExt::fn cell_set_cell_data -->
Sets the cell renderer based on the `tree_model` and `iter`. That is, for
every attribute mapping in `self`, it will get a value from the set
column on the `iter`, and use that value to set the attribute on the cell
renderer. This is used primarily by the `TreeView`.
## `tree_model`
The `TreeModel` to to get the cell renderers attributes from.
## `iter`
The `TreeIter` to to get the cell renderer’s attributes from.
## `is_expander`
`true`, if the row has children
## `is_expanded`
`true`, if the row has visible children
<!-- trait TreeViewColumnExt::fn clear -->
Unsets all the mappings on all renderers on the `self`.
<!-- trait TreeViewColumnExt::fn clear_attributes -->
Clears all existing attributes previously set with
`TreeViewColumn::set_attributes`.
## `cell_renderer`
a `CellRenderer` to clear the attribute mapping on.
<!-- trait TreeViewColumnExt::fn clicked -->
Emits the “clicked” signal on the column. This function will only work if
`self` is clickable.
<!-- trait TreeViewColumnExt::fn focus_cell -->
Sets the current keyboard focus to be at `cell`, if the column contains
2 or more editable and activatable cells.
## `cell`
A `CellRenderer`
<!-- trait TreeViewColumnExt::fn get_alignment -->
Returns the current x alignment of `self`. This value can range
between 0.0 and 1.0.

# Returns

The current alignent of `self`.
<!-- trait TreeViewColumnExt::fn get_button -->
Returns the button used in the treeview column header

# Returns

The button for the column header.
<!-- trait TreeViewColumnExt::fn get_clickable -->
Returns `true` if the user can click on the header for the column.

# Returns

`true` if user can click the column header.
<!-- trait TreeViewColumnExt::fn get_expand -->
Returns `true` if the column expands to fill available space.

# Returns

`true` if the column expands to fill available space.
<!-- trait TreeViewColumnExt::fn get_fixed_width -->
Gets the fixed width of the column. This may not be the actual displayed
width of the column; for that, use `TreeViewColumnExt::get_width`.

# Returns

The fixed width of the column.
<!-- trait TreeViewColumnExt::fn get_max_width -->
Returns the maximum width in pixels of the `self`, or -1 if no maximum
width is set.

# Returns

The maximum width of the `self`.
<!-- trait TreeViewColumnExt::fn get_min_width -->
Returns the minimum width in pixels of the `self`, or -1 if no minimum
width is set.

# Returns

The minimum width of the `self`.
<!-- trait TreeViewColumnExt::fn get_reorderable -->
Returns `true` if the `self` can be reordered by the user.

# Returns

`true` if the `self` can be reordered by the user.
<!-- trait TreeViewColumnExt::fn get_resizable -->
Returns `true` if the `self` can be resized by the end user.

# Returns

`true`, if the `self` can be resized.
<!-- trait TreeViewColumnExt::fn get_sizing -->
Returns the current type of `self`.

# Returns

The type of `self`.
<!-- trait TreeViewColumnExt::fn get_sort_column_id -->
Gets the logical `sort_column_id` that the model sorts on when this
column is selected for sorting.
See `TreeViewColumnExt::set_sort_column_id`.

# Returns

the current `sort_column_id` for this column, or -1 if
 this column can’t be used for sorting.
<!-- trait TreeViewColumnExt::fn get_sort_indicator -->
Gets the value set by `TreeViewColumnExt::set_sort_indicator`.

# Returns

whether the sort indicator arrow is displayed
<!-- trait TreeViewColumnExt::fn get_sort_order -->
Gets the value set by `TreeViewColumnExt::set_sort_order`.

# Returns

the sort order the sort indicator is indicating
<!-- trait TreeViewColumnExt::fn get_spacing -->
Returns the spacing of `self`.

# Returns

the spacing of `self`.
<!-- trait TreeViewColumnExt::fn get_title -->
Returns the title of the widget.

# Returns

the title of the column. This string should not be
modified or freed.
<!-- trait TreeViewColumnExt::fn get_tree_view -->
Returns the `TreeView` wherein `self` has been inserted.
If `column` is currently not inserted in any tree view, `None` is
returned.

# Returns

The tree view wherein `column` has
 been inserted if any, `None` otherwise.
<!-- trait TreeViewColumnExt::fn get_visible -->
Returns `true` if `self` is visible.

# Returns

whether the column is visible or not. If it is visible, then
the tree will show the column.
<!-- trait TreeViewColumnExt::fn get_widget -->
Returns the `Widget` in the button on the column header.
If a custom widget has not been set then `None` is returned.

# Returns

The `Widget` in the column
 header, or `None`
<!-- trait TreeViewColumnExt::fn get_width -->
Returns the current size of `self` in pixels.

# Returns

The current width of `self`.
<!-- trait TreeViewColumnExt::fn get_x_offset -->
Returns the current X offset of `self` in pixels.

# Returns

The current X offset of `self`.
<!-- trait TreeViewColumnExt::fn pack_end -->
Adds the `cell` to end of the column. If `expand` is `false`, then the `cell`
is allocated no more space than it needs. Any unused space is divided
evenly between cells for which `expand` is `true`.
## `cell`
The `CellRenderer`.
## `expand`
`true` if `cell` is to be given extra space allocated to `self`.
<!-- trait TreeViewColumnExt::fn pack_start -->
Packs the `cell` into the beginning of the column. If `expand` is `false`, then
the `cell` is allocated no more space than it needs. Any unused space is divided
evenly between cells for which `expand` is `true`.
## `cell`
The `CellRenderer`.
## `expand`
`true` if `cell` is to be given extra space allocated to `self`.
<!-- trait TreeViewColumnExt::fn queue_resize -->
Flags the column, and the cell renderers added to this column, to have
their sizes renegotiated.
<!-- trait TreeViewColumnExt::fn set_alignment -->
Sets the alignment of the title or custom widget inside the column header.
The alignment determines its location inside the button -- 0.0 for left, 0.5
for center, 1.0 for right.
## `xalign`
The alignment, which is between [0.0 and 1.0] inclusive.
<!-- trait TreeViewColumnExt::fn set_attributes -->
Sets the attributes in the list as the attributes of `self`.
The attributes should be in attribute/column order, as in
`TreeViewColumn::add_attribute`. All existing attributes
are removed, and replaced with the new attributes.
## `cell_renderer`
the `CellRenderer` we’re setting the attributes of
<!-- trait TreeViewColumnExt::fn set_cell_data_func -->
Sets the ``GtkTreeCellDataFunc`` to use for the column. This
function is used instead of the standard attributes mapping for
setting the column value, and should set the value of `self`'s
cell renderer as appropriate. `func` may be `None` to remove an
older one.
## `cell_renderer`
A `CellRenderer`
## `func`
The ``GtkTreeCellDataFunc`` to use.
## `func_data`
The user data for `func`.
## `destroy`
The destroy notification for `func_data`
<!-- trait TreeViewColumnExt::fn set_clickable -->
Sets the header to be active if `clickable` is `true`. When the header is
active, then it can take keyboard focus, and can be clicked.
## `clickable`
`true` if the header is active.
<!-- trait TreeViewColumnExt::fn set_expand -->
Sets the column to take available extra space. This space is shared equally
amongst all columns that have the expand set to `true`. If no column has this
option set, then the last column gets all extra space. By default, every
column is created with this `false`.

Along with “fixed-width”, the “expand” property changes when the column is
resized by the user.
## `expand`
`true` if the column should expand to fill available space.
<!-- trait TreeViewColumnExt::fn set_fixed_width -->
If `fixed_width` is not -1, sets the fixed width of `self`; otherwise
unsets it. The effective value of `fixed_width` is clamped between the
minimum and maximum width of the column; however, the value stored in the
“fixed-width” property is not clamped. If the column sizing is
`TreeViewColumnSizing::GrowOnly` or `TreeViewColumnSizing::Autosize`, setting
a fixed width overrides the automatically calculated width. Note that
`fixed_width` is only a hint to GTK+; the width actually allocated to the
column may be greater or less than requested.

Along with “expand”, the “fixed-width” property changes when the column is
resized by the user.
## `fixed_width`
The new fixed width, in pixels, or -1.
<!-- trait TreeViewColumnExt::fn set_max_width -->
Sets the maximum width of the `self`. If `max_width` is -1, then the
maximum width is unset. Note, the column can actually be wider than max
width if it’s the last column in a view. In this case, the column expands to
fill any extra space.
## `max_width`
The maximum width of the column in pixels, or -1.
<!-- trait TreeViewColumnExt::fn set_min_width -->
Sets the minimum width of the `self`. If `min_width` is -1, then the
minimum width is unset.
## `min_width`
The minimum width of the column in pixels, or -1.
<!-- trait TreeViewColumnExt::fn set_reorderable -->
If `reorderable` is `true`, then the column can be reordered by the end user
dragging the header.
## `reorderable`
`true`, if the column can be reordered.
<!-- trait TreeViewColumnExt::fn set_resizable -->
If `resizable` is `true`, then the user can explicitly resize the column by
grabbing the outer edge of the column button. If resizable is `true` and
sizing mode of the column is `TreeViewColumnSizing::Autosize`, then the sizing
mode is changed to `TreeViewColumnSizing::GrowOnly`.
## `resizable`
`true`, if the column can be resized
<!-- trait TreeViewColumnExt::fn set_sizing -->
Sets the growth behavior of `self` to `type_`.
## `type_`
The `TreeViewColumnSizing`.
<!-- trait TreeViewColumnExt::fn set_sort_column_id -->
Sets the logical `sort_column_id` that this column sorts on when this column
is selected for sorting. Doing so makes the column header clickable.
## `sort_column_id`
The `sort_column_id` of the model to sort on.
<!-- trait TreeViewColumnExt::fn set_sort_indicator -->
Call this function with a `setting` of `true` to display an arrow in
the header button indicating the column is sorted. Call
`TreeViewColumnExt::set_sort_order` to change the direction of
the arrow.
## `setting`
`true` to display an indicator that the column is sorted
<!-- trait TreeViewColumnExt::fn set_sort_order -->
Changes the appearance of the sort indicator.

This does not actually sort the model. Use
`TreeViewColumnExt::set_sort_column_id` if you want automatic sorting
support. This function is primarily for custom sorting behavior, and should
be used in conjunction with `TreeSortable::set_sort_column_id` to do
that. For custom models, the mechanism will vary.

The sort indicator changes direction to indicate normal sort or reverse sort.
Note that you must have the sort indicator enabled to see anything when
calling this function; see `TreeViewColumnExt::set_sort_indicator`.
## `order`
sort order that the sort indicator should indicate
<!-- trait TreeViewColumnExt::fn set_spacing -->
Sets the spacing field of `self`, which is the number of pixels to
place between cell renderers packed into it.
## `spacing`
distance between cell renderers in pixels.
<!-- trait TreeViewColumnExt::fn set_title -->
Sets the title of the `self`. If a custom widget has been set, then
this value is ignored.
## `title`
The title of the `self`.
<!-- trait TreeViewColumnExt::fn set_visible -->
Sets the visibility of `self`.
## `visible`
`true` if the `self` is visible.
<!-- trait TreeViewColumnExt::fn set_widget -->
Sets the widget in the header to be `widget`. If widget is `None`, then the
header button is set with a `Label` set to the title of `self`.
## `widget`
A child `Widget`, or `None`.
<!-- trait TreeViewColumnExt::fn get_property_cell_area -->
The `CellArea` used to layout cell renderers for this column.

If no area is specified when creating the tree view column with `TreeViewColumn::new_with_area`
a horizontally oriented `CellAreaBox` will be used.
<!-- trait TreeViewColumnExt::fn set_property_cell_area -->
The `CellArea` used to layout cell renderers for this column.

If no area is specified when creating the tree view column with `TreeViewColumn::new_with_area`
a horizontally oriented `CellAreaBox` will be used.
<!-- trait TreeViewColumnExt::fn get_property_sort_column_id -->
Logical sort column ID this column sorts on when selected for sorting. Setting the sort column ID makes the column header
clickable. Set to -1 to make the column unsortable.
<!-- trait TreeViewColumnExt::fn set_property_sort_column_id -->
Logical sort column ID this column sorts on when selected for sorting. Setting the sort column ID makes the column header
clickable. Set to -1 to make the column unsortable.
<!-- enum TreeViewColumnSizing -->
The sizing method the column uses to determine its width. Please note
that `TreeViewColumnSizing::Autosize` are inefficient for large views, and
can make columns appear choppy.
<!-- enum TreeViewColumnSizing::variant GrowOnly -->
Columns only get bigger in reaction to changes in the model
<!-- enum TreeViewColumnSizing::variant Autosize -->
Columns resize to be the optimal size everytime the model changes.
<!-- enum TreeViewColumnSizing::variant Fixed -->
Columns are a fixed numbers of pixels wide.
<!-- enum TreeViewDropPosition -->
An enum for determining where a dropped row goes.
<!-- enum TreeViewDropPosition::variant Before -->
dropped row is inserted before
<!-- enum TreeViewDropPosition::variant After -->
dropped row is inserted after
<!-- enum TreeViewDropPosition::variant IntoOrBefore -->
dropped row becomes a child or is inserted before
<!-- enum TreeViewDropPosition::variant IntoOrAfter -->
dropped row becomes a child or is inserted after
<!-- enum TreeViewGridLines -->
Used to indicate which grid lines to draw in a tree view.
<!-- enum TreeViewGridLines::variant None -->
No grid lines.
<!-- enum TreeViewGridLines::variant Horizontal -->
Horizontal grid lines.
<!-- enum TreeViewGridLines::variant Vertical -->
Vertical grid lines.
<!-- enum TreeViewGridLines::variant Both -->
Horizontal and vertical grid lines.
<!-- enum Unit -->
See also `PrintSettings::set_paper_width`.
<!-- enum Unit::variant None -->
No units.
<!-- enum Unit::variant Points -->
Dimensions in points.
<!-- enum Unit::variant Inch -->
Dimensions in inches.
<!-- enum Unit::variant Mm -->
Dimensions in millimeters
<!-- struct Viewport -->
The `Viewport` widget acts as an adaptor class, implementing
scrollability for child widgets that lack their own scrolling
capabilities. Use `Viewport` to scroll child widgets such as
`Grid`, `Box`, and so on.

If a widget has native scrolling abilities, such as `TextView`,
`TreeView` or `IconView`, it can be added to a `ScrolledWindow`
with `ContainerExt::add`. If a widget does not, you must first add the
widget to a `Viewport`, then add the viewport to the scrolled window.
`ContainerExt::add` does this automatically if a child that does not
implement `Scrollable` is added to a `ScrolledWindow`, so you can
ignore the presence of the viewport.

The `Viewport` will start scrolling content only if allocated less
than the child widget’s minimum size in a given orientation.

# CSS nodes

`Viewport` has a single CSS node with name viewport.

# Implements

[`ViewportExt`](trait.ViewportExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ScrollableExt`](trait.ScrollableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait ViewportExt -->
Trait containing all `Viewport` methods.

# Implementors

[`Viewport`](struct.Viewport.html)
<!-- impl Viewport::fn new -->
Creates a new `Viewport` with the given adjustments, or with default
adjustments if none are given.
## `hadjustment`
horizontal adjustment
## `vadjustment`
vertical adjustment

# Returns

a new `Viewport`
<!-- trait ViewportExt::fn get_bin_window -->
Gets the bin window of the `Viewport`.

# Returns

a `gdk::Window`
<!-- trait ViewportExt::fn get_shadow_type -->
Gets the shadow type of the `Viewport`. See
`ViewportExt::set_shadow_type`.

# Returns

the shadow type
<!-- trait ViewportExt::fn get_view_window -->
Gets the view window of the `Viewport`.

# Returns

a `gdk::Window`
<!-- trait ViewportExt::fn set_shadow_type -->
Sets the shadow type of the viewport.
## `type_`
the new shadow type.
<!-- struct VolumeButton -->
`VolumeButton` is a subclass of `ScaleButton` that has
been tailored for use as a volume control widget with suitable
icons, tooltips and accessible labels.

# Implements

[`VolumeButtonExt`](trait.VolumeButtonExt.html), [`ScaleButtonExt`](trait.ScaleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`ActionableExt`](trait.ActionableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait VolumeButtonExt -->
Trait containing all `VolumeButton` methods.

# Implementors

[`VolumeButton`](struct.VolumeButton.html)
<!-- impl VolumeButton::fn new -->
Creates a `VolumeButton`, with a range between 0.0 and 1.0, with
a stepping of 0.02. Volume values can be obtained and modified using
the functions from `ScaleButton`.

# Returns

a new `VolumeButton`
<!-- trait VolumeButtonExt::fn get_property_use_symbolic -->
Whether to use symbolic icons as the icons. Note that
if the symbolic icons are not available in your installed
theme, then the normal (potentially colorful) icons will
be used.
<!-- trait VolumeButtonExt::fn set_property_use_symbolic -->
Whether to use symbolic icons as the icons. Note that
if the symbolic icons are not available in your installed
theme, then the normal (potentially colorful) icons will
be used.
<!-- struct Widget -->
`Widget` is the base class all widgets in GTK+ derive from. It manages the
widget lifecycle, states and style.

# Height-for-width Geometry Management # {`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 five virtual methods:

- `WidgetClass.get_request_mode`()
- `WidgetClass.get_preferred_width`()
- `WidgetClass.get_preferred_height`()
- `WidgetClass.get_preferred_height_for_width`()
- `WidgetClass.get_preferred_width_for_height`()
- `WidgetClass.get_preferred_height_and_baseline_for_width`()

There are some important things to keep in mind when implementing
height-for-width and when using it in container implementations.

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 `SizeRequestMode` chosen by the toplevel.

For example, when queried in the normal
`SizeRequestMode::HeightForWidth` mode:
First, the default minimum and natural width for each widget
in the interface will be computed using `WidgetExt::get_preferred_width`.
Because the preferred widths for each container 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
`WidgetExt::get_preferred_height_for_width`, which 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
(unless `GtkWindowExt::set_geometry_hints` is explicitly used instead).

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 `GtkWindowExt::set_default_size`). During the
recursive allocation process it’s important to note that request cycles
will be recursively executed while container widgets allocate their children.
Each container 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 `Widget` 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, `Widget` caches a small number of results
to avoid re-querying for the same sizes in one allocation cycle.

See
[`Container`’s geometry management section][container-geometry-management]
to learn more about how height-for-width allocations are performed
by container widgets.

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 `Label` that does height-for-width word wrapping
will not expect to have `WidgetClass.get_preferred_height`() 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 `SizeRequestMode::HeightForWidth` widget
generally deals with width-for-height requests, for `WidgetClass.get_preferred_height`()
it will do:


```C
static void
foo_widget_get_preferred_height (GtkWidget *widget,
                                 gint *min_height,
                                 gint *nat_height)
{
   if (i_am_in_height_for_width_mode)
     {
       gint min_width, nat_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           &min_width,
                                                           &nat_width);
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
                                                          (widget,
                                                           min_width,
                                                           min_height,
                                                           nat_height);
     }
   else
     {
        ... some widgets do both. For instance, if a GtkLabel is
        rotated to 90 degrees it will return the minimum and
        natural height for the rotated label here.
     }
}
```

And in `WidgetClass.get_preferred_width_for_height`() it will simply return
the minimum and natural width:

```C
static void
foo_widget_get_preferred_width_for_height (GtkWidget *widget,
                                           gint for_height,
                                           gint *min_width,
                                           gint *nat_width)
{
   if (i_am_in_height_for_width_mode)
     {
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           min_width,
                                                           nat_width);
     }
   else
     {
        ... again if a widget is sometimes operating in
        width-for-height mode (like a rotated GtkLabel) it can go
        ahead and do its real width for height calculation here.
     }
}
```

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 this:


```C
GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget,
                                                   &min,
                                                   &natural);
```

It will not work to use the wrapper functions, such as
`WidgetExt::get_preferred_width` inside your own size request
implementation. These return a request adjusted by `SizeGroup`
and by the `WidgetClass.adjust_size_request`() virtual method. 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.

Of course if you are getting the size request for
another widget, such as a child of a
container, you must use the wrapper APIs.
Otherwise, you would not properly consider widget margins,
`SizeGroup`, and so forth.

Since 3.10 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 `Align::Baseline`, and is inside a container
that supports baselines and has a natural “row” that it aligns to the baseline,
or a baseline assigned to it by the grandparent.

Baseline alignment support for a widget is done by the `WidgetClass.get_preferred_height_and_baseline_for_width`()
virtual function. It allows you to report a baseline in combination with the
minimum and natural height. If there is no baseline you can return -1 to indicate
this. The default implementation of this virtual function calls into the
`WidgetClass.get_preferred_height`() and `WidgetClass.get_preferred_height_for_width`(),
so if baselines are not supported it doesn’t need to be implemented.

If a widget ends up baseline aligned it will be allocated all the space in the parent
as if it was `Align::Fill`, but the selected baseline can be found via `WidgetExt::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.

# Style Properties

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

Use `WidgetClass::install_style_property` to install style properties for
a widget class, `WidgetClass::find_style_property` or
`WidgetClass::list_style_properties` to get information about existing
style properties and `WidgetExt::style_get_property`, `WidgetExt::style_get` or
`WidgetExt::style_get_valist` to obtain the value of a style property.

# `Widget` as `Buildable`

The `Widget` implementation of the `Buildable` interface supports a
custom `<accelerator>` element, which has attributes named ”key”, ”modifiers”
and ”signal” and allows to specify accelerators.

An example of a UI definition fragment specifying an accelerator:

```C
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 `WidgetExt::init_template` from the instance
initialization function:


```C
static void
foo_widget_init (FooWidget *self)
{
  // ...
  gtk_widget_init_template (GTK_WIDGET (self));
}
```

You can access widgets defined in the template using the
`WidgetExt::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.


```C
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.


```C
// 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);
}
```

# Implements

[`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait WidgetExt -->
Trait containing all `Widget` methods.

# Implementors

[`Actionable`](struct.Actionable.html), [`AppChooser`](struct.AppChooser.html), [`Calendar`](struct.Calendar.html), [`CellEditable`](struct.CellEditable.html), [`CellView`](struct.CellView.html), [`Container`](struct.Container.html), [`DrawingArea`](struct.DrawingArea.html), [`Entry`](struct.Entry.html), [`GLArea`](struct.GLArea.html), [`Invisible`](struct.Invisible.html), [`LevelBar`](struct.LevelBar.html), [`Misc`](struct.Misc.html), [`ProgressBar`](struct.ProgressBar.html), [`Range`](struct.Range.html), [`Separator`](struct.Separator.html), [`Spinner`](struct.Spinner.html), [`Switch`](struct.Switch.html), [`ToolShell`](struct.ToolShell.html), [`Widget`](struct.Widget.html)
<!-- impl Widget::fn new -->
This is a convenience function for creating a widget and setting
its properties in one go. For example you might write:
`gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign",
0.0, NULL)` to create a left-aligned label. Equivalent to
`gobject::Object::new`, but returns a widget so you don’t have to
cast the object yourself.
## `type_`
type ID of the widget to create
## `first_property_name`
name of first property to set

# Returns

a new `Widget` of type `widget_type`
<!-- impl Widget::fn get_default_direction -->
Obtains the current default reading direction. See
`Widget::set_default_direction`.

# Returns

the current default direction.
<!-- impl Widget::fn set_default_direction -->
Sets the default reading direction for widgets where the
direction has not been explicitly set by `WidgetExt::set_direction`.
## `dir`
the new default direction. This cannot be
 `TextDirection::None`.
<!-- trait WidgetExt::fn activate -->
For widgets that can be “activated” (buttons, menu items, etc.)
this function activates them. Activation is what happens when you
press Enter on a widget during key navigation. If `self` isn't
activatable, the function returns `false`.

# Returns

`true` if the widget was activatable
<!-- trait WidgetExt::fn add_accelerator -->
Installs an accelerator for this `self` in `accel_group` that causes
`accel_signal` to be emitted if the accelerator is activated.
The `accel_group` needs to be added to the widget’s toplevel via
`GtkWindowExt::add_accel_group`, and the signal must be of type `gobject::SignalFlags::Action`.
Accelerators added through this function are not user changeable during
runtime. If you want to support accelerators that can be changed by the
user, use `AccelMap::add_entry` and `WidgetExt::set_accel_path` or
`GtkMenuItemExt::set_accel_path` instead.
## `accel_signal`
widget signal to emit on accelerator activation
## `accel_group`
accel group for this widget, added to its toplevel
## `accel_key`
GDK keyval of the accelerator
## `accel_mods`
modifier key combination of the accelerator
## `accel_flags`
flag accelerators, e.g. `AccelFlags::Visible`
<!-- trait WidgetExt::fn add_device_events -->
Adds the device events in the bitfield `events` to the event mask for
`self`. See `WidgetExt::set_device_events` for details.
## `device`
a `gdk::Device`
## `events`
an event mask, see `gdk::EventMask`
<!-- trait WidgetExtManual::fn add_events -->
Adds the events in the bitfield `events` to the event mask for
`self`. See `Widget::set_events` and the
[input handling overview][event-masks] for details.
## `events`
an event mask, see `gdk::EventMask`
<!-- trait WidgetExt::fn add_mnemonic_label -->
Adds a widget to the list of mnemonic labels for
this widget. (See `WidgetExt::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 `Widget::destroy` signal or a weak notifier.
## `label`
a `Widget` that acts as a mnemonic label for `self`
<!-- trait WidgetExtManual::fn add_tick_callback -->
Queues an animation frame update and adds a callback to be called
before each frame. Until the tick callback is removed, it will be
called frequently (usually at the frame rate of the output device
or as quickly as the application can be repainted, whichever is
slower). For this reason, is most suitable for handling graphics
that change every frame or every few frames. The tick callback does
not automatically imply a relayout or repaint. If you want a
repaint or relayout, and aren’t changing widget properties that
would trigger that (for example, changing the text of a `Label`),
then you will have to call `WidgetExt::queue_resize` or
`WidgetExt::queue_draw_area` yourself.

`gdk::FrameClock::get_frame_time` should generally be used for timing
continuous animations and
`gdk::FrameTimings::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
`gdk::FrameClock::update` signal of `gdk::FrameClock`, since you don't
have to worry about when a `gdk::FrameClock` is assigned to a widget.
## `callback`
function to call for updating animations
## `user_data`
data to pass to `callback`
## `notify`
function to call to free `user_data` when the callback is removed.

# Returns

an id for the connection of this callback. Remove the callback
 by passing it to `Widget::remove_tick_callback`
<!-- trait WidgetExt::fn can_activate_accel -->
Determines whether an accelerator that activates the signal
identified by `signal_id` can currently be activated.
This is done by emitting the `Widget::can-activate-accel`
signal on `self`; if the signal isn’t overridden by a
handler or in a derived widget, then the default check is
that the widget must be sensitive, and the widget and all
its ancestors mapped.
## `signal_id`
the ID of a signal installed on `self`

# Returns

`true` if the accelerator can be activated.
<!-- trait WidgetExt::fn child_focus -->
This function is used by custom widget implementations; if you're
writing an app, you’d use `WidgetExt::grab_focus` to move the focus
to a particular widget, and `ContainerExt::set_focus_chain` to
change the focus tab order. So you may want to investigate those
functions instead.

`WidgetExt::child_focus` is called by containers as the user moves
around the window using keyboard shortcuts. `direction` indicates
what kind of motion is taking place (up, down, left, right, tab
forward, tab backward). `WidgetExt::child_focus` emits the
`Widget::focus` signal; widgets override the default handler
for this signal in order to implement appropriate focus behavior.

The default ::focus handler for a widget should return `true` if
moving in `direction` left the focus on a focusable location inside
that widget, and `false` if moving in `direction` moved the focus
outside the widget. If returning `true`, widgets normally
call `WidgetExt::grab_focus` to place the focus accordingly;
if returning `false`, they don’t modify the current focus location.
## `direction`
direction of focus movement

# Returns

`true` if focus ended up inside `self`
<!-- trait WidgetExt::fn child_notify -->
Emits a `Widget::child-notify` signal for the
[child property][child-properties] `child_property`
on `self`.

This is the analogue of `gobject::ObjectExt::notify` for child properties.

Also see `ContainerExt::child_notify`.
## `child_property`
the name of a child property installed on the
 class of `self`’s parent
<!-- trait WidgetExt::fn compute_expand -->
Computes whether a container should give this widget extra space
when possible. Containers should check this, rather than
looking at `WidgetExt::get_hexpand` or `WidgetExt::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.
## `orientation`
expand direction

# Returns

whether widget tree rooted here should be expanded
<!-- trait WidgetExt::fn create_pango_context -->
Creates a new `pango::Context` with the appropriate font map,
font options, font description, and base direction for drawing
text for this widget. See also `WidgetExt::get_pango_context`.

# Returns

the new `pango::Context`
<!-- trait WidgetExt::fn create_pango_layout -->
Creates a new `pango::Layout` with the appropriate font map,
font description, and base direction for drawing text for
this widget.

If you keep a `pango::Layout` created in this way around, you need
to re-create it when the widget `pango::Context` is replaced.
This can be tracked by using the `Widget::screen-changed` signal
on the widget.
## `text`
text to set on the layout (can be `None`)

# Returns

the new `pango::Layout`
<!-- trait WidgetExt::fn destroy -->
Destroys a widget.

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

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

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

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

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

See also: `ContainerExt::remove`
<!-- trait WidgetExt::fn destroyed -->
This function sets *`widget_pointer` to `None` if `widget_pointer` !=
`None`. It’s intended to be used as a callback connected to the
“destroy” signal of a widget. You connect `WidgetExt::destroyed`
as a signal handler, and pass the address of your widget variable
as user data. Then when the widget is destroyed, the variable will
be set to `None`. Useful for example to avoid multiple copies
of the same dialog.
## `widget_pointer`
address of a variable that contains `self`
<!-- trait WidgetExt::fn device_is_shadowed -->
Returns `true` if `device` has been shadowed by a GTK+
device grab on another widget, so it would stop sending
events to `self`. This may be used in the
`Widget::grab-notify` signal to check for specific
devices. See `gtk_device_grab_add`.
## `device`
a `gdk::Device`

# Returns

`true` if there is an ongoing grab on `device`
 by another `Widget` than `self`.
<!-- trait WidgetExt::fn drag_begin_with_coordinates -->
Initiates a drag on the source side. The function only needs to be used
when the application is starting drags itself, and is not needed when
`Widget::drag_source_set` is used.

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

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

1. During a `Widget::button-press-event` handler, if you want to start a drag
immediately when the user presses the mouse button. Pass the `event`
that you have in your `Widget::button-press-event` handler.

2. During a `Widget::motion-notify-event` handler, if you want to start a drag
when the mouse moves past a certain threshold distance after a button-press.
Pass the `event` that you have in your `Widget::motion-notify-event` handler.

3. During a timeout handler, if you want to start a drag after the mouse
button is held down for some time. Try to save the last event that you got
from the mouse, using `gdk_event_copy`, and pass it to this function
(remember to free the event with `gdk_event_free` when you are done).
If you really cannot pass a real event, pass `None` instead.
## `targets`
The targets (data formats) in which the
 source can provide the data
## `actions`
A bitmask of the allowed drag actions for this drag
## `button`
The button the user clicked to start the drag
## `event`
The event that triggered the start of the drag,
 or `None` if none can be obtained.
## `x`
The initial x coordinate to start dragging from, in the coordinate space
 of `self`. If -1 is passed, the coordinates are retrieved from `event` or
 the current pointer position
## `y`
The initial y coordinate to start dragging from, in the coordinate space
 of `self`. If -1 is passed, the coordinates are retrieved from `event` or
 the current pointer position

# Returns

the context for this drag
<!-- trait WidgetExt::fn drag_check_threshold -->
Checks to see if a mouse drag starting at (`start_x`, `start_y`) and ending
at (`current_x`, `current_y`) has passed the GTK+ drag threshold, and thus
should trigger the beginning of a drag-and-drop operation.
## `start_x`
X coordinate of start of drag
## `start_y`
Y coordinate of start of drag
## `current_x`
current X coordinate
## `current_y`
current Y coordinate

# Returns

`true` if the drag threshold has been passed.
<!-- trait WidgetExt::fn drag_dest_add_image_targets -->
Add the image targets supported by `SelectionData` to
the target list of the drag destination. The targets
are added with `info` = 0. If you need another value,
use `TargetList::add_image_targets` and
`WidgetExt::drag_dest_set_target_list`.
<!-- trait WidgetExt::fn drag_dest_add_text_targets -->
Add the text targets supported by `SelectionData` to
the target list of the drag destination. The targets
are added with `info` = 0. If you need another value,
use `TargetList::add_text_targets` and
`WidgetExt::drag_dest_set_target_list`.
<!-- trait WidgetExt::fn drag_dest_add_uri_targets -->
Add the URI targets supported by `SelectionData` to
the target list of the drag destination. The targets
are added with `info` = 0. If you need another value,
use `TargetList::add_uri_targets` and
`WidgetExt::drag_dest_set_target_list`.
<!-- trait WidgetExt::fn drag_dest_find_target -->
Looks for a match between the supported targets of `context` and the
`dest_target_list`, returning the first matching target, otherwise
returning `GDK_NONE`. `dest_target_list` should usually be the return
value from `WidgetExt::drag_dest_get_target_list`, but some widgets may
have different valid targets for different parts of the widget; in
that case, they will have to implement a drag_motion handler that
passes the correct target list to this function.
## `context`
drag context
## `target_list`
list of droppable targets, or `None` to use
 gtk_drag_dest_get_target_list (`self`).

# Returns

first target that the source offers
 and the dest can accept, or `GDK_NONE`
<!-- trait WidgetExt::fn drag_dest_get_target_list -->
Returns the list of targets this widget can accept from
drag-and-drop.

# Returns

the `TargetList`, or `None` if none
<!-- trait WidgetExt::fn drag_dest_get_track_motion -->
Returns whether the widget has been configured to always
emit `Widget::drag-motion` signals.

# Returns

`true` if the widget always emits
 `Widget::drag-motion` events
<!-- trait WidgetExtManual::fn drag_dest_set -->
Sets a widget as a potential drop destination, and adds default behaviors.

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

Things become more complicated when you try to preview the dragged data,
as described in the documentation for `Widget::drag-motion`. The default
behaviors described by `flags` make some assumptions, that can conflict
with your own signal handlers. For instance `DestDefaults::Drop` causes
invokations of `gdk_drag_status` in the context of `Widget::drag-motion`,
and invokations of `gtk_drag_finish` in `Widget::drag-data-received`.
Especially the later is dramatic, when your own `Widget::drag-motion`
handler calls `WidgetExt::drag_get_data` to inspect the dragged data.

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

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

  gdk_window_get_pointer (gtk_widget_get_window (widget),
                          NULL, NULL, &mask);
  if (mask & GDK_CONTROL_MASK)
    gdk_drag_status (context, GDK_ACTION_COPY, time);
  else
    gdk_drag_status (context, GDK_ACTION_MOVE, time);
}
```
## `flags`
which types of default drag behavior to use
## `targets`
a pointer to an array of
 ``GtkTargetEntrys`` indicating the drop types that this `self` will
 accept, or `None`. Later you can access the list with
 `WidgetExt::drag_dest_get_target_list` and `WidgetExt::drag_dest_find_target`.
## `n_targets`
the number of entries in `targets`
## `actions`
a bitmask of possible actions for a drop onto this `self`.
<!-- trait WidgetExt::fn drag_dest_set_proxy -->
Sets this widget as a proxy for drops to another window.

# Deprecated since 3.22

## `proxy_window`
the window to which to forward drag events
## `protocol`
the drag protocol which the `proxy_window` accepts
 (You can use `gdk_drag_get_protocol` to determine this)
## `use_coordinates`
If `true`, send the same coordinates to the
 destination, because it is an embedded
 subwindow.
<!-- trait WidgetExt::fn drag_dest_set_target_list -->
Sets the target types that this widget can accept from drag-and-drop.
The widget must first be made into a drag destination with
`Widget::drag_dest_set`.
## `target_list`
list of droppable targets, or `None` for none
<!-- trait WidgetExt::fn drag_dest_set_track_motion -->
Tells the widget to emit `Widget::drag-motion` and
`Widget::drag-leave` events regardless of the targets and the
`DestDefaults::Motion` flag.

This may be used when a widget wants to do generic
actions regardless of the targets that the source offers.
## `track_motion`
whether to accept all targets
<!-- trait WidgetExt::fn drag_dest_unset -->
Clears information about a drop destination set with
`Widget::drag_dest_set`. The widget will no longer receive
notification of drags.
<!-- trait WidgetExt::fn drag_get_data -->
Gets the data associated with a drag. When the data
is received or the retrieval fails, GTK+ will emit a
`Widget::drag-data-received` signal. Failure of the retrieval
is indicated by the length field of the `selection_data`
signal parameter being negative. However, when `WidgetExt::drag_get_data`
is called implicitely because the `DestDefaults::Drop` was set,
then the widget will not receive notification of failed
drops.
## `context`
the drag context
## `target`
the target (form of the data) to retrieve
## `time_`
a timestamp for retrieving the data. This will
 generally be the time received in a `Widget::drag-motion`
 or `Widget::drag-drop` signal
<!-- trait WidgetExt::fn drag_highlight -->
Highlights a widget as a currently hovered drop target.
To end the highlight, call `WidgetExt::drag_unhighlight`.
GTK+ calls this automatically if `DestDefaults::Highlight` is set.
<!-- trait WidgetExt::fn drag_source_add_image_targets -->
Add the writable image targets supported by `SelectionData` to
the target list of the drag source. The targets
are added with `info` = 0. If you need another value,
use `TargetList::add_image_targets` and
`WidgetExt::drag_source_set_target_list`.
<!-- trait WidgetExt::fn drag_source_add_text_targets -->
Add the text targets supported by `SelectionData` to
the target list of the drag source. The targets
are added with `info` = 0. If you need another value,
use `TargetList::add_text_targets` and
`WidgetExt::drag_source_set_target_list`.
<!-- trait WidgetExt::fn drag_source_add_uri_targets -->
Add the URI targets supported by `SelectionData` to
the target list of the drag source. The targets
are added with `info` = 0. If you need another value,
use `TargetList::add_uri_targets` and
`WidgetExt::drag_source_set_target_list`.
<!-- trait WidgetExt::fn drag_source_get_target_list -->
Gets the list of targets this widget can provide for
drag-and-drop.

# Returns

the `TargetList`, or `None` if none
<!-- trait WidgetExtManual::fn drag_source_set -->
Sets up a widget so that GTK+ will start a drag operation when the user
clicks and drags on the widget. The widget must have a window.
## `start_button_mask`
the bitmask of buttons that can start the drag
## `targets`
the table of targets
 that the drag will support, may be `None`
## `n_targets`
the number of items in `targets`
## `actions`
the bitmask of possible actions for a drag from this widget
<!-- trait WidgetExt::fn drag_source_set_icon_gicon -->
Sets the icon that will be used for drags from a particular source
to `icon`. See the docs for `IconTheme` for more details.
## `icon`
A `gio::Icon`
<!-- trait WidgetExt::fn drag_source_set_icon_name -->
Sets the icon that will be used for drags from a particular source
to a themed icon. See the docs for `IconTheme` for more details.
## `icon_name`
name of icon to use
<!-- trait WidgetExt::fn drag_source_set_icon_pixbuf -->
Sets the icon that will be used for drags from a particular widget
from a `gdk_pixbuf::Pixbuf`. GTK+ retains a reference for `pixbuf` and will
release it when it is no longer needed.
## `pixbuf`
the `gdk_pixbuf::Pixbuf` for the drag icon
<!-- trait WidgetExt::fn drag_source_set_target_list -->
Changes the target types that this widget offers for drag-and-drop.
The widget must first be made into a drag source with
`Widget::drag_source_set`.
## `target_list`
list of draggable targets, or `None` for none
<!-- trait WidgetExt::fn drag_source_unset -->
Undoes the effects of `Widget::drag_source_set`.
<!-- trait WidgetExt::fn drag_unhighlight -->
Removes a highlight set by `WidgetExt::drag_highlight` from
a widget.
<!-- trait WidgetExt::fn draw -->
Draws `self` to `cr`. The top left corner of the widget will be
drawn to the currently set origin point of `cr`.

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

Note that special-purpose widgets may contain special code for
rendering to the screen and might appear differently on screen
and when rendered using `WidgetExt::draw`.
## `cr`
a cairo context to draw to
<!-- trait WidgetExt::fn error_bell -->
Notifies the user about an input-related error on this widget.
If the `Settings:gtk-error-bell` setting is `true`, it calls
`gdk::WindowExt::beep`, otherwise it does nothing.

Note that the effect of `gdk::WindowExt::beep` can be configured in many
ways, depending on the windowing backend and the desktop environment
or window manager that is used.
<!-- trait WidgetExt::fn event -->
Rarely-used function. This function is used to emit
the event signals on a widget (those signals should never
be emitted without using this function to do so).
If you want to synthesize an event though, don’t use this function;
instead, use `gtk_main_do_event` so the event will behave as if
it were in the event queue. Don’t synthesize expose events; instead,
use `gdk::WindowExt::invalidate_rect` to invalidate a region of the
window.
## `event`
a ``GdkEvent``

# Returns

return from the event signal emission (`true` if
 the event was handled)
<!-- trait WidgetExt::fn freeze_child_notify -->
Stops emission of `Widget::child-notify` signals on `self`. The
signals are queued until `WidgetExt::thaw_child_notify` is called
on `self`.

This is the analogue of `gobject::ObjectExt::freeze_notify` for child properties.
<!-- trait WidgetExt::fn get_accessible -->
Returns the accessible object that describes the widget to an
assistive technology.

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

The documentation of the
[ATK](http://developer.gnome.org/atk/stable/)
library contains more information about accessible objects and their uses.

# Returns

the `atk::Object` associated with `self`
<!-- trait WidgetExt::fn get_action_group -->
Retrieves the `gio::ActionGroup` that was registered using `prefix`. The resulting
`gio::ActionGroup` may have been registered to `self` or any `Widget` in its
ancestry.

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

Feature: `v3_16`

## `prefix`
The “prefix” of the action group.

# Returns

A `gio::ActionGroup` or `None`.
<!-- trait WidgetExt::fn get_allocated_baseline -->
Returns the baseline that has currently been allocated to `self`.
This function is intended to be used when implementing handlers
for the `Widget::draw` function, and when allocating child
widgets in `Widget::size_allocate`.

# Returns

the baseline of the `self`, or -1 if none
<!-- trait WidgetExt::fn get_allocated_height -->
Returns the height that has currently been allocated to `self`.
This function is intended to be used when implementing handlers
for the `Widget::draw` function.

# Returns

the height of the `self`
<!-- trait WidgetExt::fn get_allocated_size -->
Retrieves the widget’s allocated size.

This function returns the last values passed to
`WidgetExt::size_allocate_with_baseline`. The value differs from
the size returned in `WidgetExt::get_allocation` in that functions
like `WidgetExt::set_halign` can adjust the allocation, but not
the value returned by this function.

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

Feature: `v3_20`

## `allocation`
a pointer to a `Allocation` to copy to
## `baseline`
a pointer to an integer to copy to
<!-- trait WidgetExt::fn get_allocated_width -->
Returns the width that has currently been allocated to `self`.
This function is intended to be used when implementing handlers
for the `Widget::draw` function.

# Returns

the width of the `self`
<!-- trait WidgetExt::fn get_allocation -->
Retrieves the widget’s allocation.

Note, when implementing a `Container`: a widget’s allocation will
be its “adjusted” allocation, that is, the widget’s parent
container typically calls `WidgetExt::size_allocate` with an
allocation, and that allocation is then adjusted (to handle margin
and alignment for example) before assignment to the widget.
`WidgetExt::get_allocation` returns the adjusted allocation that
was actually assigned to the widget. The adjusted allocation is
guaranteed to be completely contained within the
`WidgetExt::size_allocate` allocation, however. So a `Container`
is guaranteed that its children stay inside the assigned bounds,
but not that they have exactly the bounds the container assigned.
There is no way to get the original allocation assigned by
`WidgetExt::size_allocate`, since it isn’t stored; if a container
implementation needs that information it will have to track it itself.
## `allocation`
a pointer to a `Allocation` to copy to
<!-- trait WidgetExt::fn get_ancestor -->
Gets the first ancestor of `self` with type `widget_type`. For example,
`gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets
the first `Box` that’s an ancestor of `self`. No reference will be
added to the returned widget; it should not be unreferenced. See note
about checking for a toplevel `Window` in the docs for
`WidgetExt::get_toplevel`.

Note that unlike `WidgetExt::is_ancestor`, `WidgetExt::get_ancestor`
considers `self` to be an ancestor of itself.
## `widget_type`
ancestor type

# Returns

the ancestor widget, or `None` if not found
<!-- trait WidgetExt::fn get_app_paintable -->
Determines whether the application intends to draw on the widget in
an `Widget::draw` handler.

See `WidgetExt::set_app_paintable`

# Returns

`true` if the widget is app paintable
<!-- trait WidgetExt::fn get_can_default -->
Determines whether `self` can be a default widget. See
`WidgetExt::set_can_default`.

# Returns

`true` if `self` can be a default widget, `false` otherwise
<!-- trait WidgetExt::fn get_can_focus -->
Determines whether `self` can own the input focus. See
`WidgetExt::set_can_focus`.

# Returns

`true` if `self` can own the input focus, `false` otherwise
<!-- trait WidgetExt::fn get_child_visible -->
Gets the value set with `WidgetExt::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.

# Returns

`true` if the widget is mapped with the parent.
<!-- trait WidgetExt::fn get_clip -->
Retrieves the widget’s clip area.

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

Historically, in GTK+ the clip area has been equal to the allocation
retrieved via `WidgetExt::get_allocation`.
## `clip`
a pointer to a `Allocation` to copy to
<!-- trait WidgetExt::fn get_clipboard -->
Returns the clipboard object for the given selection to
be used with `self`. `self` must have a `gdk::Display`
associated with it, so must be attached to a toplevel
window.
## `selection`
a `gdk::Atom` which identifies the clipboard
 to use. `GDK_SELECTION_CLIPBOARD` gives the
 default clipboard. Another common value
 is `GDK_SELECTION_PRIMARY`, which gives
 the primary X selection.

# Returns

the appropriate clipboard object. If no
 clipboard already exists, a new one will
 be created. Once a clipboard object has
 been created, it is persistent for all time.
<!-- trait WidgetExt::fn get_device_enabled -->
Returns whether `device` can interact with `self` and its
children. See `WidgetExt::set_device_enabled`.
## `device`
a `gdk::Device`

# Returns

`true` is `device` is enabled for `self`
<!-- trait WidgetExt::fn get_device_events -->
Returns the events mask for the widget corresponding to an specific device. These
are the events that the widget will receive when `device` operates on it.
## `device`
a `gdk::Device`

# Returns

device event mask for `self`
<!-- trait WidgetExt::fn get_direction -->
Gets the reading direction for a particular widget. See
`WidgetExt::set_direction`.

# Returns

the reading direction for the widget.
<!-- trait WidgetExt::fn get_display -->
Get the `gdk::Display` for the toplevel window associated with
this widget. This function can only be called after the widget
has been added to a widget hierarchy with a `Window` at the top.

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

# Returns

the `gdk::Display` for the toplevel for this widget.
<!-- trait WidgetExt::fn get_double_buffered -->
Determines whether the widget is double buffered.

See `Widget::set_double_buffered`

# Returns

`true` if the widget is double buffered
<!-- trait WidgetExtManual::fn get_events -->
Returns the event mask (see `gdk::EventMask`) for the widget. These are the
events that the widget will receive.

Note: Internally, the widget event mask will be the logical OR of the event
mask set through `Widget::set_events` or `Widget::add_events`, and the
event mask necessary to cater for every `EventController` created for the
widget.

# Returns

event mask for `self`
<!-- trait WidgetExt::fn get_focus_on_click -->
Returns whether the widget should grab focus when it is clicked with the mouse.
See `WidgetExt::set_focus_on_click`.

Feature: `v3_20`


# Returns

`true` if the widget should grab focus when it is clicked with
 the mouse.
<!-- trait WidgetExt::fn get_font_map -->
Gets the font map that has been set with `WidgetExt::set_font_map`.

Feature: `v3_18`


# Returns

A `pango::FontMap`, or `None`
<!-- trait WidgetExt::fn get_font_options -->
Returns the `cairo::FontOptions` used for Pango rendering. When not set,
the defaults font options for the `gdk::Screen` will be used.

Feature: `v3_18`


# Returns

the `cairo::FontOptions` or `None` if not set
<!-- trait WidgetExt::fn get_frame_clock -->
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::FrameClock::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::FrameClock::get_frame_time`, and
then update the animation by calling
`gdk::FrameClock::get_frame_time` again during each repaint.

`gdk::FrameClock::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 `WidgetExt::queue_draw` which invalidates
the widget (thus scheduling it to receive a draw on the next
frame). `WidgetExt::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.

# Returns

a `gdk::FrameClock`,
or `None` if widget is unrealized
<!-- trait WidgetExt::fn get_halign -->
Gets the value of the `Widget:halign` property.

For backwards compatibility reasons this method will never return
`Align::Baseline`, but instead it will convert it to
`Align::Fill`. Baselines are not supported for horizontal
alignment.

# Returns

the horizontal alignment of `self`
<!-- trait WidgetExt::fn get_has_tooltip -->
Returns the current value of the has-tooltip property. See
`Widget:has-tooltip` for more information.

# Returns

current value of has-tooltip on `self`.
<!-- trait WidgetExt::fn get_has_window -->
Determines whether `self` has a `gdk::Window` of its own. See
`WidgetExt::set_has_window`.

# Returns

`true` if `self` has a window, `false` otherwise
<!-- trait WidgetExt::fn get_hexpand -->
Gets whether the widget would like any available extra horizontal
space. When a user resizes a `Window`, 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 `WidgetExt::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.

# Returns

whether hexpand flag is set
<!-- trait WidgetExt::fn get_hexpand_set -->
Gets whether `WidgetExt::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.

# Returns

whether hexpand has been explicitly set
<!-- trait WidgetExt::fn get_mapped -->
Whether the widget is mapped.

# Returns

`true` if the widget is mapped, `false` otherwise.
<!-- trait WidgetExt::fn get_margin_bottom -->
Gets the value of the `Widget:margin-bottom` property.

# Returns

The bottom margin of `self`
<!-- trait WidgetExt::fn get_margin_end -->
Gets the value of the `Widget:margin-end` property.

# Returns

The end margin of `self`
<!-- trait WidgetExt::fn get_margin_start -->
Gets the value of the `Widget:margin-start` property.

# Returns

The start margin of `self`
<!-- trait WidgetExt::fn get_margin_top -->
Gets the value of the `Widget:margin-top` property.

# Returns

The top margin of `self`
<!-- trait WidgetExt::fn get_modifier_mask -->
Returns the modifier mask the `self`’s windowing system backend
uses for a particular purpose.

See `gdk::Keymap::get_modifier_mask`.
## `intent`
the use case for the modifier mask

# Returns

the modifier mask used for `intent`.
<!-- trait WidgetExt::fn get_widget_name -->
Retrieves the name of a widget. See `WidgetExt::set_name` for the
significance of widget names.

# Returns

name of the widget. This string is owned by GTK+ and
should not be modified or freed
<!-- trait WidgetExt::fn get_no_show_all -->
Returns the current value of the `Widget:no-show-all` property,
which determines whether calls to `WidgetExt::show_all`
will affect this widget.

# Returns

the current value of the “no-show-all” property.
<!-- trait WidgetExt::fn get_opacity -->
Fetches the requested opacity for this widget.
See `WidgetExt::set_opacity`.

# Returns

the requested opacity for this widget.
<!-- trait WidgetExt::fn get_pango_context -->
Gets a `pango::Context` with the appropriate font map, font description,
and base direction for this widget. Unlike the context returned
by `WidgetExt::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 using the `Widget::screen-changed` signal on the widget.

# Returns

the `pango::Context` for the widget.
<!-- trait WidgetExt::fn get_parent -->
Returns the parent container of `self`.

# Returns

the parent container of `self`, or `None`
<!-- trait WidgetExt::fn get_parent_window -->
Gets `self`’s parent window, or `None` if it does not have one.

# Returns

the parent window of `self`, or `None`
if it does not have a parent window.
<!-- trait WidgetExt::fn get_path -->
Returns the `WidgetPath` representing `self`, if the widget
is not connected to a toplevel widget, a partial path will be
created.

# Returns

The `WidgetPath` representing `self`
<!-- trait WidgetExt::fn get_preferred_height -->
Retrieves a widget’s initial minimum and natural height.

This call is specific to width-for-height requests.

The returned request will be modified by the
`WidgetClass`::adjust_size_request virtual method and by any
``GtkSizeGroups`` that have been applied. That is, the returned request
is the one that should be used for layout, not necessarily the one
returned by the widget itself.
## `minimum_height`
location to store the minimum height, or `None`
## `natural_height`
location to store the natural height, or `None`
<!-- trait WidgetExt::fn get_preferred_height_and_baseline_for_width -->
Retrieves a widget’s minimum and natural height and the corresponding baselines if it would be given
the specified `width`, or the default height if `width` is -1. The baselines may be -1 which means
that no baseline is requested for this widget.

The returned request will be modified by the
`WidgetClass`::adjust_size_request and `WidgetClass`::adjust_baseline_request virtual methods
and by any ``GtkSizeGroups`` that have been applied. That is, the returned request
is the one that should be used for layout, not necessarily the one
returned by the widget itself.
## `width`
the width which is available for allocation, or -1 if none
## `minimum_height`
location for storing the minimum height, or `None`
## `natural_height`
location for storing the natural height, or `None`
## `minimum_baseline`
location for storing the baseline for the minimum height, or `None`
## `natural_baseline`
location for storing the baseline for the natural height, or `None`
<!-- trait WidgetExt::fn get_preferred_height_for_width -->
Retrieves a widget’s minimum and natural height if it would be given
the specified `width`.

The returned request will be modified by the
`WidgetClass`::adjust_size_request virtual method and by any
``GtkSizeGroups`` that have been applied. That is, the returned request
is the one that should be used for layout, not necessarily the one
returned by the widget itself.
## `width`
the width which is available for allocation
## `minimum_height`
location for storing the minimum height, or `None`
## `natural_height`
location for storing the natural height, or `None`
<!-- trait WidgetExt::fn get_preferred_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 `Layout`.

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 `WidgetExt::get_preferred_height_and_baseline_for_width` if you want to support
baseline alignment.
## `minimum_size`
location for storing the minimum size, or `None`
## `natural_size`
location for storing the natural size, or `None`
<!-- trait WidgetExt::fn get_preferred_width -->
Retrieves a widget’s initial minimum and natural width.

This call is specific to height-for-width requests.

The returned request will be modified by the
`WidgetClass`::adjust_size_request virtual method and by any
``GtkSizeGroups`` that have been applied. That is, the returned request
is the one that should be used for layout, not necessarily the one
returned by the widget itself.
## `minimum_width`
location to store the minimum width, or `None`
## `natural_width`
location to store the natural width, or `None`
<!-- trait WidgetExt::fn get_preferred_width_for_height -->
Retrieves a widget’s minimum and natural width if it would be given
the specified `height`.

The returned request will be modified by the
`WidgetClass`::adjust_size_request virtual method and by any
``GtkSizeGroups`` that have been applied. That is, the returned request
is the one that should be used for layout, not necessarily the one
returned by the widget itself.
## `height`
the height which is available for allocation
## `minimum_width`
location for storing the minimum width, or `None`
## `natural_width`
location for storing the natural width, or `None`
<!-- trait WidgetExt::fn get_realized -->
Determines whether `self` is realized.

# Returns

`true` if `self` is realized, `false` otherwise
<!-- trait WidgetExt::fn get_receives_default -->
Determines whether `self` is always treated as the default widget
within its toplevel when it has the focus, even if another widget
is the default.

See `WidgetExt::set_receives_default`.

# Returns

`true` if `self` acts as the default widget when focused,
 `false` otherwise
<!-- trait WidgetExt::fn get_request_mode -->
Gets whether the widget prefers a height-for-width layout
or a width-for-height layout.

`Bin` 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.

# Returns

The `SizeRequestMode` preferred by `self`.
<!-- trait WidgetExt::fn get_scale_factor -->
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).

See `gdk::WindowExt::get_scale_factor`.

# Returns

the scale factor for `self`
<!-- trait WidgetExt::fn get_screen -->
Get the `gdk::Screen` from the toplevel window associated with
this widget. This function can only be called after the widget
has been added to a widget hierarchy with a `Window`
at the top.

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

# Returns

the `gdk::Screen` for the toplevel for this widget.
<!-- trait WidgetExt::fn get_sensitive -->
Returns the widget’s sensitivity (in the sense of returning
the value that has been set using `WidgetExt::set_sensitive`).

The effective sensitivity of a widget is however determined by both its
own and its parent widget’s sensitivity. See `WidgetExt::is_sensitive`.

# Returns

`true` if the widget is sensitive
<!-- trait WidgetExt::fn get_settings -->
Gets the settings object holding the settings used for this widget.

Note that this function can only be called when the `Widget`
is attached to a toplevel, since the settings object is specific
to a particular `gdk::Screen`.

# Returns

the relevant `Settings` object
<!-- trait WidgetExt::fn get_size_request -->
Gets the size request that was explicitly set for the widget using
`WidgetExt::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
`WidgetExt::set_size_request`. To get the size a widget will
actually request, call `WidgetExt::get_preferred_size` instead of
this function.
## `width`
return location for width, or `None`
## `height`
return location for height, or `None`
<!-- trait WidgetExt::fn get_state_flags -->
Returns the widget state as a flag set. It is worth mentioning
that the effective `StateFlags::Insensitive` state will be
returned, that is, also based on parent insensitivity, even if
`self` itself is sensitive.

Also note that if you are looking for a way to obtain the
`StateFlags` to pass to a `StyleContext` method, you
should look at `StyleContextExt::get_state`.

# Returns

The state flags for widget
<!-- trait WidgetExt::fn get_style_context -->
Returns the style context associated to `self`. The returned object is
guaranteed to be the same for the lifetime of `self`.

# Returns

a `StyleContext`. This memory is owned by `self` and
 must not be freed.
<!-- trait WidgetExt::fn get_support_multidevice -->
Returns `true` if `self` is multiple pointer aware. See
`WidgetExt::set_support_multidevice` for more information.

# Returns

`true` if `self` is multidevice aware.
<!-- trait WidgetExt::fn get_template_child -->
Fetch an object build from the template XML for `widget_type` in this `self` instance.

This will only report children which were previously declared with
`WidgetClass::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.
## `widget_type`
The `glib::Type` to get a template child for
## `name`
The “id” of the child defined in the template XML

# Returns

The object built in the template XML with the id `name`
<!-- trait WidgetExt::fn get_tooltip_markup -->
Gets the contents of the tooltip for `self`.

# Returns

the tooltip text, or `None`. You should free the
 returned string with `g_free` when done.
<!-- trait WidgetExt::fn get_tooltip_text -->
Gets the contents of the tooltip for `self`.

# Returns

the tooltip text, or `None`. You should free the
 returned string with `g_free` when done.
<!-- trait WidgetExt::fn get_tooltip_window -->
Returns the `Window` of the current tooltip. This can be the
`Window` created by default, or the custom tooltip window set
using `WidgetExt::set_tooltip_window`.

# Returns

The `Window` of the current tooltip.
<!-- trait WidgetExt::fn get_toplevel -->
This function returns the topmost widget in the container hierarchy
`self` is a part of. If `self` has no parent widgets, it will be
returned as the topmost widget. No reference will be added to the
returned widget; it should not be unreferenced.

Note the difference in behavior vs. `WidgetExt::get_ancestor`;
`gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)`
would return
`None` if `self` wasn’t inside a toplevel window, and if the
window was inside a `Window`-derived widget which was in turn
inside the toplevel `Window`. While the second case may
seem unlikely, it actually happens when a `Plug` is embedded
inside a `Socket` within the same application.

To reliably find the toplevel `Window`, use
`WidgetExt::get_toplevel` and call GTK_IS_WINDOW()
on the result. For instance, to get the title of a widget's toplevel
window, one might use:

```C
static const char *
get_widget_toplevel_title (GtkWidget *widget)
{
  GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
  if (GTK_IS_WINDOW (toplevel))
    {
      return gtk_window_get_title (GTK_WINDOW (toplevel));
    }

  return NULL;
}
```

# Returns

the topmost ancestor of `self`, or `self` itself
 if there’s no ancestor.
<!-- trait WidgetExt::fn get_valign -->
Gets the value of the `Widget:valign` property.

For backwards compatibility reasons this method will never return
`Align::Baseline`, but instead it will convert it to
`Align::Fill`. If your widget want to support baseline aligned
children it must use `WidgetExt::get_valign_with_baseline`, or
`g_object_get (widget, "valign", &value, NULL)`, which will
also report the true value.

# Returns

the vertical alignment of `self`, ignoring baseline alignment
<!-- trait WidgetExt::fn get_valign_with_baseline -->
Gets the value of the `Widget:valign` property, including
`Align::Baseline`.

# Returns

the vertical alignment of `self`
<!-- trait WidgetExt::fn get_vexpand -->
Gets whether the widget would like any available extra vertical
space.

See `WidgetExt::get_hexpand` for more detail.

# Returns

whether vexpand flag is set
<!-- trait WidgetExt::fn get_vexpand_set -->
Gets whether `WidgetExt::set_vexpand` has been used to
explicitly set the expand flag on this widget.

See `WidgetExt::get_hexpand_set` for more detail.

# Returns

whether vexpand has been explicitly set
<!-- trait WidgetExt::fn get_visible -->
Determines whether the widget is visible. If you want to
take into account whether the widget’s parent is also marked as
visible, use `WidgetExt::is_visible` instead.

This function does not check if the widget is obscured in any way.

See `WidgetExt::set_visible`.

# Returns

`true` if the widget is visible
<!-- trait WidgetExt::fn get_visual -->
Gets the visual that will be used to render `self`.

# Returns

the visual for `self`
<!-- trait WidgetExt::fn get_window -->
Returns the widget’s window if it is realized, `None` otherwise

# Returns

`self`’s window.
<!-- trait WidgetExt::fn grab_add -->
Makes `self` the current grabbed widget.

This means that interaction with other widgets in the same
application is blocked and mouse as well as keyboard events
are delivered to this widget.

If `self` is not sensitive, it is not set as the current
grabbed widget and this function does nothing.
<!-- trait WidgetExt::fn grab_default -->
Causes `self` to become the default widget. `self` must be able to be
a default widget; typically you would ensure this yourself
by calling `WidgetExt::set_can_default` with a `true` value.
The default widget is activated when
the user presses Enter in a window. Default widgets must be
activatable, that is, `WidgetExt::activate` should affect them. Note
that `Entry` widgets require the “activates-default” property
set to `true` before they activate the default widget when Enter
is pressed and the `Entry` is focused.
<!-- trait WidgetExt::fn grab_focus -->
Causes `self` to have the keyboard focus for the `Window` it's
inside. `self` must be a focusable widget, such as a `Entry`;
something like `Frame` won’t work.

More precisely, it must have the `GTK_CAN_FOCUS` flag set. Use
`WidgetExt::set_can_focus` to modify that flag.

The widget also needs to be realized and mapped. This is indicated by the
related signals. Grabbing the focus immediately after creating the widget
will likely fail and cause critical warnings.
<!-- trait WidgetExt::fn grab_remove -->
Removes the grab from the given widget.

You have to pair calls to `WidgetExt::grab_add` and `WidgetExt::grab_remove`.

If `self` does not have the grab, this function does nothing.
<!-- trait WidgetExt::fn has_default -->
Determines whether `self` is the current default widget within its
toplevel. See `WidgetExt::set_can_default`.

# Returns

`true` if `self` is the current default widget within
 its toplevel, `false` otherwise
<!-- trait WidgetExt::fn has_focus -->
Determines if the widget has the global input focus. See
`WidgetExt::is_focus` for the difference between having the global
input focus, and only having the focus within a toplevel.

# Returns

`true` if the widget has the global input focus.
<!-- trait WidgetExt::fn has_grab -->
Determines whether the widget is currently grabbing events, so it
is the only widget receiving input events (keyboard and mouse).

See also `WidgetExt::grab_add`.

# Returns

`true` if the widget is in the grab_widgets stack
<!-- trait WidgetExt::fn has_screen -->
Checks whether there is a `gdk::Screen` is associated with
this widget. All toplevel widgets have an associated
screen, and all widgets added into a hierarchy with a toplevel
window at the top.

# Returns

`true` if there is a `gdk::Screen` associated
 with the widget.
<!-- trait WidgetExt::fn has_visible_focus -->
Determines if the widget should show a visible indication that
it has the global input focus. This is a convenience function for
use in ::draw handlers that takes into account whether focus
indication should currently be shown in the toplevel window of
`self`. See `GtkWindowExt::get_focus_visible` for more information
about focus indication.

To find out if the widget has the global input focus, use
`WidgetExt::has_focus`.

# Returns

`true` if the widget should display a “focus rectangle”
<!-- trait WidgetExt::fn hide -->
Reverses the effects of `WidgetExt::show`, causing the widget to be
hidden (invisible to the user).
<!-- trait WidgetExtManual::fn hide_on_delete -->
Utility function; intended to be connected to the `Widget::delete-event`
signal on a `Window`. The function calls `WidgetExt::hide` on its
argument, then returns `true`. If connected to ::delete-event, the
result is that clicking the close button for a window (on the
window frame, top right corner usually) will hide but not destroy
the window. By default, GTK+ destroys windows when ::delete-event
is received.

# Returns

`true`
<!-- trait WidgetExt::fn in_destruction -->
Returns whether the widget is currently being destroyed.
This information can sometimes be used to avoid doing
unnecessary work.

# Returns

`true` if `self` is being destroyed
<!-- trait WidgetExt::fn init_template -->
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 `WidgetClass::set_template`

It is important to call this function in the instance initializer
of a `Widget` subclass and not in `gobject::Object.constructed`() or
`gobject::Object.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 `gobject::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 `gobject::Object::new`
should take precedence over properties set in the private template XML.
<!-- trait WidgetExt::fn input_shape_combine_region -->
Sets an input shape for this widget’s GDK window. This allows for
windows which react to mouse click in a nonrectangular region, see
`gdk::WindowExt::input_shape_combine_region` for more information.
## `region`
shape to be added, or `None` to remove an existing shape
<!-- trait WidgetExt::fn insert_action_group -->
Inserts `group` into `self`. Children of `self` that implement
`Actionable` can then be associated with actions in `group` by
setting their “action-name” to
`prefix`.`action-name`.

If `group` is `None`, a previously inserted group for `name` is removed
from `self`.
## `name`
the prefix for actions in `group`
## `group`
a `gio::ActionGroup`, or `None`
<!-- trait WidgetExtManual::fn intersect -->
Computes the intersection of a `self`’s area and `area`, storing
the intersection in `intersection`, and returns `true` if there was
an intersection. `intersection` may be `None` if you’re only
interested in whether there was an intersection.
## `area`
a rectangle
## `intersection`
rectangle to store
 intersection of `self` and `area`

# Returns

`true` if there was an intersection
<!-- trait WidgetExt::fn is_ancestor -->
Determines whether `self` is somewhere inside `ancestor`, possibly with
intermediate containers.
## `ancestor`
another `Widget`

# Returns

`true` if `ancestor` contains `self` as a child,
 grandchild, great grandchild, etc.
<!-- trait WidgetExt::fn is_composited -->
Whether `self` can rely on having its alpha channel
drawn correctly. On X11 this function returns whether a
compositing manager is running for `self`’s screen.

Please note that the semantics of this call will change
in the future if used on a widget that has a composited
window in its hierarchy (as set by `gdk::WindowExt::set_composited`).

# Deprecated since 3.22

Use `gdk::Screen::is_composited` instead.

# Returns

`true` if the widget can rely on its alpha
channel being drawn correctly.
<!-- trait WidgetExt::fn is_drawable -->
Determines whether `self` can be drawn to. A widget can be drawn
to if it is mapped and visible.

# Returns

`true` if `self` is drawable, `false` otherwise
<!-- trait WidgetExt::fn is_focus -->
Determines if the widget is the focus widget within its
toplevel. (This does not mean that the `Widget:has-focus` property is
necessarily set; `Widget:has-focus` will only be set if the
toplevel widget additionally has the global input focus.)

# Returns

`true` if the widget is the focus widget.
<!-- trait WidgetExt::fn is_sensitive -->
Returns the widget’s effective sensitivity, which means
it is sensitive itself and also its parent widget is sensitive

# Returns

`true` if the widget is effectively sensitive
<!-- trait WidgetExt::fn is_toplevel -->
Determines whether `self` is a toplevel widget.

Currently only `Window` and `Invisible` (and out-of-process
``GtkPlugs``) are toplevel widgets. Toplevel widgets have no parent
widget.

# Returns

`true` if `self` is a toplevel, `false` otherwise
<!-- trait WidgetExt::fn is_visible -->
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 `WidgetExt::get_visible` and `WidgetExt::set_visible`

# Returns

`true` if the widget and all its parents are visible
<!-- trait WidgetExt::fn keynav_failed -->
This function should be called whenever keyboard navigation within
a single widget hits a boundary. The function emits the
`Widget::keynav-failed` signal on the widget and its return
value should be interpreted in a way similar to the return value of
`WidgetExt::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
`WidgetExt::child_focus` on the widget’s toplevel.

The default ::keynav-failed handler returns `false` for
`DirectionType::TabForward` and `DirectionType::TabBackward`. For the other
values of `DirectionType` it returns `true`.

Whenever the default handler returns `true`, it also calls
`WidgetExt::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
`Entry` 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.
## `direction`
direction of focus movement

# Returns

`true` if stopping keyboard navigation is fine, `false`
 if the emitting widget should try to handle the keyboard
 navigation attempt in its parent container(s).
<!-- trait WidgetExt::fn list_accel_closures -->
Lists the closures used by `self` for accelerator group connections
with `AccelGroup::connect_by_path` or `AccelGroup::connect`.
The closures can be used to monitor accelerator changes on `self`,
by connecting to the `AccelGroup::accel-changed` signal of the
`AccelGroup` of a closure which can be found out with
`AccelGroup::from_accel_closure`.

# Returns


 a newly allocated `glib::List` of closures
<!-- trait WidgetExt::fn list_action_prefixes -->
Retrieves a `None`-terminated array of strings containing the prefixes of
`gio::ActionGroup`'s available to `self`.

Feature: `v3_16`


# Returns

a `None`-terminated array of strings.
<!-- trait WidgetExt::fn list_mnemonic_labels -->
Returns a newly allocated list of the widgets, normally labels, for
which this widget is the target of a mnemonic (see for example,
`LabelExt::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.

# Returns

the list of
 mnemonic labels; free this list
 with `glib::List::free` when you are done with it.
<!-- trait WidgetExt::fn map -->
This function is only for use in widget implementations. Causes
a widget to be mapped if it isn’t already.
<!-- trait WidgetExt::fn mnemonic_activate -->
Emits the `Widget::mnemonic-activate` signal.
## `group_cycling`
`true` if there are other widgets with the same mnemonic

# Returns

`true` if the signal has been handled
<!-- trait WidgetExt::fn override_background_color -->
Sets the background color to use for a widget.

All other style values are left untouched.
See `WidgetExt::override_color`.

# Deprecated since 3.16

This function is not useful in the context of CSS-based
 rendering. If you wish to change the way a widget renders its background
 you should use a custom CSS style, through an application-specific
 `StyleProvider` and a CSS style class. You can also override the default
 drawing of a widget through the `Widget::draw` signal, and use Cairo to
 draw a specific color, regardless of the CSS style.
## `state`
the state for which to set the background color
## `color`
the color to assign, or `None` to undo the effect
 of previous calls to `WidgetExt::override_background_color`
<!-- trait WidgetExt::fn override_color -->
Sets the color to use for a widget.

All other style values are left untouched.

This function does not act recursively. Setting the color of a
container does not affect its children. Note that some widgets that
you may not think of as containers, for instance ``GtkButtons``,
are actually containers.

This API is mostly meant as a quick way for applications to
change a widget appearance. If you are developing a widgets
library and intend this change to be themeable, it is better
done by setting meaningful CSS classes in your
widget/container implementation through `StyleContextExt::add_class`.

This way, your widget library can install a `CssProvider`
with the `GTK_STYLE_PROVIDER_PRIORITY_FALLBACK` priority in order
to provide a default styling for those widgets that need so, and
this theming may fully overridden by the user’s theme.

Note that for complex widgets this may bring in undesired
results (such as uniform background color everywhere), in
these cases it is better to fully style such widgets through a
`CssProvider` with the `GTK_STYLE_PROVIDER_PRIORITY_APPLICATION`
priority.

# Deprecated since 3.16

Use a custom style provider and style classes instead
## `state`
the state for which to set the color
## `color`
the color to assign, or `None` to undo the effect
 of previous calls to `WidgetExt::override_color`
<!-- trait WidgetExt::fn override_cursor -->
Sets the cursor color to use in a widget, overriding the
cursor-color and secondary-cursor-color
style properties. All other style values are left untouched.
See also `Widget::modify_style`.

Note that the underlying properties have the `gdk::Color` type,
so the alpha value in `primary` and `secondary` will be ignored.

# Deprecated since 3.16

This function is not useful in the context of CSS-based
 rendering. If you wish to change the color used to render the primary
 and secondary cursors you should use a custom CSS style, through an
 application-specific `StyleProvider` and a CSS style class.
## `cursor`
the color to use for primary cursor (does not need to be
 allocated), or `None` to undo the effect of previous calls to
 of `WidgetExt::override_cursor`.
## `secondary_cursor`
the color to use for secondary cursor (does not
 need to be allocated), or `None` to undo the effect of previous
 calls to of `WidgetExt::override_cursor`.
<!-- trait WidgetExt::fn override_font -->
Sets the font to use for a widget. All other style values are
left untouched. See `WidgetExt::override_color`.

# Deprecated since 3.16

This function is not useful in the context of CSS-based
 rendering. If you wish to change the font a widget uses to render its text
 you should use a custom CSS style, through an application-specific
 `StyleProvider` and a CSS style class.
## `font_desc`
the font description to use, or `None` to undo
 the effect of previous calls to `WidgetExt::override_font`
<!-- trait WidgetExt::fn override_symbolic_color -->
Sets a symbolic color for a widget.

All other style values are left untouched.
See `WidgetExt::override_color` for overriding the foreground
or background color.

# Deprecated since 3.16

This function is not useful in the context of CSS-based
 rendering. If you wish to change the color used to render symbolic icons
 you should use a custom CSS style, through an application-specific
 `StyleProvider` and a CSS style class.
## `name`
the name of the symbolic color to modify
## `color`
the color to assign (does not need
 to be allocated), or `None` to undo the effect of previous
 calls to `WidgetExt::override_symbolic_color`
<!-- trait WidgetExt::fn queue_allocate -->
This function is only for use in widget implementations.

Flags the widget for a rerun of the `WidgetClass`::size_allocate
function. Use this function instead of `WidgetExt::queue_resize`
when the `self`'s size request didn't change but it wants to
reposition its contents.

An example user of this function is `WidgetExt::set_halign`.

Feature: `v3_20`

<!-- trait WidgetExt::fn queue_compute_expand -->
Mark `self` as needing to recompute its expand flags. Call
this function when setting legacy expand child properties
on the child of a container.

See `WidgetExt::compute_expand`.
<!-- trait WidgetExt::fn queue_draw -->
Equivalent to calling `WidgetExt::queue_draw_area` for the
entire area of a widget.
<!-- trait WidgetExt::fn queue_draw_area -->
Convenience function that calls `WidgetExt::queue_draw_region` on
the region created from the given coordinates.

The region here is specified in widget coordinates.
Widget coordinates are a bit odd; for historical reasons, they are
defined as `self`->window coordinates for widgets that return `true` for
`WidgetExt::get_has_window`, and are relative to `self`->allocation.x,
`self`->allocation.y otherwise.

`width` or `height` may be 0, in this case this function does
nothing. Negative values for `width` and `height` are not allowed.
## `x`
x coordinate of upper-left corner of rectangle to redraw
## `y`
y coordinate of upper-left corner of rectangle to redraw
## `width`
width of region to draw
## `height`
height of region to draw
<!-- trait WidgetExt::fn queue_draw_region -->
Invalidates the area of `self` defined by `region` by calling
`gdk::WindowExt::invalidate_region` on the widget’s window and all its
child windows. Once the main loop becomes idle (after the current
batch of events has been processed, roughly), the window will
receive expose events for the union of all regions that have been
invalidated.

Normally you would only use this function in widget
implementations. You might also use it to schedule a redraw of a
`DrawingArea` or some portion thereof.
## `region`
region to draw
<!-- trait WidgetExt::fn queue_resize -->
This function is only for use in widget implementations.
Flags a widget to have its size renegotiated; should
be called when a widget for some reason has a new size request.
For example, when you change the text in a `Label`, `Label`
queues a resize to ensure there’s enough space for the new text.

Note that you cannot call `WidgetExt::queue_resize` on a widget
from inside its implementation of the `WidgetClass`::size_allocate
virtual method. Calls to `WidgetExt::queue_resize` from inside
`WidgetClass`::size_allocate will be silently ignored.
<!-- trait WidgetExt::fn queue_resize_no_redraw -->
This function works like `WidgetExt::queue_resize`,
except that the widget is not invalidated.
<!-- trait WidgetExt::fn realize -->
Creates the GDK (windowing system) resources associated with a
widget. For example, `self`->window will be created when a widget
is realized. Normally realization happens implicitly; if you show
a widget and all its parent containers, then the widget will be
realized and mapped automatically.

Realizing a widget requires all
the widget’s parent widgets to be realized; calling
`WidgetExt::realize` realizes the widget’s parents in addition to
`self` 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
`Widget::draw`. Or simply g_signal_connect () to the
`Widget::realize` signal.
<!-- trait WidgetExt::fn register_window -->
Registers a `gdk::Window` with the widget and sets it up so that
the widget receives events for it. Call `WidgetExt::unregister_window`
when destroying the window.

Before 3.8 you needed to call `gdk::WindowExt::set_user_data` directly to set
this up. This is now deprecated and you should use `WidgetExt::register_window`
instead. Old code will keep working as is, although some new features like
transparency might not work perfectly.
## `window`
a `gdk::Window`
<!-- trait WidgetExt::fn remove_accelerator -->
Removes an accelerator from `self`, previously installed with
`WidgetExt::add_accelerator`.
## `accel_group`
accel group for this widget
## `accel_key`
GDK keyval of the accelerator
## `accel_mods`
modifier key combination of the accelerator

# Returns

whether an accelerator was installed and could be removed
<!-- trait WidgetExt::fn remove_mnemonic_label -->
Removes a widget from the list of mnemonic labels for
this widget. (See `WidgetExt::list_mnemonic_labels`). The widget
must have previously been added to the list with
`WidgetExt::add_mnemonic_label`.
## `label`
a `Widget` that was previously set as a mnemonic label for
 `self` with `WidgetExt::add_mnemonic_label`.
<!-- trait WidgetExt::fn remove_tick_callback -->
Removes a tick callback previously registered with
`Widget::add_tick_callback`.
## `id`
an id returned by `Widget::add_tick_callback`
<!-- trait WidgetExt::fn reset_style -->
Updates the style context of `self` and all descendants
by updating its widget path. ``GtkContainers`` may want
to use this on a child when reordering it in a way that a different
style might apply to it. See also `ContainerExt::get_path_for_child`.
<!-- trait WidgetExt::fn send_expose -->
Very rarely-used function. This function is used to emit
an expose event on a widget. This function is not normally used
directly. The only time it is used is when propagating an expose
event to a windowless child widget (`WidgetExt::get_has_window` is `false`),
and that is normally done using `ContainerExt::propagate_draw`.

If you want to force an area of a window to be redrawn,
use `gdk::WindowExt::invalidate_rect` or `gdk::WindowExt::invalidate_region`.
To cause the redraw to be done immediately, follow that call
with a call to `gdk::WindowExt::process_updates`.

# Deprecated since 3.22

Application and widget code should not handle
 expose events directly; invalidation should use the `Widget`
 API, and drawing should only happen inside `Widget::draw`
 implementations
## `event`
a expose ``GdkEvent``

# Returns

return from the event signal emission (`true` if
 the event was handled)
<!-- trait WidgetExt::fn send_focus_change -->
Sends the focus change `event` to `self`

This function is not meant to be used by applications. The only time it
should be used is when it is necessary for a `Widget` to assign focus
to a widget that is semantically owned by the first widget even though
it’s not a direct child - for instance, a search entry in a floating
window similar to the quick search in `TreeView`.

An example of its usage is:


```C
  GdkEvent *fevent = gdk_event_new (GDK_FOCUS_CHANGE);

  fevent->focus_change.type = GDK_FOCUS_CHANGE;
  fevent->focus_change.in = TRUE;
  fevent->focus_change.window = _gtk_widget_get_window (widget);
  if (fevent->focus_change.window != NULL)
    g_object_ref (fevent->focus_change.window);

  gtk_widget_send_focus_change (widget, fevent);

  gdk_event_free (event);
```
## `event`
a ``GdkEvent`` of type GDK_FOCUS_CHANGE

# Returns

the return value from the event signal emission: `true`
 if the event was handled, and `false` otherwise
<!-- trait WidgetExt::fn set_accel_path -->
Given an accelerator group, `accel_group`, and an accelerator path,
`accel_path`, sets up an accelerator in `accel_group` so whenever the
key binding that is defined for `accel_path` is pressed, `self`
will be activated. This removes any accelerators (for any
accelerator group) installed by previous calls to
`WidgetExt::set_accel_path`. Associating accelerators with
paths allows them to be modified by the user and the modifications
to be saved for future use. (See `AccelMap::save`.)

This function is a low level function that would most likely
be used by a menu creation system like `UIManager`. If you
use `UIManager`, setting up accelerator paths will be done
automatically.

Even when you you aren’t using `UIManager`, if you only want to
set up accelerators on menu items `GtkMenuItemExt::set_accel_path`
provides a somewhat more convenient interface.

Note that `accel_path` string will be stored in a `glib::Quark`. Therefore, if you
pass a static string, you can save some memory by interning it first with
`g_intern_static_string`.
## `accel_path`
path used to look up the accelerator
## `accel_group`
a `AccelGroup`.
<!-- trait WidgetExt::fn set_allocation -->
Sets the widget’s allocation. This should not be used
directly, but from within a widget’s size_allocate method.

The allocation set should be the “adjusted” or actual
allocation. If you’re implementing a `Container`, you want to use
`WidgetExt::size_allocate` instead of `WidgetExt::set_allocation`.
The `WidgetClass`::adjust_size_allocation virtual method adjusts the
allocation inside `WidgetExt::size_allocate` to create an adjusted
allocation.
## `allocation`
a pointer to a `Allocation` to copy from
<!-- trait WidgetExt::fn set_app_paintable -->
Sets whether the application intends to draw on the widget in
an `Widget::draw` handler.

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

Note that the background is still drawn when the widget is mapped.
## `app_paintable`
`true` if the application will paint on the widget
<!-- trait WidgetExt::fn set_can_default -->
Specifies whether `self` can be a default widget. See
`WidgetExt::grab_default` for details about the meaning of
“default”.
## `can_default`
whether or not `self` can be a default widget.
<!-- trait WidgetExt::fn set_can_focus -->
Specifies whether `self` can own the input focus. See
`WidgetExt::grab_focus` for actually setting the input focus on a
widget.
## `can_focus`
whether or not `self` can own the input focus.
<!-- trait WidgetExt::fn set_child_visible -->
Sets whether `self` should be mapped along with its when its parent
is mapped and `self` has been shown with `WidgetExt::show`.

The child visibility can be set for widget before it is added to
a container with `WidgetExt::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.
## `is_visible`
if `true`, `self` should be mapped along with its parent.
<!-- trait WidgetExt::fn set_clip -->
Sets the widget’s clip. This must not be used directly,
but from within a widget’s size_allocate method.
It must be called after `WidgetExt::set_allocation` (or after chaining up
to the parent class), because that function resets the clip.

The clip set should be the area that `self` draws on. If `self` is a
`Container`, the area must contain all children's clips.

If this function is not called by `self` during a ::size-allocate handler,
the clip will be set to `self`'s allocation.
## `clip`
a pointer to a `Allocation` to copy from
<!-- trait WidgetExt::fn set_device_enabled -->
Enables or disables a `gdk::Device` to interact with `self`
and all its children.

It does so by descending through the `gdk::Window` hierarchy
and enabling the same mask that is has for core events
(i.e. the one that `gdk::WindowExt::get_events` returns).
## `device`
a `gdk::Device`
## `enabled`
whether to enable the device
<!-- trait WidgetExt::fn set_device_events -->
Sets the device event mask (see `gdk::EventMask`) for a widget. The event
mask determines which events a widget will receive from `device`. Keep
in mind that different widgets have different default event masks, and by
changing the event mask you may disrupt a widget’s functionality,
so be careful. This function must be called while a widget is
unrealized. Consider `WidgetExt::add_device_events` for widgets that are
already realized, or if you want to preserve the existing event
mask. This function can’t be used with windowless widgets (which return
`false` from `WidgetExt::get_has_window`);
to get events on those widgets, place them inside a `EventBox`
and receive events on the event box.
## `device`
a `gdk::Device`
## `events`
event mask
<!-- trait WidgetExt::fn set_direction -->
Sets the reading direction on a particular widget. This direction
controls the primary direction for widgets containing text,
and also the direction in which the children of a container are
packed. The ability to set the direction is present in order
so that correct localization into languages with right-to-left
reading directions can be done. Generally, applications will
let the default reading direction present, except for containers
where the containers are arranged in an order that is explicitly
visual rather than logical (such as buttons for text justification).

If the direction is set to `TextDirection::None`, then the value
set by `Widget::set_default_direction` will be used.
## `dir`
the new direction
<!-- trait WidgetExtManual::fn set_events -->
Sets the event mask (see `gdk::EventMask`) for a widget. The event
mask determines which events a widget will receive. Keep in mind
that different widgets have different default event masks, and by
changing the event mask you may disrupt a widget’s functionality,
so be careful. This function must be called while a widget is
unrealized. Consider `Widget::add_events` for widgets that are
already realized, or if you want to preserve the existing event
mask. This function can’t be used with widgets that have no window.
(See `WidgetExt::get_has_window`). To get events on those widgets,
place them inside a `EventBox` and receive events on the event
box.
## `events`
event mask
<!-- trait WidgetExt::fn set_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.

Feature: `v3_20`

## `focus_on_click`
whether the widget should grab focus when clicked with the mouse
<!-- trait WidgetExt::fn set_font_map -->
Sets the font map to use for Pango rendering. When not set, the widget
will inherit the font map from its parent.

Feature: `v3_18`

## `font_map`
a `pango::FontMap`, or `None` to unset any previously
 set font map
<!-- trait WidgetExt::fn set_font_options -->
Sets the `cairo::FontOptions` used for Pango rendering in this widget.
When not set, the default font options for the `gdk::Screen` will be used.

Feature: `v3_18`

## `options`
a `cairo::FontOptions`, or `None` to unset any
 previously set default font options.
<!-- trait WidgetExt::fn set_halign -->
Sets the horizontal alignment of `self`.
See the `Widget:halign` property.
## `align`
the horizontal alignment
<!-- trait WidgetExt::fn set_has_tooltip -->
Sets the has-tooltip property on `self` to `has_tooltip`. See
`Widget:has-tooltip` for more information.
## `has_tooltip`
whether or not `self` has a tooltip.
<!-- trait WidgetExt::fn set_has_window -->
Specifies whether `self` has a `gdk::Window` of its own. Note that
all realized widgets have a non-`None` “window” pointer
(`WidgetExt::get_window` never returns a `None` window when a widget
is realized), but for many of them it’s actually the `gdk::Window` of
one of its parent widgets. Widgets that do not create a `window` for
themselves in `Widget::realize` must announce this by
calling this function with `has_window` = `false`.

This function should only be called by widget implementations,
and they should call it in their `init` function.
## `has_window`
whether or not `self` has a window.
<!-- trait WidgetExt::fn set_hexpand -->
Sets whether the widget would like any available extra horizontal
space. When a user resizes a `Window`, 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 `WidgetExt::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 `Widget`.).

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
`WidgetExt::set_hexpand` sets the hexpand-set property (see
`WidgetExt::set_hexpand_set`) which causes the widget’s hexpand
value to be used, rather than looking at children and widget state.
## `expand`
whether to expand
<!-- trait WidgetExt::fn set_hexpand_set -->
Sets whether the hexpand flag (see `WidgetExt::get_hexpand`) will
be used.

The hexpand-set property will be set automatically when you call
`WidgetExt::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.
## `set`
value for hexpand-set property
<!-- trait WidgetExt::fn set_mapped -->
Marks the widget as being mapped.

This function should only ever be called in a derived widget's
“map” or “unmap” implementation.
## `mapped`
`true` to mark the widget as mapped
<!-- trait WidgetExt::fn set_margin_bottom -->
Sets the bottom margin of `self`.
See the `Widget:margin-bottom` property.
## `margin`
the bottom margin
<!-- trait WidgetExt::fn set_margin_end -->
Sets the end margin of `self`.
See the `Widget:margin-end` property.
## `margin`
the end margin
<!-- trait WidgetExt::fn set_margin_start -->
Sets the start margin of `self`.
See the `Widget:margin-start` property.
## `margin`
the start margin
<!-- trait WidgetExt::fn set_margin_top -->
Sets the top margin of `self`.
See the `Widget:margin-top` property.
## `margin`
the top margin
<!-- trait WidgetExt::fn set_widget_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 `StyleContext`).

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.
## `name`
name for the widget
<!-- trait WidgetExt::fn set_no_show_all -->
Sets the `Widget:no-show-all` property, which determines whether
calls to `WidgetExt::show_all` will affect this widget.

This is mostly for use in constructing widget hierarchies with externally
controlled visibility, see `UIManager`.
## `no_show_all`
the new value for the “no-show-all” property
<!-- trait WidgetExt::fn set_opacity -->
Request the `self` to be rendered partially transparent,
with opacity 0 being fully transparent and 1 fully opaque. (Opacity values
are clamped to the [0,1] range.).
This works on both toplevel widget, and child widgets, although there
are some limitations:

For toplevel widgets this depends on the capabilities of the windowing
system. On X11 this has any effect only on X screens with a compositing manager
running. See `WidgetExt::is_composited`. On Windows it should work
always, although setting a window’s opacity after the window has been
shown causes it to flicker once on Windows.

For child widgets it doesn’t work if any affected widget has a native window, or
disables double buffering.
## `opacity`
desired opacity, between 0 and 1
<!-- trait WidgetExt::fn set_parent -->
This function is useful only when implementing subclasses of
`Container`.
Sets the container as the parent of `self`, and takes care of
some details such as updating the state and style of the child
to reflect its new location. The opposite function is
`WidgetExt::unparent`.
## `parent`
parent container
<!-- trait WidgetExt::fn set_parent_window -->
Sets a non default parent window for `self`.

For `Window` classes, setting a `parent_window` effects whether
the window is a toplevel window or can be embedded into other
widgets.

For `Window` classes, this needs to be called before the
window is realized.
## `parent_window`
the new parent window.
<!-- trait WidgetExt::fn set_realized -->
Marks the widget as being realized. This function must only be
called after all ``GdkWindows`` for the `self` have been created
and registered.

This function should only ever be called in a derived widget's
“realize” or “unrealize” implementation.
## `realized`
`true` to mark the widget as realized
<!-- trait WidgetExt::fn set_receives_default -->
Specifies whether `self` will be treated as the default widget
within its toplevel when it has the focus, even if another widget
is the default.

See `WidgetExt::grab_default` for details about the meaning of
“default”.
## `receives_default`
whether or not `self` can be a default widget.
<!-- trait WidgetExt::fn set_redraw_on_allocate -->
Sets whether the entire widget is queued for drawing when its size
allocation changes. By default, this setting is `true` and
the entire widget is redrawn on every size change. If your widget
leaves the upper left unchanged when made bigger, turning this
setting off will improve performance.

Note that for widgets where `WidgetExt::get_has_window` is `false`
setting this flag to `false` turns off all allocation on resizing:
the widget will not even redraw if its position changes; this is to
allow containers that don’t draw anything to avoid excess
invalidations. If you set this flag on a widget with no window that
does draw on `self`->window, you are
responsible for invalidating both the old and new allocation of the
widget when the widget is moved and responsible for invalidating
regions newly when the widget increases size.
## `redraw_on_allocate`
if `true`, the entire widget will be redrawn
 when it is allocated to a new size. Otherwise, only the
 new portion of the widget will be redrawn.
<!-- trait WidgetExt::fn set_sensitive -->
Sets the sensitivity of a widget. A widget is sensitive if the user
can interact with it. Insensitive widgets are “grayed out” and the
user can’t interact with them. Insensitive widgets are known as
“inactive”, “disabled”, or “ghosted” in some other toolkits.
## `sensitive`
`true` to make the widget sensitive
<!-- trait WidgetExt::fn set_size_request -->
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, `GtkWindowExt::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,
`GtkWindowExt::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
`Widget` 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 `Widget`.
## `width`
width `self` should request, or -1 to unset
## `height`
height `self` should request, or -1 to unset
<!-- trait WidgetExt::fn set_state_flags -->
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 `StateFlags::DirLtr` and
`StateFlags::DirRtl` but ignores them. If you want to set the widget's
direction, use `WidgetExt::set_direction`.

It is worth mentioning that any other state than `StateFlags::Insensitive`,
will be propagated down to all non-internal children if `self` is a
`Container`, while `StateFlags::Insensitive` itself will be propagated
down to all `Container` children by different means than turning on the
state flag down the hierarchy, both `WidgetExt::get_state_flags` and
`WidgetExt::is_sensitive` will make use of these.
## `flags`
State flags to turn on
## `clear`
Whether to clear state before turning on `flags`
<!-- trait WidgetExt::fn set_support_multidevice -->
Enables or disables multiple pointer awareness. If this setting is `true`,
`self` will start receiving multiple, per device enter/leave events. Note
that if custom ``GdkWindows`` are created in `Widget::realize`,
`gdk::WindowExt::set_support_multidevice` will have to be called manually on them.
## `support_multidevice`
`true` to support input from multiple devices.
<!-- trait WidgetExt::fn set_tooltip_markup -->
Sets `markup` as the contents of the tooltip, which is marked up with
 the [Pango text markup language][PangoMarkupFormat].

This function will take care of setting `Widget:has-tooltip` to `true`
and of the default handler for the `Widget::query-tooltip` signal.

See also the `Widget:tooltip-markup` property and
`Tooltip::set_markup`.
## `markup`
the contents of the tooltip for `self`, or `None`
<!-- trait WidgetExt::fn set_tooltip_text -->
Sets `text` as the contents of the tooltip. This function will take
care of setting `Widget:has-tooltip` to `true` and of the default
handler for the `Widget::query-tooltip` signal.

See also the `Widget:tooltip-text` property and `Tooltip::set_text`.
## `text`
the contents of the tooltip for `self`
<!-- trait WidgetExt::fn set_tooltip_window -->
Replaces the default window used for displaying
tooltips with `custom_window`. GTK+ will take care of showing and
hiding `custom_window` at the right moment, to behave likewise as
the default tooltip window. If `custom_window` is `None`, the default
tooltip window will be used.
## `custom_window`
a `Window`, or `None`
<!-- trait WidgetExt::fn set_valign -->
Sets the vertical alignment of `self`.
See the `Widget:valign` property.
## `align`
the vertical alignment
<!-- trait WidgetExt::fn set_vexpand -->
Sets whether the widget would like any available extra vertical
space.

See `WidgetExt::set_hexpand` for more detail.
## `expand`
whether to expand
<!-- trait WidgetExt::fn set_vexpand_set -->
Sets whether the vexpand flag (see `WidgetExt::get_vexpand`) will
be used.

See `WidgetExt::set_hexpand_set` for more detail.
## `set`
value for vexpand-set property
<!-- trait WidgetExt::fn set_visible -->
Sets the visibility state of `self`. Note that setting this to
`true` doesn’t mean the widget is actually viewable, see
`WidgetExt::get_visible`.

This function simply calls `WidgetExt::show` or `WidgetExt::hide`
but is nicer to use when the visibility of the widget depends on
some condition.
## `visible`
whether the widget should be shown or not
<!-- trait WidgetExt::fn set_visual -->
Sets the visual that should be used for by widget and its children for
creating ``GdkWindows``. The visual must be on the same `gdk::Screen` as
returned by `WidgetExt::get_screen`, so handling the
`Widget::screen-changed` signal is necessary.

Setting a new `visual` will not cause `self` to recreate its windows,
so you should call this function before `self` is realized.
## `visual`
visual to be used or `None` to unset a previous one
<!-- trait WidgetExt::fn set_window -->
Sets a widget’s window. This function should only be used in a
widget’s `Widget::realize` implementation. The `window` passed is
usually either new window created with `gdk::Window::new`, or the
window of its parent widget as returned by
`WidgetExt::get_parent_window`.

Widgets must indicate whether they will create their own `gdk::Window`
by calling `WidgetExt::set_has_window`. This is usually done in the
widget’s `init` function.

Note that this function does not add any reference to `window`.
## `window`
a `gdk::Window`
<!-- trait WidgetExt::fn shape_combine_region -->
Sets a shape for this widget’s GDK window. This allows for
transparent windows etc., see `gdk::WindowExt::shape_combine_region`
for more information.
## `region`
shape to be added, or `None` to remove an existing shape
<!-- trait WidgetExt::fn show -->
Flags a widget to be displayed. Any widget that isn’t shown will
not appear on the screen. If you want to show all the widgets in a
container, it’s easier to call `WidgetExt::show_all` on the
container, instead of individually showing the widgets.

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

When a toplevel container is shown, it is immediately realized and
mapped; other shown widgets are realized and mapped when their
toplevel container is realized and mapped.
<!-- trait WidgetExt::fn show_all -->
Recursively shows a widget, and any child widgets (if the widget is
a container).
<!-- trait WidgetExt::fn show_now -->
Shows a widget. If the widget is an unmapped toplevel widget
(i.e. a `Window` that has not yet been shown), enter the main
loop and wait for the window to actually be mapped. Be careful;
because the main loop is running, anything can happen during
this function.
<!-- trait WidgetExt::fn size_allocate -->
This function is only used by `Container` subclasses, to assign a size
and position to their child widgets.

In this function, the allocation may be adjusted. It will be forced
to a 1x1 minimum size, and the adjust_size_allocation virtual
method on the child will be used to adjust the allocation. Standard
adjustments include removing the widget’s margins, and applying the
widget’s `Widget:halign` and `Widget:valign` properties.

For baseline support in containers you need to use `WidgetExt::size_allocate_with_baseline`
instead.
## `allocation`
position and size to be allocated to `self`
<!-- trait WidgetExt::fn size_allocate_with_baseline -->
This function is only used by `Container` subclasses, to assign a size,
position and (optionally) baseline to their child widgets.

In this function, the allocation and baseline may be adjusted. It
will be forced to a 1x1 minimum size, and the
adjust_size_allocation virtual and adjust_baseline_allocation
methods on the child will be used to adjust the allocation and
baseline. Standard adjustments include removing the widget's
margins, and applying the widget’s `Widget:halign` and
`Widget:valign` properties.

If the child widget does not have a valign of `Align::Baseline` the
baseline argument is ignored and -1 is used instead.
## `allocation`
position and size to be allocated to `self`
## `baseline`
The baseline of the child, or -1
<!-- trait WidgetExt::fn style_get -->
Gets the values of a multiple style properties of `self`.
## `first_property_name`
the name of the first property to get
<!-- trait WidgetExt::fn style_get_property -->
Gets the value of a style property of `self`.
## `property_name`
the name of a style property
## `value`
location to return the property value
<!-- trait WidgetExt::fn style_get_valist -->
Non-vararg variant of `WidgetExt::style_get`. Used primarily by language
bindings.
## `first_property_name`
the name of the first property to get
## `var_args`
a va_list of pairs of property names and
 locations to return the property values, starting with the location
 for `first_property_name`.
<!-- trait WidgetExt::fn thaw_child_notify -->
Reverts the effect of a previous call to `WidgetExt::freeze_child_notify`.
This causes all queued `Widget::child-notify` signals on `self` to be
emitted.
<!-- trait WidgetExt::fn translate_coordinates -->
Translate coordinates relative to `self`’s allocation to coordinates
relative to `dest_widget`’s allocations. In order to perform this
operation, both widgets must be realized, and must share a common
toplevel.
## `dest_widget`
a `Widget`
## `src_x`
X position relative to `self`
## `src_y`
Y position relative to `self`
## `dest_x`
location to store X position relative to `dest_widget`
## `dest_y`
location to store Y position relative to `dest_widget`

# Returns

`false` if either widget was not realized, or there
 was no common ancestor. In this case, nothing is stored in
 *`dest_x` and *`dest_y`. Otherwise `true`.
<!-- trait WidgetExt::fn trigger_tooltip_query -->
Triggers a tooltip query on the display where the toplevel of `self`
is located. See `Tooltip::trigger_tooltip_query` for more
information.
<!-- trait WidgetExt::fn unmap -->
This function is only for use in widget implementations. Causes
a widget to be unmapped if it’s currently mapped.
<!-- trait WidgetExt::fn unparent -->
This function is only for use in widget implementations.
Should be called by implementations of the remove method
on `Container`, to dissociate a child from the container.
<!-- trait WidgetExt::fn unrealize -->
This function is only useful in widget implementations.
Causes a widget to be unrealized (frees all GDK resources
associated with the widget, such as `self`->window).
<!-- trait WidgetExt::fn unregister_window -->
Unregisters a `gdk::Window` from the widget that was previously set up with
`WidgetExt::register_window`. You need to call this when the window is
no longer used by the widget, such as when you destroy it.
## `window`
a `gdk::Window`
<!-- trait WidgetExt::fn unset_state_flags -->
This function is for use in widget implementations. Turns off flag
values for the current widget state (insensitive, prelighted, etc.).
See `WidgetExt::set_state_flags`.
## `flags`
State flags to turn off
<!-- trait WidgetExt::fn connect_button_press_event -->
The ::button-press-event signal will be emitted when a button
(typically from a mouse) is pressed.

To receive this signal, the `gdk::Window` associated to the
widget needs to enable the `gdk::EventMask::ButtonPressMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventButton` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_button_release_event -->
The ::button-release-event signal will be emitted when a button
(typically from a mouse) is released.

To receive this signal, the `gdk::Window` associated to the
widget needs to enable the `gdk::EventMask::ButtonReleaseMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventButton` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_can_activate_accel -->
Determines whether an accelerator that activates the signal
identified by `signal_id` can currently be activated.
This signal is present to allow applications and derived
widgets to override the default `Widget` handling
for determining whether an accelerator can be activated.
## `signal_id`
the ID of a signal installed on `widget`

# Returns

`true` if the signal can be activated.
<!-- trait WidgetExt::fn connect_child_notify -->
The ::child-notify signal is emitted for each
[child property][child-properties] that has
changed on an object. The signal's detail holds the property name.
## `child_property`
the `gobject::ParamSpec` of the changed child property
<!-- trait WidgetExt::fn connect_composited_changed -->
The ::composited-changed signal is emitted when the composited
status of `widgets` screen changes.
See `gdk::Screen::is_composited`.

# Deprecated since 3.22

Use `gdk::Screen`::composited-changed instead.
<!-- trait WidgetExt::fn connect_configure_event -->
The ::configure-event signal will be emitted when the size, position or
stacking of the `widget`'s window has changed.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::StructureMask` mask. GDK will enable this mask
automatically for all new windows.
## `event`
the `gdk::EventConfigure` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_damage_event -->
Emitted when a redirected window belonging to `widget` gets drawn into.
The region/area members of the event shows what area of the redirected
drawable was drawn into.
## `event`
the `gdk::EventExpose` event

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_delete_event -->
The ::delete-event signal is emitted if a user requests that
a toplevel window is closed. The default handler for this signal
destroys the window. Connecting `Widget::hide_on_delete` to
this signal will cause the window to be hidden instead, so that
it can later be shown again without reconstructing it.
## `event`
the event which triggered this signal

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_destroy -->
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.
<!-- trait WidgetExt::fn connect_destroy_event -->
The ::destroy-event signal is emitted when a `gdk::Window` is destroyed.
You rarely get this signal, because most widgets disconnect themselves
from their window before they destroy it, so no widget owns the
window at destroy time.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::StructureMask` mask. GDK will enable this mask
automatically for all new windows.
## `event`
the event which triggered this signal

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_direction_changed -->
The ::direction-changed signal is emitted when the text direction
of a widget changes.
## `previous_direction`
the previous text direction of `widget`
<!-- trait WidgetExt::fn connect_drag_begin -->
The ::drag-begin signal is emitted on the drag source when a drag is
started. A typical reason to connect to this signal is to set up a
custom drag icon with e.g. `WidgetExt::drag_source_set_icon_pixbuf`.

Note that some widgets set up a drag icon in the default handler of
this signal, so you may have to use `g_signal_connect_after` to
override what the default handler did.
## `context`
the drag context
<!-- trait WidgetExt::fn connect_drag_data_delete -->
The ::drag-data-delete signal is emitted on the drag source when a drag
with the action `gdk::DragAction::Move` is successfully completed. The signal
handler is responsible for deleting the data that has been dropped. What
"delete" means depends on the context of the drag operation.
## `context`
the drag context
<!-- trait WidgetExt::fn connect_drag_data_get -->
The ::drag-data-get signal is emitted on the drag source when the drop
site requests the data which is dragged. It is the responsibility of
the signal handler to fill `data` with the data in the format which
is indicated by `info`. See `SelectionData::set` and
`SelectionData::set_text`.
## `context`
the drag context
## `data`
the `SelectionData` to be filled with the dragged data
## `info`
the info that has been registered with the target in the
 `TargetList`
## `time`
the timestamp at which the data was requested
<!-- trait WidgetExt::fn connect_drag_data_received -->
The ::drag-data-received signal is emitted on the drop site when the
dragged data has been received. If the data was received in order to
determine whether the drop will be accepted, the handler is expected
to call `gdk_drag_status` and not finish the drag.
If the data was received in response to a `Widget::drag-drop` signal
(and this is the last target to be received), the handler for this
signal is expected to process the received data and then call
`gtk_drag_finish`, setting the `success` parameter depending on
whether the data was processed successfully.

Applications must create some means to determine why the signal was emitted
and therefore whether to call `gdk_drag_status` or `gtk_drag_finish`.

The handler may inspect the selected action with
`gdk::DragContext::get_selected_action` before calling
`gtk_drag_finish`, e.g. to implement `gdk::DragAction::Ask` as
shown in the following example:

```C
void
drag_data_received (GtkWidget          *widget,
                    GdkDragContext     *context,
                    gint                x,
                    gint                y,
                    GtkSelectionData   *data,
                    guint               info,
                    guint               time)
{
  if ((data->length >= 0) && (data->format == 8))
    {
      GdkDragAction action;

      // handle data here

      action = gdk_drag_context_get_selected_action (context);
      if (action == GDK_ACTION_ASK)
        {
          GtkWidget *dialog;
          gint response;

          dialog = gtk_message_dialog_new (NULL,
                                           GTK_DIALOG_MODAL |
                                           GTK_DIALOG_DESTROY_WITH_PARENT,
                                           GTK_MESSAGE_INFO,
                                           GTK_BUTTONS_YES_NO,
                                           "Move the data ?\n");
          response = gtk_dialog_run (GTK_DIALOG (dialog));
          gtk_widget_destroy (dialog);

          if (response == GTK_RESPONSE_YES)
            action = GDK_ACTION_MOVE;
          else
            action = GDK_ACTION_COPY;
         }

      gtk_drag_finish (context, TRUE, action == GDK_ACTION_MOVE, time);
    }
  else
    gtk_drag_finish (context, FALSE, FALSE, time);
 }
```
## `context`
the drag context
## `x`
where the drop happened
## `y`
where the drop happened
## `data`
the received data
## `info`
the info that has been registered with the target in the
 `TargetList`
## `time`
the timestamp at which the data was received
<!-- trait WidgetExt::fn connect_drag_drop -->
The ::drag-drop signal is emitted on the drop site when the user drops
the data onto the widget. The signal handler must determine whether
the cursor position is in a drop zone or not. If it is not in a drop
zone, it returns `false` and no further processing is necessary.
Otherwise, the handler returns `true`. In this case, the handler must
ensure that `gtk_drag_finish` is called to let the source know that
the drop is done. The call to `gtk_drag_finish` can be done either
directly or in a `Widget::drag-data-received` handler which gets
triggered by calling `WidgetExt::drag_get_data` to receive the data for one
or more of the supported targets.
## `context`
the drag context
## `x`
the x coordinate of the current cursor position
## `y`
the y coordinate of the current cursor position
## `time`
the timestamp of the motion event

# Returns

whether the cursor position is in a drop zone
<!-- trait WidgetExt::fn connect_drag_end -->
The ::drag-end signal is emitted on the drag source when a drag is
finished. A typical reason to connect to this signal is to undo
things done in `Widget::drag-begin`.
## `context`
the drag context
<!-- trait WidgetExt::fn connect_drag_failed -->
The ::drag-failed signal is emitted on the drag source when a drag has
failed. The signal handler may hook custom code to handle a failed DnD
operation based on the type of error, it returns `true` is the failure has
been already handled (not showing the default "drag operation failed"
animation), otherwise it returns `false`.
## `context`
the drag context
## `result`
the result of the drag operation

# Returns

`true` if the failed drag operation has been already handled.
<!-- trait WidgetExt::fn connect_drag_leave -->
The ::drag-leave signal is emitted on the drop site when the cursor
leaves the widget. A typical reason to connect to this signal is to
undo things done in `Widget::drag-motion`, e.g. undo highlighting
with `WidgetExt::drag_unhighlight`.


Likewise, the `Widget::drag-leave` signal is also emitted before the
::drag-drop signal, for instance to allow cleaning up of a preview item
created in the `Widget::drag-motion` signal handler.
## `context`
the drag context
## `time`
the timestamp of the motion event
<!-- trait WidgetExt::fn connect_drag_motion -->
The ::drag-motion signal is emitted on the drop site when the user
moves the cursor over the widget during a drag. The signal handler
must determine whether the cursor position is in a drop zone or not.
If it is not in a drop zone, it returns `false` and no further processing
is necessary. Otherwise, the handler returns `true`. In this case, the
handler is responsible for providing the necessary information for
displaying feedback to the user, by calling `gdk_drag_status`.

If the decision whether the drop will be accepted or rejected can't be
made based solely on the cursor position and the type of the data, the
handler may inspect the dragged data by calling `WidgetExt::drag_get_data` and
defer the `gdk_drag_status` call to the `Widget::drag-data-received`
handler. Note that you must pass `DestDefaults::Drop`,
`DestDefaults::Motion` or `DestDefaults::All` to `Widget::drag_dest_set`
when using the drag-motion signal that way.

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

```C
static void
drag_motion (GtkWidget      *widget,
             GdkDragContext *context,
             gint            x,
             gint            y,
             guint           time)
{
  GdkAtom target;

  PrivateData *private_data = GET_PRIVATE_DATA (widget);

  if (!private_data->drag_highlight)
   {
     private_data->drag_highlight = 1;
     gtk_drag_highlight (widget);
   }

  target = gtk_drag_dest_find_target (widget, context, NULL);
  if (target == GDK_NONE)
    gdk_drag_status (context, 0, time);
  else
   {
     private_data->pending_status
        = gdk_drag_context_get_suggested_action (context);
     gtk_drag_get_data (widget, context, target, time);
   }

  return TRUE;
}

static void
drag_data_received (GtkWidget        *widget,
                    GdkDragContext   *context,
                    gint              x,
                    gint              y,
                    GtkSelectionData *selection_data,
                    guint             info,
                    guint             time)
{
  PrivateData *private_data = GET_PRIVATE_DATA (widget);

  if (private_data->suggested_action)
   {
     private_data->suggested_action = 0;

     // We are getting this data due to a request in drag_motion,
     // rather than due to a request in drag_drop, so we are just
     // supposed to call gdk_drag_status(), not actually paste in
     // the data.

     str = gtk_selection_data_get_text (selection_data);
     if (!data_is_acceptable (str))
       gdk_drag_status (context, 0, time);
     else
       gdk_drag_status (context,
                        private_data->suggested_action,
                        time);
   }
  else
   {
     // accept the drop
   }
}
```
## `context`
the drag context
## `x`
the x coordinate of the current cursor position
## `y`
the y coordinate of the current cursor position
## `time`
the timestamp of the motion event

# Returns

whether the cursor position is in a drop zone
<!-- trait WidgetExt::fn connect_draw -->
This signal is emitted when a widget is supposed to render itself.
The `widget`'s top left corner must be painted at the origin of
the passed in context and be sized to the values returned by
`WidgetExt::get_allocated_width` and
`WidgetExt::get_allocated_height`.

Signal handlers connected to this signal can modify the cairo
context passed as `cr` in any way they like and don't need to
restore it. The signal emission takes care of calling `cairo_save`
before and `cairo_restore` after invoking the handler.

The signal handler will get a `cr` with a clip region already set to the
widget's dirty region, i.e. to the area that needs repainting. Complicated
widgets that want to avoid redrawing themselves completely can get the full
extents of the clip region with `gdk_cairo_get_clip_rectangle`, or they can
get a finer-grained representation of the dirty region with
`cairo_copy_clip_rectangle_list`.
## `cr`
the cairo context to draw to

# Returns

`true` to stop other handlers from being invoked for the event.
`false` to propagate the event further.
<!-- trait WidgetExt::fn connect_enter_notify_event -->
The ::enter-notify-event will be emitted when the pointer enters
the `widget`'s window.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::EnterNotifyMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventCrossing` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_event -->
The GTK+ main loop will emit three signals for each GDK event delivered
to a widget: one generic ::event signal, another, more specific,
signal that matches the type of event delivered (e.g.
`Widget::key-press-event`) and finally a generic
`Widget::event-after` signal.
## `event`
the ``GdkEvent`` which triggered this signal

# Returns

`true` to stop other handlers from being invoked for the event
and to cancel the emission of the second specific ::event signal.
 `false` to propagate the event further and to allow the emission of
 the second signal. The ::event-after signal is emitted regardless of
 the return value.
<!-- trait WidgetExt::fn connect_event_after -->
After the emission of the `Widget::event` signal and (optionally)
the second more specific signal, ::event-after will be emitted
regardless of the previous two signals handlers return values.
## `event`
the ``GdkEvent`` which triggered this signal
<!-- trait WidgetExt::fn connect_focus -->

# Returns

`true` to stop other handlers from being invoked for the event. `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_focus_in_event -->
The ::focus-in-event signal will be emitted when the keyboard focus
enters the `widget`'s window.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::FocusChangeMask` mask.
## `event`
the `gdk::EventFocus` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_focus_out_event -->
The ::focus-out-event signal will be emitted when the keyboard focus
leaves the `widget`'s window.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::FocusChangeMask` mask.
## `event`
the `gdk::EventFocus` which triggered this
 signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_grab_broken_event -->
Emitted when a pointer or keyboard grab on a window belonging
to `widget` gets broken.

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

# Returns

`true` to stop other handlers from being invoked for
 the event. `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_grab_notify -->
The ::grab-notify signal is emitted when a widget becomes
shadowed by a GTK+ grab (not a pointer or keyboard grab) on
another widget, or when it becomes unshadowed due to a grab
being removed.

A widget is shadowed by a `WidgetExt::grab_add` when the topmost
grab widget in the grab stack of its window group is not
its ancestor.
## `was_grabbed`
`false` if the widget becomes shadowed, `true`
 if it becomes unshadowed
<!-- trait WidgetExt::fn connect_hide -->
The ::hide signal is emitted when `widget` is hidden, for example with
`WidgetExt::hide`.
<!-- trait WidgetExt::fn connect_hierarchy_changed -->
The ::hierarchy-changed signal is emitted when the
anchored state of a widget changes. A widget is
“anchored” when its toplevel
ancestor is a `Window`. This signal is emitted when
a widget changes from un-anchored to anchored or vice-versa.
## `previous_toplevel`
the previous toplevel ancestor, or `None`
 if the widget was previously unanchored
<!-- trait WidgetExt::fn connect_key_press_event -->
The ::key-press-event signal is emitted when a key is pressed. The signal
emission will reoccur at the key-repeat rate when the key is kept pressed.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::KeyPressMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventKey` which triggered this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_key_release_event -->
The ::key-release-event signal is emitted when a key is released.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::KeyReleaseMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventKey` which triggered this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_keynav_failed -->
Gets emitted if keyboard navigation fails.
See `WidgetExt::keynav_failed` for details.
## `direction`
the direction of movement

# Returns

`true` if stopping keyboard navigation is fine, `false`
 if the emitting widget should try to handle the keyboard
 navigation attempt in its parent container(s).
<!-- trait WidgetExt::fn connect_leave_notify_event -->
The ::leave-notify-event will be emitted when the pointer leaves
the `widget`'s window.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::LeaveNotifyMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventCrossing` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_map -->
The ::map signal is emitted when `widget` is going to be mapped, that is
when the widget is visible (which is controlled with
`WidgetExt::set_visible`) and all its parents up to the toplevel widget
are also visible. Once the map has occurred, `Widget::map-event` will
be emitted.

The ::map signal can be used to determine whether a widget will be drawn,
for instance it can resume an animation that was stopped during the
emission of `Widget::unmap`.
<!-- trait WidgetExtManual::fn connect_map_event -->
The ::map-event signal will be emitted when the `widget`'s window is
mapped. A window is mapped when it becomes visible on the screen.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::StructureMask` mask. GDK will enable this mask
automatically for all new windows.
## `event`
the `gdk::EventAny` which triggered this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_mnemonic_activate -->
The default handler for this signal activates `widget` if `group_cycling`
is `false`, or just makes `widget` grab focus if `group_cycling` is `true`.
## `group_cycling`
`true` if there are other widgets with the same mnemonic

# Returns

`true` to stop other handlers from being invoked for the event.
`false` to propagate the event further.
<!-- trait WidgetExt::fn connect_motion_notify_event -->
The ::motion-notify-event signal is emitted when the pointer moves
over the widget's `gdk::Window`.

To receive this signal, the `gdk::Window` associated to the widget
needs to enable the `gdk::EventMask::PointerMotionMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventMotion` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_parent_set -->
The ::parent-set signal is emitted when a new parent
has been set on a widget.
## `old_parent`
the previous parent, or `None` if the widget
 just got its initial parent.
<!-- trait WidgetExt::fn connect_popup_menu -->
This signal gets emitted whenever a widget should pop up a context
menu. This usually happens through the standard key binding mechanism;
by pressing a certain key while a widget is focused, the user can cause
the widget to pop up a menu. For example, the `Entry` widget creates
a menu with clipboard commands. See the
[Popup Menu Migration Checklist][checklist-popup-menu]
for an example of how to use this signal.

# Returns

`true` if a menu was activated
<!-- trait WidgetExt::fn connect_property_notify_event -->
The ::property-notify-event signal will be emitted when a property on
the `widget`'s window has been changed or deleted.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::PropertyChangeMask` mask.
## `event`
the `gdk::EventProperty` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_proximity_in_event -->
To receive this signal the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::ProximityInMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventProximity` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_proximity_out_event -->
To receive this signal the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::ProximityOutMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventProximity` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_query_tooltip -->
Emitted when `Widget: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.
## `x`
the x coordinate of the cursor position where the request has
 been emitted, relative to `widget`'s left side
## `y`
the y coordinate of the cursor position where the request has
 been emitted, relative to `widget`'s top
## `keyboard_mode`
`true` if the tooltip was triggered using the keyboard
## `tooltip`
a `Tooltip`

# Returns

`true` if `tooltip` should be shown right now, `false` otherwise.
<!-- trait WidgetExt::fn connect_realize -->
The ::realize signal is emitted when `widget` is associated with a
`gdk::Window`, which means that `WidgetExt::realize` has been called or the
widget has been mapped (that is, it is going to be drawn).
<!-- trait WidgetExt::fn connect_screen_changed -->
The ::screen-changed signal gets emitted when the
screen of a widget has changed.
## `previous_screen`
the previous screen, or `None` if the
 widget was not associated with a screen before
<!-- trait WidgetExt::fn connect_scroll_event -->
The ::scroll-event signal is emitted when a button in the 4 to 7
range is pressed. Wheel mice are usually configured to generate
button press events for buttons 4 and 5 when the wheel is turned.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::ScrollMask` mask.

This signal will be sent to the grab widget if there is one.
## `event`
the `gdk::EventScroll` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_selection_clear_event -->
The ::selection-clear-event signal will be emitted when the
the `widget`'s window has lost ownership of a selection.
## `event`
the `gdk::EventSelection` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_selection_notify_event -->

# Returns

`true` to stop other handlers from being invoked for the event. `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_selection_request_event -->
The ::selection-request-event signal will be emitted when
another client requests ownership of the selection owned by
the `widget`'s window.
## `event`
the `gdk::EventSelection` which triggered
 this signal.

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_show -->
The ::show signal is emitted when `widget` is shown, for example with
`WidgetExt::show`.
<!-- trait WidgetExt::fn connect_show_help -->

# Returns

`true` to stop other handlers from being invoked for the event.
`false` to propagate the event further.
<!-- trait WidgetExt::fn connect_size_allocate -->
## `allocation`
the region which has been
 allocated to the widget.
<!-- trait WidgetExt::fn connect_state_flags_changed -->
The ::state-flags-changed signal is emitted when the widget state
changes, see `WidgetExt::get_state_flags`.
## `flags`
The previous state flags.
<!-- trait WidgetExt::fn connect_style_updated -->
The ::style-updated signal is a convenience signal that is emitted when the
`StyleContext::changed` signal is emitted on the `widget`'s associated
`StyleContext` as returned by `WidgetExt::get_style_context`.

Note that style-modifying functions like `WidgetExt::override_color` also
cause this signal to be emitted.
<!-- trait WidgetExt::fn connect_unmap -->
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.
<!-- trait WidgetExtManual::fn connect_unmap_event -->
The ::unmap-event signal will be emitted when the `widget`'s window is
unmapped. A window is unmapped when it becomes invisible on the screen.

To receive this signal, the `gdk::Window` associated to the widget needs
to enable the `gdk::EventMask::StructureMask` mask. GDK will enable this mask
automatically for all new windows.
## `event`
the `gdk::EventAny` which triggered this signal

# Returns

`true` to stop other handlers from being invoked for the event.
 `false` to propagate the event further.
<!-- trait WidgetExt::fn connect_unrealize -->
The ::unrealize signal is emitted when the `gdk::Window` associated with
`widget` is destroyed, which means that `WidgetExt::unrealize` has been
called or the widget has been unmapped (that is, it is going to be
hidden).
<!-- trait WidgetExt::fn connect_window_state_event -->
The ::window-state-event will be emitted when the state of the
toplevel window associated to the `widget` changes.

To receive this signal the `gdk::Window` associated to the widget
needs to enable the `gdk::EventMask::StructureMask` mask. GDK will enable
this mask automatically for all new windows.
## `event`
the `gdk::EventWindowState` which
 triggered this signal.

# Returns

`true` to stop other handlers from being invoked for the
 event. `false` to propagate the event further.
<!-- trait WidgetExt::fn get_property_expand -->
Whether to expand in both directions. Setting this sets both `Widget:hexpand` and `Widget:vexpand`
<!-- trait WidgetExt::fn set_property_expand -->
Whether to expand in both directions. Setting this sets both `Widget:hexpand` and `Widget:vexpand`
<!-- trait WidgetExt::fn get_property_focus_on_click -->
Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Before 3.20, several widgets (`Button`, `FileChooserButton`,
`ComboBox`) implemented this property individually.

Feature: `v3_20`

<!-- trait WidgetExt::fn set_property_focus_on_click -->
Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Before 3.20, several widgets (`Button`, `FileChooserButton`,
`ComboBox`) implemented this property individually.

Feature: `v3_20`

<!-- trait WidgetExt::fn get_property_halign -->
How to distribute horizontal space if widget gets extra space, see `Align`
<!-- trait WidgetExt::fn set_property_halign -->
How to distribute horizontal space if widget gets extra space, see `Align`
<!-- trait WidgetExt::fn get_property_has_tooltip -->
Enables or disables the emission of `Widget::query-tooltip` on `widget`.
A value of `true` indicates that `widget` can have a tooltip, in this case
the widget will be queried using `Widget::query-tooltip` to determine
whether it will provide a tooltip or not.

Note that setting this property to `true` for the first time will change
the event masks of the `GdkWindows` of this widget to include leave-notify
and motion-notify events. This cannot and will not be undone when the
property is set to `false` again.
<!-- trait WidgetExt::fn set_property_has_tooltip -->
Enables or disables the emission of `Widget::query-tooltip` on `widget`.
A value of `true` indicates that `widget` can have a tooltip, in this case
the widget will be queried using `Widget::query-tooltip` to determine
whether it will provide a tooltip or not.

Note that setting this property to `true` for the first time will change
the event masks of the `GdkWindows` of this widget to include leave-notify
and motion-notify events. This cannot and will not be undone when the
property is set to `false` again.
<!-- trait WidgetExt::fn get_property_hexpand -->
Whether to expand horizontally. See `WidgetExt::set_hexpand`.
<!-- trait WidgetExt::fn set_property_hexpand -->
Whether to expand horizontally. See `WidgetExt::set_hexpand`.
<!-- trait WidgetExt::fn get_property_hexpand_set -->
Whether to use the `Widget:hexpand` property. See `WidgetExt::get_hexpand_set`.
<!-- trait WidgetExt::fn set_property_hexpand_set -->
Whether to use the `Widget:hexpand` property. See `WidgetExt::get_hexpand_set`.
<!-- trait WidgetExt::fn get_property_margin -->
Sets all four sides' margin at once. If read, returns max
margin on any side.
<!-- trait WidgetExt::fn set_property_margin -->
Sets all four sides' margin at once. If read, returns max
margin on any side.
<!-- trait WidgetExt::fn get_property_margin_bottom -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn set_property_margin_bottom -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn get_property_margin_end -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn set_property_margin_end -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn get_property_margin_start -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn set_property_margin_start -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn get_property_margin_top -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn set_property_margin_top -->
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
`WidgetExt::set_size_request` for example.
<!-- trait WidgetExt::fn get_property_opacity -->
The requested opacity of the widget. See `WidgetExt::set_opacity` for
more details about window opacity.

Before 3.8 this was only available in `Window`
<!-- trait WidgetExt::fn set_property_opacity -->
The requested opacity of the widget. See `WidgetExt::set_opacity` for
more details about window opacity.

Before 3.8 this was only available in `Window`
<!-- trait WidgetExt::fn get_property_scale_factor -->
The scale factor of the widget. See `WidgetExt::get_scale_factor` for
more details about widget scaling.
<!-- trait WidgetExt::fn get_property_style -->
The style of the widget, which contains information about how it will look (colors, etc).

# Deprecated

Use `StyleContext` instead
<!-- trait WidgetExt::fn set_property_style -->
The style of the widget, which contains information about how it will look (colors, etc).

# Deprecated

Use `StyleContext` instead
<!-- trait WidgetExt::fn get_property_tooltip_markup -->
Sets the text of tooltip to be the given string, which is marked up
with the [Pango text markup language][PangoMarkupFormat].
Also see `Tooltip::set_markup`.

This is a convenience property which will take care of getting the
tooltip shown if the given string is not `None`: `Widget:has-tooltip`
will automatically be set to `true` and there will be taken care of
`Widget::query-tooltip` in the default signal handler.

Note that if both `Widget:tooltip-text` and `Widget:tooltip-markup`
are set, the last one wins.
<!-- trait WidgetExt::fn set_property_tooltip_markup -->
Sets the text of tooltip to be the given string, which is marked up
with the [Pango text markup language][PangoMarkupFormat].
Also see `Tooltip::set_markup`.

This is a convenience property which will take care of getting the
tooltip shown if the given string is not `None`: `Widget:has-tooltip`
will automatically be set to `true` and there will be taken care of
`Widget::query-tooltip` in the default signal handler.

Note that if both `Widget:tooltip-text` and `Widget:tooltip-markup`
are set, the last one wins.
<!-- trait WidgetExt::fn get_property_tooltip_text -->
Sets the text of tooltip to be the given string.

Also see `Tooltip::set_text`.

This is a convenience property which will take care of getting the
tooltip shown if the given string is not `None`: `Widget:has-tooltip`
will automatically be set to `true` and there will be taken care of
`Widget::query-tooltip` in the default signal handler.

Note that if both `Widget:tooltip-text` and `Widget:tooltip-markup`
are set, the last one wins.
<!-- trait WidgetExt::fn set_property_tooltip_text -->
Sets the text of tooltip to be the given string.

Also see `Tooltip::set_text`.

This is a convenience property which will take care of getting the
tooltip shown if the given string is not `None`: `Widget:has-tooltip`
will automatically be set to `true` and there will be taken care of
`Widget::query-tooltip` in the default signal handler.

Note that if both `Widget:tooltip-text` and `Widget:tooltip-markup`
are set, the last one wins.
<!-- trait WidgetExt::fn get_property_valign -->
How to distribute vertical space if widget gets extra space, see `Align`
<!-- trait WidgetExt::fn set_property_valign -->
How to distribute vertical space if widget gets extra space, see `Align`
<!-- trait WidgetExt::fn get_property_vexpand -->
Whether to expand vertically. See `WidgetExt::set_vexpand`.
<!-- trait WidgetExt::fn set_property_vexpand -->
Whether to expand vertically. See `WidgetExt::set_vexpand`.
<!-- trait WidgetExt::fn get_property_vexpand_set -->
Whether to use the `Widget:vexpand` property. See `WidgetExt::get_vexpand_set`.
<!-- trait WidgetExt::fn set_property_vexpand_set -->
Whether to use the `Widget:vexpand` property. See `WidgetExt::get_vexpand_set`.
<!-- trait WidgetExt::fn get_property_window -->
The widget's window if it is realized, `None` otherwise.
<!-- enum WidgetHelpType -->
Kinds of widget-specific help. Used by the ::show-help signal.
<!-- enum WidgetHelpType::variant Tooltip -->
Tooltip.
<!-- enum WidgetHelpType::variant WhatsThis -->
What’s this.
<!-- struct WidgetPath -->
`WidgetPath` is a boxed type that represents a widget hierarchy from
the topmost widget, typically a toplevel, to any child. This widget
path abstraction is used in `StyleContext` on behalf of the real
widget in order to query style information.

If you are using GTK+ widgets, you probably will not need to use
this API directly, as there is `WidgetExt::get_path`, and the style
context returned by `WidgetExt::get_style_context` will be automatically
updated on widget hierarchy changes.

The widget path generation is generally simple:

## Defining a button within a window


```C
{
  GtkWidgetPath *path;

  path = gtk_widget_path_new ();
  gtk_widget_path_append_type (path, GTK_TYPE_WINDOW);
  gtk_widget_path_append_type (path, GTK_TYPE_BUTTON);
}
```

Although more complex information, such as widget names, or
different classes (property that may be used by other widget
types) and intermediate regions may be included:

## Defining the first tab widget in a notebook


```C
{
  GtkWidgetPath *path;
  guint pos;

  path = gtk_widget_path_new ();

  pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK);
  gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST);

  pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL);
  gtk_widget_path_iter_set_name (path, pos, "first tab label");
}
```

All this information will be used to match the style information
that applies to the described widget.
<!-- impl WidgetPath::fn new -->
Returns an empty widget path.

# Returns

A newly created, empty, `WidgetPath`
<!-- impl WidgetPath::fn append_for_widget -->
Appends the data from `widget` to the widget hierarchy represented
by `self`. This function is a shortcut for adding information from
`widget` to the given `self`. This includes setting the name or
adding the style classes from `widget`.
## `widget`
the widget to append to the widget path

# Returns

the position where the data was inserted
<!-- impl WidgetPath::fn append_type -->
Appends a widget type to the widget hierarchy represented by `self`.
## `type_`
widget type to append

# Returns

the position where the element was inserted
<!-- impl WidgetPath::fn append_with_siblings -->
Appends a widget type with all its siblings to the widget hierarchy
represented by `self`. Using this function instead of
`WidgetPath::append_type` will allow the CSS theming to use
sibling matches in selectors and apply :nth-`child` pseudo classes.
In turn, it requires a lot more care in widget implementations as
widgets need to make sure to call `WidgetExt::reset_style` on all
involved widgets when the `siblings` path changes.
## `siblings`
a widget path describing a list of siblings. This path
 may not contain any siblings itself and it must not be modified
 afterwards.
## `sibling_index`
index into `siblings` for where the added element is
 positioned.

# Returns

the position where the element was inserted.
<!-- impl WidgetPath::fn copy -->
Returns a copy of `self`

# Returns

a copy of `self`
<!-- impl WidgetPath::fn free -->
Decrements the reference count on `self`, freeing the structure
if the reference count reaches 0.
<!-- impl WidgetPath::fn get_object_type -->
Returns the topmost object type, that is, the object type this path
is representing.

# Returns

The object type
<!-- impl WidgetPath::fn has_parent -->
Returns `true` if any of the parents of the widget represented
in `self` is of type `type_`, or any subtype of it.
## `type_`
widget type to check in parents

# Returns

`true` if any parent is of type `type_`
<!-- impl WidgetPath::fn is_type -->
Returns `true` if the widget type represented by this path
is `type_`, or a subtype of it.
## `type_`
widget type to match

# Returns

`true` if the widget represented by `self` is of type `type_`
<!-- impl WidgetPath::fn iter_add_class -->
Adds the class `name` to the widget at position `pos` in
the hierarchy defined in `self`. See
`StyleContextExt::add_class`.
## `pos`
position to modify, -1 for the path head
## `name`
a class name
<!-- impl WidgetPath::fn iter_clear_classes -->
Removes all classes from the widget at position `pos` in the
hierarchy defined in `self`.
## `pos`
position to modify, -1 for the path head
<!-- impl WidgetPath::fn iter_get_name -->
Returns the name corresponding to the widget found at
the position `pos` in the widget hierarchy defined by
`self`
## `pos`
position to get the widget name for, -1 for the path head

# Returns

The widget name, or `None` if none was set.
<!-- impl WidgetPath::fn iter_get_object_name -->
Returns the object name that is at position `pos` in the widget
hierarchy defined in `self`.

Feature: `v3_20`

## `pos`
position to get the object name for, -1 for the path head

# Returns

the name or `None`
<!-- impl WidgetPath::fn iter_get_object_type -->
Returns the object `glib::Type` that is at position `pos` in the widget
hierarchy defined in `self`.
## `pos`
position to get the object type for, -1 for the path head

# Returns

a widget type
<!-- impl WidgetPath::fn iter_get_sibling_index -->
Returns the index into the list of siblings for the element at `pos` as
returned by `WidgetPath::iter_get_siblings`. If that function would
return `None` because the element at `pos` has no siblings, this function
will return 0.
## `pos`
position to get the sibling index for, -1 for the path head

# Returns

0 or the index into the list of siblings for the element at `pos`.
<!-- impl WidgetPath::fn iter_get_siblings -->
Returns the list of siblings for the element at `pos`. If the element
was not added with siblings, `None` is returned.
## `pos`
position to get the siblings for, -1 for the path head

# Returns

`None` or the list of siblings for the element at `pos`.
<!-- impl WidgetPath::fn iter_get_state -->
Returns the state flags corresponding to the widget found at
the position `pos` in the widget hierarchy defined by
`self`
## `pos`
position to get the state for, -1 for the path head

# Returns

The state flags
<!-- impl WidgetPath::fn iter_has_class -->
Returns `true` if the widget at position `pos` has the class `name`
defined, `false` otherwise.
## `pos`
position to query, -1 for the path head
## `name`
class name

# Returns

`true` if the class `name` is defined for the widget at `pos`
<!-- impl WidgetPath::fn iter_has_name -->
Returns `true` if the widget at position `pos` has the name `name`,
`false` otherwise.
## `pos`
position to query, -1 for the path head
## `name`
a widget name

# Returns

`true` if the widget at `pos` has this name
<!-- impl WidgetPath::fn iter_has_qclass -->
See `WidgetPath::iter_has_class`. This is a version that operates
with GQuarks.
## `pos`
position to query, -1 for the path head
## `qname`
class name as a `glib::Quark`

# Returns

`true` if the widget at `pos` has the class defined.
<!-- impl WidgetPath::fn iter_has_qname -->
See `WidgetPath::iter_has_name`. This is a version
that operates on `GQuarks`.
## `pos`
position to query, -1 for the path head
## `qname`
widget name as a `glib::Quark`

# Returns

`true` if the widget at `pos` has this name
<!-- impl WidgetPath::fn iter_list_classes -->
Returns a list with all the class names defined for the widget
at position `pos` in the hierarchy defined in `self`.
## `pos`
position to query, -1 for the path head

# Returns

The list of
 classes, This is a list of strings, the `glib::SList` contents
 are owned by GTK+, but you should use `glib::SList::free` to
 free the list itself.
<!-- impl WidgetPath::fn iter_remove_class -->
Removes the class `name` from the widget at position `pos` in
the hierarchy defined in `self`.
## `pos`
position to modify, -1 for the path head
## `name`
class name
<!-- impl WidgetPath::fn iter_set_name -->
Sets the widget name for the widget found at position `pos`
in the widget hierarchy defined by `self`.
## `pos`
position to modify, -1 for the path head
## `name`
widget name
<!-- impl WidgetPath::fn iter_set_object_name -->
Sets the object name for a given position in the widget hierarchy
defined by `self`.

When set, the object name overrides the object type when matching
CSS.

Feature: `v3_20`

## `pos`
position to modify, -1 for the path head
## `name`
object name to set or `None` to unset
<!-- impl WidgetPath::fn iter_set_object_type -->
Sets the object type for a given position in the widget hierarchy
defined by `self`.
## `pos`
position to modify, -1 for the path head
## `type_`
object type to set
<!-- impl WidgetPath::fn iter_set_state -->
Sets the widget name for the widget found at position `pos`
in the widget hierarchy defined by `self`.

If you want to update just a single state flag, you need to do
this manually, as this function updates all state flags.

## Setting a flag


```C
gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag);
```

## Unsetting a flag


```C
gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag);
```
## `pos`
position to modify, -1 for the path head
## `state`
state flags
<!-- impl WidgetPath::fn length -->
Returns the number of `Widget` `GTypes` between the represented
widget and its topmost container.

# Returns

the number of elements in the path
<!-- impl WidgetPath::fn prepend_type -->
Prepends a widget type to the widget hierachy represented by `self`.
## `type_`
widget type to prepend
<!-- impl WidgetPath::fn ref -->
Increments the reference count on `self`.

# Returns

`self` itself.
<!-- impl WidgetPath::fn to_string -->
Dumps the widget path into a string representation. It tries to match
the CSS style as closely as possible (Note that there might be paths
that cannot be represented in CSS).

The main use of this code is for debugging purposes, so that you can
`g_print` the path or dump it in a gdb session.

# Returns

A new string describing `self`.
<!-- impl WidgetPath::fn unref -->
Decrements the reference count on `self`, freeing the structure
if the reference count reaches 0.
<!-- struct Window -->
A `Window` is a toplevel window which can contain other widgets.
Windows normally have decorations that are under the control
of the windowing system and allow the user to manipulate the window
(resize it, move it, close it,...).

# `Window` as `Buildable`

The `Window` implementation of the `Buildable` interface supports a
custom `<accel-groups>` element, which supports any number of `<group>`
elements representing the `AccelGroup` objects you want to add to
your window (synonymous with `GtkWindowExt::add_accel_group`.

It also supports the `<initial-focus>` element, whose name property names
the widget to receive the focus when the window is mapped.

An example of a UI definition fragment with accel groups:

```plain
window.background
├── decoration
├── <titlebar child>.titlebar [.default-decoration]
╰── <child>
```

`Window` has a main CSS node with name window and style class .background,
and a subnode with name decoration.

Style classes that are typically used with the main CSS node are .csd (when
client-side decorations are in use), .solid-csd (for client-side decorations
without invisible borders), .ssd (used by mutter when rendering server-side
decorations). `Window` also represents window states with the following
style classes on the main node: .tiled, .maximized, .fullscreen. Specialized
types of window often add their own discriminating style classes, such as
.popup or .tooltip.

`Window` adds the .titlebar and .default-decoration style classes to the
widget that is added as a titlebar child.

# Implements

[`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html), [`BuildableExtManual`](prelude/trait.BuildableExtManual.html)
<!-- trait GtkWindowExt -->
Trait containing all `Window` methods.

# Implementors

[`ApplicationWindow`](struct.ApplicationWindow.html), [`Assistant`](struct.Assistant.html), [`Dialog`](struct.Dialog.html), [`OffscreenWindow`](struct.OffscreenWindow.html), [`Plug`](struct.Plug.html), [`ShortcutsWindow`](struct.ShortcutsWindow.html), [`Window`](struct.Window.html)
<!-- impl Window::fn new -->
Creates a new `Window`, which is a toplevel window that can
contain other widgets. Nearly always, the type of the window should
be `WindowType::Toplevel`. If you’re implementing something like a
popup menu from scratch (which is a bad idea, just use `Menu`),
you might use `WindowType::Popup`. `WindowType::Popup` is not for
dialogs, though in some other toolkits dialogs are called “popups”.
In GTK+, `WindowType::Popup` means a pop-up menu or pop-up tooltip.
On X11, popup windows are not controlled by the
[window manager][gtk-X11-arch].

If you simply want an undecorated window (no window borders), use
`GtkWindowExt::set_decorated`, don’t use `WindowType::Popup`.

All top-level windows created by `Window::new` are stored in
an internal top-level window list. This list can be obtained from
`Window::list_toplevels`. Due to Gtk+ keeping a reference to
the window internally, `Window::new` does not return a reference
to the caller.

To delete a `Window`, call `Widget::destroy`.
## `type_`
type of window

# Returns

a new `Window`.
<!-- impl Window::fn get_default_icon_list -->
Gets the value set by `Window::set_default_icon_list`.
The list is a copy and should be freed with `glib::List::free`,
but the pixbufs in the list have not had their reference count
incremented.

# Returns

copy of default icon list
<!-- impl Window::fn get_default_icon_name -->
Returns the fallback icon name for windows that has been set
with `Window::set_default_icon_name`. The returned
string is owned by GTK+ and should not be modified. It
is only valid until the next call to
`Window::set_default_icon_name`.

# Returns

the fallback icon name for windows
<!-- impl Window::fn list_toplevels -->
Returns a list of all existing toplevel windows. 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.

# Returns

list of toplevel widgets
<!-- impl Window::fn set_auto_startup_notification -->
By default, after showing the first `Window`, GTK+ calls
`gdk_notify_startup_complete`. Call this function to disable
the automatic startup notification. You might do this if your
first window is a splash screen, and you want to delay notification
until after your real main window has been shown, for example.

In that example, you would disable startup notification
temporarily, show your splash screen, then re-enable it so that
showing the main window would automatically result in notification.
## `setting`
`true` to automatically do startup notification
<!-- impl Window::fn set_default_icon -->
Sets an icon to be used as fallback for windows that haven't
had `GtkWindowExt::set_icon` called on them from a pixbuf.
## `icon`
the icon
<!-- impl Window::fn set_default_icon_from_file -->
Sets an icon to be used as fallback for windows that haven't
had `GtkWindowExt::set_icon_list` called on them from a file
on disk. Warns on failure if `err` is `None`.
## `filename`
location of icon file

# Returns

`true` if setting the icon succeeded.
<!-- impl Window::fn set_default_icon_list -->
Sets an icon list to be used as fallback for windows that haven't
had `GtkWindowExt::set_icon_list` called on them to set up a
window-specific icon list. This function allows you to set up the
icon for all windows in your app at once.

See `GtkWindowExt::set_icon_list` for more details.
## `list`
a list of `gdk_pixbuf::Pixbuf`
<!-- impl Window::fn set_default_icon_name -->
Sets an icon to be used as fallback for windows that haven't
had `GtkWindowExt::set_icon_list` called on them from a named
themed icon, see `GtkWindowExt::set_icon_name`.
## `name`
the name of the themed icon
<!-- impl Window::fn set_interactive_debugging -->
Opens or closes the [interactive debugger][interactive-debugging],
which offers access to the widget hierarchy of the application
and to useful debugging tools.
## `enable`
`true` to enable interactive debugging
<!-- trait GtkWindowExt::fn activate_default -->
Activates the default widget for the window, unless the current
focused widget has been configured to receive the default action
(see `WidgetExt::set_receives_default`), in which case the
focused widget is activated.

# Returns

`true` if a widget got activated.
<!-- trait GtkWindowExt::fn activate_focus -->
Activates the current focused widget within the window.

# Returns

`true` if a widget got activated.
<!-- trait GtkWindowExt::fn activate_key -->
Activates mnemonics and accelerators for this `Window`. This is normally
called by the default ::key_press_event handler for toplevel windows,
however in some cases it may be useful to call this directly when
overriding the standard key handling for a toplevel window.
## `event`
a `gdk::EventKey`

# Returns

`true` if a mnemonic or accelerator was found and activated.
<!-- trait GtkWindowExt::fn add_accel_group -->
Associate `accel_group` with `self`, such that calling
`gtk_accel_groups_activate` on `self` will activate accelerators
in `accel_group`.
## `accel_group`
a `AccelGroup`
<!-- trait GtkWindowExt::fn add_mnemonic -->
Adds a mnemonic to this window.
## `keyval`
the mnemonic
## `target`
the widget that gets activated by the mnemonic
<!-- trait GtkWindowExt::fn begin_move_drag -->
Starts moving a window. This function is used if an application has
window movement grips. When GDK can support it, the window movement
will be done using the standard mechanism for the
[window manager][gtk-X11-arch] or windowing
system. Otherwise, GDK will try to emulate window movement,
potentially not all that well, depending on the windowing system.
## `button`
mouse button that initiated the drag
## `root_x`
X position where the user clicked to initiate the drag, in root window coordinates
## `root_y`
Y position where the user clicked to initiate the drag
## `timestamp`
timestamp from the click event that initiated the drag
<!-- trait GtkWindowExt::fn begin_resize_drag -->
Starts resizing a window. This function is used if an application
has window resizing controls. When GDK can support it, the resize
will be done using the standard mechanism for the
[window manager][gtk-X11-arch] or windowing
system. Otherwise, GDK will try to emulate window resizing,
potentially not all that well, depending on the windowing system.
## `edge`
position of the resize control
## `button`
mouse button that initiated the drag
## `root_x`
X position where the user clicked to initiate the drag, in root window coordinates
## `root_y`
Y position where the user clicked to initiate the drag
## `timestamp`
timestamp from the click event that initiated the drag
<!-- trait GtkWindowExt::fn close -->
Requests that the window is closed, similar to what happens
when a window manager close button is clicked.

This function can be used with close buttons in custom
titlebars.
<!-- trait GtkWindowExt::fn deiconify -->
Asks to deiconify (i.e. unminimize) the specified `self`. Note
that you shouldn’t assume the window is definitely deiconified
afterward, because other entities (e.g. the user or
[window manager][gtk-X11-arch])) could iconify it
again before your code which assumes deiconification gets to run.

You can track iconification via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn fullscreen -->
Asks to place `self` in the fullscreen state. Note that you
shouldn’t assume the window is definitely full screen afterward,
because other entities (e.g. the user or
[window manager][gtk-X11-arch]) could unfullscreen it
again, and not all window managers honor requests to fullscreen
windows. But normally the window will end up fullscreen. Just
don’t write code that crashes if not.

You can track the fullscreen state via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn fullscreen_on_monitor -->
Asks to place `self` in the fullscreen state. Note that you shouldn't assume
the window is definitely full screen afterward.

You can track the fullscreen state via the "window-state-event" signal
on `Widget`.

Feature: `v3_18`

## `screen`
a `gdk::Screen` to draw to
## `monitor`
which monitor to go fullscreen on
<!-- trait GtkWindowExt::fn get_accept_focus -->
Gets the value set by `GtkWindowExt::set_accept_focus`.

# Returns

`true` if window should receive the input focus
<!-- trait GtkWindowExt::fn get_application -->
Gets the `Application` associated with the window (if any).

# Returns

a `Application`, or `None`
<!-- trait GtkWindowExt::fn get_attached_to -->
Fetches the attach widget for this window. See
`GtkWindowExt::set_attached_to`.

# Returns

the widget where the window
is attached, or `None` if the window is not attached to any widget.
<!-- trait GtkWindowExt::fn get_decorated -->
Returns whether the window has been set to have decorations
such as a title bar via `GtkWindowExt::set_decorated`.

# Returns

`true` if the window has been set to have decorations
<!-- trait GtkWindowExt::fn get_default_size -->
Gets the default size of the window. A value of -1 for the width or
height indicates that a default size has not been explicitly set
for that dimension, so the “natural” size of the window will be
used.
## `width`
location to store the default width, or `None`
## `height`
location to store the default height, or `None`
<!-- trait GtkWindowExt::fn get_default_widget -->
Returns the default widget for `self`. See
`GtkWindowExt::set_default` for more details.

# Returns

the default widget, or `None`
if there is none.
<!-- trait GtkWindowExt::fn get_deletable -->
Returns whether the window has been set to have a close button
via `GtkWindowExt::set_deletable`.

# Returns

`true` if the window has been set to have a close button
<!-- trait GtkWindowExt::fn get_destroy_with_parent -->
Returns whether the window will be destroyed with its transient parent. See
gtk_window_set_destroy_with_parent ().

# Returns

`true` if the window will be destroyed with its transient parent.
<!-- trait GtkWindowExt::fn get_focus -->
Retrieves the current focused widget within the window.
Note that this is the widget that would have the focus
if the toplevel window focused; if the toplevel window
is not focused then `gtk_widget_has_focus (widget)` will
not be `true` for the widget.

# Returns

the currently focused widget,
or `None` if there is none.
<!-- trait GtkWindowExt::fn get_focus_on_map -->
Gets the value set by `GtkWindowExt::set_focus_on_map`.

# Returns

`true` if window should receive the input focus when
mapped.
<!-- trait GtkWindowExt::fn get_focus_visible -->
Gets the value of the `Window:focus-visible` property.

# Returns

`true` if “focus rectangles” are supposed to be visible
 in this window.
<!-- trait GtkWindowExt::fn get_gravity -->
Gets the value set by `GtkWindowExt::set_gravity`.

# Returns

window gravity
<!-- trait GtkWindowExt::fn get_group -->
Returns the group for `self` or the default group, if
`self` is `None` or if `self` does not have an explicit
window group.

# Returns

the `WindowGroup` for a window or the default group
<!-- trait GtkWindowExt::fn get_hide_titlebar_when_maximized -->
Returns whether the window has requested to have its titlebar hidden
when maximized. See gtk_window_set_hide_titlebar_when_maximized ().

# Returns

`true` if the window has requested to have its titlebar
 hidden when maximized
<!-- trait GtkWindowExt::fn get_icon -->
Gets the value set by `GtkWindowExt::set_icon` (or if you've
called `GtkWindowExt::set_icon_list`, gets the first icon in
the icon list).

# Returns

icon for window or `None` if none
<!-- trait GtkWindowExt::fn get_icon_list -->
Retrieves the list of icons set by `GtkWindowExt::set_icon_list`.
The list is copied, but the reference count on each
member won’t be incremented.

# Returns

copy of window’s icon list
<!-- trait GtkWindowExt::fn get_icon_name -->
Returns the name of the themed icon for the window,
see `GtkWindowExt::set_icon_name`.

# Returns

the icon name or `None` if the window has
no themed icon
<!-- trait GtkWindowExt::fn get_mnemonic_modifier -->
Returns the mnemonic modifier for this window. See
`GtkWindowExt::set_mnemonic_modifier`.

# Returns

the modifier mask used to activate
 mnemonics on this window.
<!-- trait GtkWindowExt::fn get_mnemonics_visible -->
Gets the value of the `Window:mnemonics-visible` property.

# Returns

`true` if mnemonics are supposed to be visible
in this window.
<!-- trait GtkWindowExt::fn get_modal -->
Returns whether the window is modal. See `GtkWindowExt::set_modal`.

# Returns

`true` if the window is set to be modal and
 establishes a grab when shown
<!-- trait GtkWindowExt::fn get_position -->
This function returns the position you need to pass to
`GtkWindowExt::move` to keep `self` in its current position.
This means that the meaning of the returned value varies with
window gravity. See `GtkWindowExt::move` for more details.

The reliability of this function depends on the windowing system
currently in use. Some windowing systems, such as Wayland, do not
support a global coordinate system, and thus the position of the
window will always be (0, 0). Others, like X11, do not have a reliable
way to obtain the geometry of the decorations of a window if they are
provided by the window manager. Additionally, on X11, window manager
have been known to mismanage window gravity, which result in windows
moving even if you use the coordinates of the current position as
returned by this function.

If you haven’t changed the window gravity, its gravity will be
`gdk::Gravity::NorthWest`. This means that `GtkWindowExt::get_position`
gets the position of the top-left corner of the window manager
frame for the window. `GtkWindowExt::move` sets the position of this
same top-left corner.

If a window has gravity `gdk::Gravity::Static` the window manager
frame is not relevant, and thus `GtkWindowExt::get_position` will
always produce accurate results. However you can’t use static
gravity to do things like place a window in a corner of the screen,
because static gravity ignores the window manager decorations.

Ideally, this function should return appropriate values if the
window has client side decorations, assuming that the windowing
system supports global coordinates.

In practice, saving the window position should not be left to
applications, as they lack enough knowledge of the windowing
system and the window manager state to effectively do so. The
appropriate way to implement saving the window position is to
use a platform-specific protocol, wherever that is available.
## `root_x`
return location for X coordinate of
 gravity-determined reference point, or `None`
## `root_y`
return location for Y coordinate of
 gravity-determined reference point, or `None`
<!-- trait GtkWindowExt::fn get_resizable -->
Gets the value set by `GtkWindowExt::set_resizable`.

# Returns

`true` if the user can resize the window
<!-- trait GtkWindowExt::fn get_role -->
Returns the role of the window. See `GtkWindowExt::set_role` for
further explanation.

# Returns

the role of the window if set, or `None`. The
returned is owned by the widget and must not be modified or freed.
<!-- trait GtkWindowExt::fn get_screen -->
Returns the `gdk::Screen` associated with `self`.

# Returns

a `gdk::Screen`.
<!-- trait GtkWindowExt::fn get_size -->
Obtains the current size of `self`.

If `self` is not visible on screen, this function return the size GTK+
will suggest to the [window manager][gtk-X11-arch] for the initial window
size (but this is not reliably the same as the size the window manager
will actually select). See: `GtkWindowExt::set_default_size`.

Depending on the windowing system and the window manager constraints,
the size returned by this function may not match the size set using
`GtkWindowExt::resize`; additionally, since `GtkWindowExt::resize` may be
implemented as an asynchronous operation, GTK+ cannot guarantee in any
way that this code:


```C
  // width and height are set elsewhere
  gtk_window_resize (window, width, height);

  int new_width, new_height;
  gtk_window_get_size (window, &new_width, &new_height);
```

will result in `new_width` and `new_height` matching `width` and
`height`, respectively.

This function will return the logical size of the `Window`,
excluding the widgets used in client side decorations; there is,
however, no guarantee that the result will be completely accurate
because client side decoration may include widgets that depend on
the user preferences and that may not be visibile at the time you
call this function.

The dimensions returned by this function are suitable for being
stored across sessions; use `GtkWindowExt::set_default_size` to
restore them when before showing the window.

To avoid potential race conditions, you should only call this
function in response to a size change notification, for instance
inside a handler for the `Widget::size-allocate` signal, or
inside a handler for the `Widget::configure-event` signal:


```C
static void
on_size_allocate (GtkWidget *widget, GtkAllocation *allocation)
{
  int new_width, new_height;

  gtk_window_get_size (GTK_WINDOW (widget), &new_width, &new_height);

  ...
}
```

Note that, if you connect to the `Widget::size-allocate` signal,
you should not use the dimensions of the `Allocation` passed to
the signal handler, as the allocation may contain client side
decorations added by GTK+, depending on the windowing system in
use.

If you are getting a window size in order to position the window
on the screen, you should, instead, simply set the window’s semantic
type with `GtkWindowExt::set_type_hint`, which allows the window manager
to e.g. center dialogs. Also, if you set the transient parent of
dialogs with `GtkWindowExt::set_transient_for` window managers will
often center the dialog over its parent window. It's much preferred
to let the window manager handle these cases rather than doing it
yourself, because all apps will behave consistently and according to
user or system preferences, if the window manager handles it. Also,
the window manager can take into account the size of the window
decorations and border that it may add, and of which GTK+ has no
knowledge. Additionally, positioning windows in global screen coordinates
may not be allowed by the windowing system. For more information,
see: `GtkWindowExt::set_position`.
## `width`
return location for width, or `None`
## `height`
return location for height, or `None`
<!-- trait GtkWindowExt::fn get_skip_pager_hint -->
Gets the value set by `GtkWindowExt::set_skip_pager_hint`.

# Returns

`true` if window shouldn’t be in pager
<!-- trait GtkWindowExt::fn get_skip_taskbar_hint -->
Gets the value set by `GtkWindowExt::set_skip_taskbar_hint`

# Returns

`true` if window shouldn’t be in taskbar
<!-- trait GtkWindowExt::fn get_title -->
Retrieves the title of the window. See `GtkWindowExt::set_title`.

# Returns

the title of the window, or `None` if none has
been set explicitly. The returned string is owned by the widget
and must not be modified or freed.
<!-- trait GtkWindowExt::fn get_titlebar -->
Returns the custom titlebar that has been set with
`GtkWindowExt::set_titlebar`.

Feature: `v3_16`


# Returns

the custom titlebar, or `None`
<!-- trait GtkWindowExt::fn get_transient_for -->
Fetches the transient parent for this window. See
`GtkWindowExt::set_transient_for`.

# Returns

the transient parent for this
window, or `None` if no transient parent has been set.
<!-- trait GtkWindowExt::fn get_type_hint -->
Gets the type hint for this window. See `GtkWindowExt::set_type_hint`.

# Returns

the type hint for `self`.
<!-- trait GtkWindowExt::fn get_urgency_hint -->
Gets the value set by `GtkWindowExt::set_urgency_hint`

# Returns

`true` if window is urgent
<!-- trait GtkWindowExt::fn get_window_type -->
Gets the type of the window. See `WindowType`.

# Returns

the type of the window
<!-- trait GtkWindowExt::fn has_group -->
Returns whether `self` has an explicit window group.

# Returns

`true` if `self` has an explicit window group.

Since 2.22
<!-- trait GtkWindowExt::fn has_toplevel_focus -->
Returns whether the input focus is within this `Window`.
For real toplevel windows, this is identical to `GtkWindowExt::is_active`,
but for embedded windows, like `Plug`, the results will differ.

# Returns

`true` if the input focus is within this `Window`
<!-- trait GtkWindowExt::fn iconify -->
Asks to iconify (i.e. minimize) the specified `self`. Note that
you shouldn’t assume the window is definitely iconified afterward,
because other entities (e.g. the user or
[window manager][gtk-X11-arch]) could deiconify it
again, or there may not be a window manager in which case
iconification isn’t possible, etc. But normally the window will end
up iconified. Just don’t write code that crashes if not.

It’s permitted to call this function before showing a window,
in which case the window will be iconified before it ever appears
onscreen.

You can track iconification via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn is_active -->
Returns whether the window is part of the current active toplevel.
(That is, the toplevel window receiving keystrokes.)
The return value is `true` if the window is active toplevel
itself, but also if it is, say, a `Plug` embedded in the active toplevel.
You might use this function if you wanted to draw a widget
differently in an active window from a widget in an inactive window.
See `GtkWindowExt::has_toplevel_focus`

# Returns

`true` if the window part of the current active window.
<!-- trait GtkWindowExt::fn is_maximized -->
Retrieves the current maximized state of `self`.

Note that since maximization is ultimately handled by the window
manager and happens asynchronously to an application request, you
shouldn’t assume the return value of this function changing
immediately (or at all), as an effect of calling
`GtkWindowExt::maximize` or `GtkWindowExt::unmaximize`.

# Returns

whether the window has a maximized state.
<!-- trait GtkWindowExt::fn maximize -->
Asks to maximize `self`, so that it becomes full-screen. Note that
you shouldn’t assume the window is definitely maximized afterward,
because other entities (e.g. the user or
[window manager][gtk-X11-arch]) could unmaximize it
again, and not all window managers support maximization. But
normally the window will end up maximized. Just don’t write code
that crashes if not.

It’s permitted to call this function before showing a window,
in which case the window will be maximized when it appears onscreen
initially.

You can track maximization via the “window-state-event” signal
on `Widget`, or by listening to notifications on the
`Window:is-maximized` property.
<!-- trait GtkWindowExt::fn mnemonic_activate -->
Activates the targets associated with the mnemonic.
## `keyval`
the mnemonic
## `modifier`
the modifiers

# Returns

`true` if the activation is done.
<!-- trait GtkWindowExt::fn move -->
Asks the [window manager][gtk-X11-arch] to move
`self` to the given position. Window managers are free to ignore
this; most window managers ignore requests for initial window
positions (instead using a user-defined placement algorithm) and
honor requests after the window has already been shown.

Note: the position is the position of the gravity-determined
reference point for the window. The gravity determines two things:
first, the location of the reference point in root window
coordinates; and second, which point on the window is positioned at
the reference point.

By default the gravity is `gdk::Gravity::NorthWest`, so the reference
point is simply the `x`, `y` supplied to `GtkWindowExt::move`. The
top-left corner of the window decorations (aka window frame or
border) will be placed at `x`, `y`. Therefore, to position a window
at the top left of the screen, you want to use the default gravity
(which is `gdk::Gravity::NorthWest`) and move the window to 0,0.

To position a window at the bottom right corner of the screen, you
would set `gdk::Gravity::SouthEast`, which means that the reference
point is at `x` + the window width and `y` + the window height, and
the bottom-right corner of the window border will be placed at that
reference point. So, to place a window in the bottom right corner
you would first set gravity to south east, then write:
`gtk_window_move (window, gdk_screen_width () - window_width,
gdk_screen_height () - window_height)` (note that this
example does not take multi-head scenarios into account).

The [Extended Window Manager Hints Specification](http://www.freedesktop.org/Standards/wm-spec)
has a nice table of gravities in the “implementation notes” section.

The `GtkWindowExt::get_position` documentation may also be relevant.
## `x`
X coordinate to move window to
## `y`
Y coordinate to move window to
<!-- trait GtkWindowExt::fn parse_geometry -->
Parses a standard X Window System geometry string - see the
manual page for X (type “man X”) for details on this.
`GtkWindowExt::parse_geometry` does work on all GTK+ ports
including Win32 but is primarily intended for an X environment.

If either a size or a position can be extracted from the
geometry string, `GtkWindowExt::parse_geometry` returns `true`
and calls `GtkWindowExt::set_default_size` and/or `GtkWindowExt::move`
to resize/move the window.

If `GtkWindowExt::parse_geometry` returns `true`, it will also
set the `gdk::WindowHints::UserPos` and/or `gdk::WindowHints::UserSize` hints
indicating to the window manager that the size/position of
the window was user-specified. This causes most window
managers to honor the geometry.

Note that for `GtkWindowExt::parse_geometry` to work as expected, it has
to be called when the window has its “final” size, i.e. after calling
`WidgetExt::show_all` on the contents and `GtkWindowExt::set_geometry_hints`
on the window.

```C
#include <gtk/gtk.h>

static void
fill_with_content (GtkWidget *vbox)
{
  // fill with content...
}

int
main (int argc, char *argv[])
{
  GtkWidget *window, *vbox;
  GdkGeometry size_hints = {
    100, 50, 0, 0, 100, 50, 10,
    10, 0.0, 0.0, GDK_GRAVITY_NORTH_WEST
  };

  gtk_init (&argc, &argv);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  vbox = gtk_box_new (GTK_ORIENTATION_VERTICAL, 0);

  gtk_container_add (GTK_CONTAINER (window), vbox);
  fill_with_content (vbox);
  gtk_widget_show_all (vbox);

  gtk_window_set_geometry_hints (GTK_WINDOW (window),
                      NULL,
                    &size_hints,
                    GDK_HINT_MIN_SIZE |
                    GDK_HINT_BASE_SIZE |
                    GDK_HINT_RESIZE_INC);

  if (argc > 1)
    {
      gboolean res;
      res = gtk_window_parse_geometry (GTK_WINDOW (window),
                                       argv[1]);
      if (! res)
        fprintf (stderr,
                 "Failed to parse “%s”\n",
                 argv[1]);
    }

  gtk_widget_show_all (window);
  gtk_main ();

  return 0;
}
```

# Deprecated since 3.20

Geometry handling in GTK is deprecated.
## `geometry`
geometry string

# Returns

`true` if string was parsed successfully
<!-- trait GtkWindowExtManual::fn present -->
Presents a window to the user. This function should not be used
as when it is called, it is too late to gather a valid timestamp
to allow focus stealing prevention to work correctly.
<!-- trait GtkWindowExt::fn present_with_time -->
Presents a window to the user. This may mean raising the window
in the stacking order, deiconifying it, moving it to the current
desktop, and/or giving it the keyboard focus, possibly dependent
on the user’s platform, window manager, and preferences.

If `self` is hidden, this function calls `WidgetExt::show`
as well.

This function should be used when the user tries to open a window
that’s already open. Say for example the preferences dialog is
currently open, and the user chooses Preferences from the menu
a second time; use `Window::present` to move the already-open dialog
where the user can see it.

Presents a window to the user in response to a user interaction. The
timestamp should be gathered when the window was requested to be shown
(when clicking a link for example), rather than once the window is
ready to be shown.
## `timestamp`
the timestamp of the user interaction (typically a
 button or key press event) which triggered this call
<!-- trait GtkWindowExt::fn propagate_key_event -->
Propagate a key press or release event to the focus widget and
up the focus container chain until a widget handles `event`.
This is normally called by the default ::key_press_event and
::key_release_event handlers for toplevel windows,
however in some cases it may be useful to call this directly when
overriding the standard key handling for a toplevel window.
## `event`
a `gdk::EventKey`

# Returns

`true` if a widget in the focus chain handled the event.
<!-- trait GtkWindowExt::fn remove_accel_group -->
Reverses the effects of `GtkWindowExt::add_accel_group`.
## `accel_group`
a `AccelGroup`
<!-- trait GtkWindowExt::fn remove_mnemonic -->
Removes a mnemonic from this window.
## `keyval`
the mnemonic
## `target`
the widget that gets activated by the mnemonic
<!-- trait GtkWindowExt::fn resize -->
Resizes the window as if the user had done so, obeying geometry
constraints. The default geometry constraint is that windows may
not be smaller than their size request; to override this
constraint, call `WidgetExt::set_size_request` to set the window's
request to a smaller value.

If `GtkWindowExt::resize` is called before showing a window for the
first time, it overrides any default size set with
`GtkWindowExt::set_default_size`.

Windows may not be resized smaller than 1 by 1 pixels.

When using client side decorations, GTK+ will do its best to adjust
the given size so that the resulting window size matches the
requested size without the title bar, borders and shadows added for
the client side decorations, but there is no guarantee that the
result will be totally accurate because these widgets added for
client side decorations depend on the theme and may not be realized
or visible at the time `GtkWindowExt::resize` is issued.

If the `Window` has a titlebar widget (see `GtkWindowExt::set_titlebar`), then
typically, `GtkWindowExt::resize` will compensate for the height of the titlebar
widget only if the height is known when the resulting `Window` configuration
is issued.
For example, if new widgets are added after the `Window` configuration
and cause the titlebar widget to grow in height, this will result in a
window content smaller that specified by `GtkWindowExt::resize` and not
a larger window.
## `width`
width in pixels to resize the window to
## `height`
height in pixels to resize the window to
<!-- trait GtkWindowExt::fn resize_to_geometry -->
Like `GtkWindowExt::resize`, but `width` and `height` are interpreted
in terms of the base size and increment set with
gtk_window_set_geometry_hints.

# Deprecated since 3.20

This function does nothing. Use
 `GtkWindowExt::resize` and compute the geometry yourself.
## `width`
width in resize increments to resize the window to
## `height`
height in resize increments to resize the window to
<!-- trait GtkWindowExt::fn set_accept_focus -->
Windows may set a hint asking the desktop environment not to receive
the input focus. This function sets this hint.
## `setting`
`true` to let this window receive input focus
<!-- trait GtkWindowExt::fn set_application -->
Sets or unsets the `Application` associated with the window.

The application will be kept alive for at least as long as it has any windows
associated with it (see `gio::ApplicationExt::hold` for a way to keep it alive
without windows).

Normally, the connection between the application and the window will remain
until the window is destroyed, but you can explicitly remove it by setting
the `application` to `None`.

This is equivalent to calling `GtkApplicationExt::remove_window` and/or
`GtkApplicationExt::add_window` on the old/new applications as relevant.
## `application`
a `Application`, or `None` to unset
<!-- trait GtkWindowExt::fn set_attached_to -->
Marks `self` as attached to `attach_widget`. This creates a logical binding
between the window and the widget it belongs to, which is used by GTK+ to
propagate information such as styling or accessibility to `self` as if it
was a children of `attach_widget`.

Examples of places where specifying this relation is useful are for instance
a `Menu` created by a `ComboBox`, a completion popup window
created by `Entry` or a typeahead search entry created by `TreeView`.

Note that this function should not be confused with
`GtkWindowExt::set_transient_for`, which specifies a window manager relation
between two toplevels instead.

Passing `None` for `attach_widget` detaches the window.
## `attach_widget`
a `Widget`, or `None`
<!-- trait GtkWindowExt::fn set_decorated -->
By default, windows are decorated with a title bar, resize
controls, etc. Some [window managers][gtk-X11-arch]
allow GTK+ to disable these decorations, creating a
borderless window. If you set the decorated property to `false`
using this function, GTK+ will do its best to convince the window
manager not to decorate the window. Depending on the system, this
function may not have any effect when called on a window that is
already visible, so you should call it before calling `WidgetExt::show`.

On Windows, this function always works, since there’s no window manager
policy involved.
## `setting`
`true` to decorate the window
<!-- trait GtkWindowExt::fn set_default -->
The default widget is the widget that’s activated when the user
presses Enter in a dialog (for example). This function sets or
unsets the default widget for a `Window`. When setting (rather
than unsetting) the default widget it’s generally easier to call
`WidgetExt::grab_default` on the widget. Before making a widget
the default widget, you must call `WidgetExt::set_can_default` on
the widget you’d like to make the default.
## `default_widget`
widget to be the default, or `None`
 to unset the default widget for the toplevel
<!-- trait GtkWindowExt::fn set_default_geometry -->
Like `GtkWindowExt::set_default_size`, but `width` and `height` are interpreted
in terms of the base size and increment set with
gtk_window_set_geometry_hints.

# Deprecated since 3.20

This function does nothing. If you want to set a default
 size, use `GtkWindowExt::set_default_size` instead.
## `width`
width in resize increments, or -1 to unset the default width
## `height`
height in resize increments, or -1 to unset the default height
<!-- trait GtkWindowExt::fn set_default_size -->
Sets the default size of a window. If the window’s “natural” size
(its size request) is larger than the default, the default will be
ignored. More generally, if the default size does not obey the
geometry hints for the window (`GtkWindowExt::set_geometry_hints` can
be used to set these explicitly), the default size will be clamped
to the nearest permitted size.

Unlike `WidgetExt::set_size_request`, which sets a size request for
a widget and thus would keep users from shrinking the window, this
function only sets the initial size, just as if the user had
resized the window themselves. Users can still shrink the window
again as they normally would. Setting a default size of -1 means to
use the “natural” default size (the size request of the window).

For more control over a window’s initial size and how resizing works,
investigate `GtkWindowExt::set_geometry_hints`.

For some uses, `GtkWindowExt::resize` is a more appropriate function.
`GtkWindowExt::resize` changes the current size of the window, rather
than the size to be used on initial display. `GtkWindowExt::resize` always
affects the window itself, not the geometry widget.

The default size of a window only affects the first time a window is
shown; if a window is hidden and re-shown, it will remember the size
it had prior to hiding, rather than using the default size.

Windows can’t actually be 0x0 in size, they must be at least 1x1, but
passing 0 for `width` and `height` is OK, resulting in a 1x1 default size.

If you use this function to reestablish a previously saved window size,
note that the appropriate size to save is the one returned by
`GtkWindowExt::get_size`. Using the window allocation directly will not
work in all circumstances and can lead to growing or shrinking windows.
## `width`
width in pixels, or -1 to unset the default width
## `height`
height in pixels, or -1 to unset the default height
<!-- trait GtkWindowExt::fn set_deletable -->
By default, windows have a close button in the window frame. Some
[window managers][gtk-X11-arch] allow GTK+ to
disable this button. If you set the deletable property to `false`
using this function, GTK+ will do its best to convince the window
manager not to show a close button. Depending on the system, this
function may not have any effect when called on a window that is
already visible, so you should call it before calling `WidgetExt::show`.

On Windows, this function always works, since there’s no window manager
policy involved.
## `setting`
`true` to decorate the window as deletable
<!-- trait GtkWindowExt::fn set_destroy_with_parent -->
If `setting` is `true`, then destroying the transient parent of `self`
will also destroy `self` itself. This is useful for dialogs that
shouldn’t persist beyond the lifetime of the main window they're
associated with, for example.
## `setting`
whether to destroy `self` with its transient parent
<!-- trait GtkWindowExt::fn set_focus -->
If `focus` is not the current focus widget, and is focusable, sets
it as the focus widget for the window. If `focus` is `None`, unsets
the focus widget for this window. To set the focus to a particular
widget in the toplevel, it is usually more convenient to use
`WidgetExt::grab_focus` instead of this function.
## `focus`
widget to be the new focus widget, or `None` to unset
 any focus widget for the toplevel window.
<!-- trait GtkWindowExt::fn set_focus_on_map -->
Windows may set a hint asking the desktop environment not to receive
the input focus when the window is mapped. This function sets this
hint.
## `setting`
`true` to let this window receive input focus on map
<!-- trait GtkWindowExt::fn set_focus_visible -->
Sets the `Window:focus-visible` property.
## `setting`
the new value
<!-- trait GtkWindowExt::fn set_geometry_hints -->
This function sets up hints about how a window can be resized by
the user. You can set a minimum and maximum size; allowed resize
increments (e.g. for xterm, you can only resize by the size of a
character); aspect ratios; and more. See the `gdk::Geometry` struct.
## `geometry_widget`
widget the geometry hints used to be applied to
 or `None`. Since 3.20 this argument is ignored and GTK behaves as if `None` was
 set.
## `geometry`
struct containing geometry information or `None`
## `geom_mask`
mask indicating which struct fields should be paid attention to
<!-- trait GtkWindowExt::fn set_gravity -->
Window gravity defines the meaning of coordinates passed to
`GtkWindowExt::move`. See `GtkWindowExt::move` and `gdk::Gravity` for
more details.

The default window gravity is `gdk::Gravity::NorthWest` which will
typically “do what you mean.”
## `gravity`
window gravity
<!-- trait GtkWindowExt::fn set_has_user_ref_count -->
Tells GTK+ whether to drop its extra reference to the window
when `Widget::destroy` is called.

This function is only exported for the benefit of language
bindings which may need to keep the window alive until their
wrapper object is garbage collected. There is no justification
for ever calling this function in an application.
## `setting`
the new value
<!-- trait GtkWindowExt::fn set_hide_titlebar_when_maximized -->
If `setting` is `true`, then `self` will request that it’s titlebar
should be hidden when maximized.
This is useful for windows that don’t convey any information other
than the application name in the titlebar, to put the available
screen space to better use. If the underlying window system does not
support the request, the setting will not have any effect.

Note that custom titlebars set with `GtkWindowExt::set_titlebar` are
not affected by this. The application is in full control of their
content and visibility anyway.
## `setting`
whether to hide the titlebar when `self` is maximized
<!-- trait GtkWindowExt::fn set_icon -->
Sets up the icon representing a `Window`. This icon is used when
the window is minimized (also known as iconified). Some window
managers or desktop environments may also place it in the window
frame, or display it in other contexts. On others, the icon is not
used at all, so your mileage may vary.

The icon should be provided in whatever size it was naturally
drawn; that is, don’t scale the image before passing it to
GTK+. Scaling is postponed until the last minute, when the desired
final size is known, to allow best quality.

If you have your icon hand-drawn in multiple sizes, use
`GtkWindowExt::set_icon_list`. Then the best size will be used.

This function is equivalent to calling `GtkWindowExt::set_icon_list`
with a 1-element list.

See also `Window::set_default_icon_list` to set the icon
for all windows in your application in one go.
## `icon`
icon image, or `None`
<!-- trait GtkWindowExt::fn set_icon_from_file -->
Sets the icon for `self`.
Warns on failure if `err` is `None`.

This function is equivalent to calling `GtkWindowExt::set_icon`
with a pixbuf created by loading the image from `filename`.
## `filename`
location of icon file

# Returns

`true` if setting the icon succeeded.
<!-- trait GtkWindowExt::fn set_icon_list -->
Sets up the icon representing a `Window`. The icon is used when
the window is minimized (also known as iconified). Some window
managers or desktop environments may also place it in the window
frame, or display it in other contexts. On others, the icon is not
used at all, so your mileage may vary.

`GtkWindowExt::set_icon_list` allows you to pass in the same icon in
several hand-drawn sizes. The list should contain the natural sizes
your icon is available in; that is, don’t scale the image before
passing it to GTK+. Scaling is postponed until the last minute,
when the desired final size is known, to allow best quality.

By passing several sizes, you may improve the final image quality
of the icon, by reducing or eliminating automatic image scaling.

Recommended sizes to provide: 16x16, 32x32, 48x48 at minimum, and
larger images (64x64, 128x128) if you have them.

See also `Window::set_default_icon_list` to set the icon
for all windows in your application in one go.

Note that transient windows (those who have been set transient for another
window using `GtkWindowExt::set_transient_for`) will inherit their
icon from their transient parent. So there’s no need to explicitly
set the icon on transient windows.
## `list`
list of `gdk_pixbuf::Pixbuf`
<!-- trait GtkWindowExt::fn set_icon_name -->
Sets the icon for the window from a named themed icon.
See the docs for `IconTheme` for more details.
On some platforms, the window icon is not used at all.

Note that this has nothing to do with the WM_ICON_NAME
property which is mentioned in the ICCCM.
## `name`
the name of the themed icon
<!-- trait GtkWindowExt::fn set_keep_above -->
Asks to keep `self` above, so that it stays on top. Note that
you shouldn’t assume the window is definitely above afterward,
because other entities (e.g. the user or
[window manager][gtk-X11-arch]) could not keep it above,
and not all window managers support keeping windows above. But
normally the window will end kept above. Just don’t write code
that crashes if not.

It’s permitted to call this function before showing a window,
in which case the window will be kept above when it appears onscreen
initially.

You can track the above state via the “window-state-event” signal
on `Widget`.

Note that, according to the
[Extended Window Manager Hints Specification](http://www.freedesktop.org/Standards/wm-spec),
the above state is mainly meant for user preferences and should not
be used by applications e.g. for drawing attention to their
dialogs.
## `setting`
whether to keep `self` above other windows
<!-- trait GtkWindowExt::fn set_keep_below -->
Asks to keep `self` below, so that it stays in bottom. Note that
you shouldn’t assume the window is definitely below afterward,
because other entities (e.g. the user or
[window manager][gtk-X11-arch]) could not keep it below,
and not all window managers support putting windows below. But
normally the window will be kept below. Just don’t write code
that crashes if not.

It’s permitted to call this function before showing a window,
in which case the window will be kept below when it appears onscreen
initially.

You can track the below state via the “window-state-event” signal
on `Widget`.

Note that, according to the
[Extended Window Manager Hints Specification](http://www.freedesktop.org/Standards/wm-spec),
the above state is mainly meant for user preferences and should not
be used by applications e.g. for drawing attention to their
dialogs.
## `setting`
whether to keep `self` below other windows
<!-- trait GtkWindowExt::fn set_mnemonic_modifier -->
Sets the mnemonic modifier for this window.
## `modifier`
the modifier mask used to activate
 mnemonics on this window.
<!-- trait GtkWindowExt::fn set_mnemonics_visible -->
Sets the `Window:mnemonics-visible` property.
## `setting`
the new value
<!-- trait GtkWindowExt::fn set_modal -->
Sets a window modal or non-modal. Modal windows prevent interaction
with other windows in the same application. To keep modal dialogs
on top of main application windows, use
`GtkWindowExt::set_transient_for` to make the dialog transient for the
parent; most [window managers][gtk-X11-arch]
will then disallow lowering the dialog below the parent.
## `modal`
whether the window is modal
<!-- trait GtkWindowExt::fn set_position -->
Sets a position constraint for this window. If the old or new
constraint is `WindowPosition::CenterAlways`, this will also cause
the window to be repositioned to satisfy the new constraint.
## `position`
a position constraint.
<!-- trait GtkWindowExt::fn set_resizable -->
Sets whether the user can resize a window. Windows are user resizable
by default.
## `resizable`
`true` if the user can resize this window
<!-- trait GtkWindowExt::fn set_role -->
This function is only useful on X11, not with other GTK+ targets.

In combination with the window title, the window role allows a
[window manager][gtk-X11-arch] to identify "the
same" window when an application is restarted. So for example you
might set the “toolbox” role on your app’s toolbox window, so that
when the user restarts their session, the window manager can put
the toolbox back in the same place.

If a window already has a unique title, you don’t need to set the
role, since the WM can use the title to identify the window when
restoring the session.
## `role`
unique identifier for the window to be used when restoring a session
<!-- trait GtkWindowExt::fn set_screen -->
Sets the `gdk::Screen` where the `self` is displayed; if
the window is already mapped, it will be unmapped, and
then remapped on the new screen.
## `screen`
a `gdk::Screen`.
<!-- trait GtkWindowExt::fn set_skip_pager_hint -->
Windows may set a hint asking the desktop environment not to display
the window in the pager. This function sets this hint.
(A "pager" is any desktop navigation tool such as a workspace
switcher that displays a thumbnail representation of the windows
on the screen.)
## `setting`
`true` to keep this window from appearing in the pager
<!-- trait GtkWindowExt::fn set_skip_taskbar_hint -->
Windows may set a hint asking the desktop environment not to display
the window in the task bar. This function sets this hint.
## `setting`
`true` to keep this window from appearing in the task bar
<!-- trait GtkWindowExt::fn set_startup_id -->
Startup notification identifiers are used by desktop environment to
track application startup, to provide user feedback and other
features. This function changes the corresponding property on the
underlying `gdk::Window`. Normally, startup identifier is managed
automatically and you should only use this function in special cases
like transferring focus from other processes. You should use this
function before calling `Window::present` or any equivalent
function generating a window map event.

This function is only useful on X11, not with other GTK+ targets.
## `startup_id`
a string with startup-notification identifier
<!-- trait GtkWindowExt::fn set_title -->
Sets the title of the `Window`. The title of a window will be
displayed in its title bar; on the X Window System, the title bar
is rendered by the [window manager][gtk-X11-arch],
so exactly how the title appears to users may vary
according to a user’s exact configuration. The title should help a
user distinguish this window from other windows they may have
open. A good title might include the application name and current
document filename, for example.
## `title`
title of the window
<!-- trait GtkWindowExt::fn set_titlebar -->
Sets a custom titlebar for `self`.

A typical widget used here is `HeaderBar`, as it provides various features
expected of a titlebar while allowing the addition of child widgets to it.

If you set a custom titlebar, GTK+ will do its best to convince
the window manager not to put its own titlebar on the window.
Depending on the system, this function may not work for a window
that is already visible, so you set the titlebar before calling
`WidgetExt::show`.
## `titlebar`
the widget to use as titlebar
<!-- trait GtkWindowExt::fn set_transient_for -->
Dialog windows should be set transient for the main application
window they were spawned from. This allows
[window managers][gtk-X11-arch] to e.g. keep the
dialog on top of the main window, or center the dialog over the
main window. `Dialog::new_with_buttons` and other convenience
functions in GTK+ will sometimes call
`GtkWindowExt::set_transient_for` on your behalf.

Passing `None` for `parent` unsets the current transient window.

On Wayland, this function can also be used to attach a new
`WindowType::Popup` to a `WindowType::Toplevel` parent already mapped
on screen so that the `WindowType::Popup` will be created as a
subsurface-based window `gdk::WindowType::Subsurface` which can be
positioned at will relatively to the `WindowType::Toplevel` surface.

On Windows, this function puts the child window on top of the parent,
much as the window manager would have done on X.
## `parent`
parent window, or `None`
<!-- trait GtkWindowExt::fn set_type_hint -->
By setting the type hint for the window, you allow the window
manager to decorate and handle the window in a way which is
suitable to the function of the window in your application.

This function should be called before the window becomes visible.

`Dialog::new_with_buttons` and other convenience functions in GTK+
will sometimes call `GtkWindowExt::set_type_hint` on your behalf.
## `hint`
the window type
<!-- trait GtkWindowExt::fn set_urgency_hint -->
Windows may set a hint asking the desktop environment to draw
the users attention to the window. This function sets this hint.
## `setting`
`true` to mark this window as urgent
<!-- trait GtkWindowExt::fn set_wmclass -->
Don’t use this function. It sets the X Window System “class” and
“name” hints for a window. According to the ICCCM, you should
always set these to the same value for all windows in an
application, and GTK+ sets them to that value by default, so calling
this function is sort of pointless. However, you may want to call
`GtkWindowExt::set_role` on each window in your application, for the
benefit of the session manager. Setting the role allows the window
manager to restore window positions when loading a saved session.

# Deprecated since 3.22

## `wmclass_name`
window name hint
## `wmclass_class`
window class hint
<!-- trait GtkWindowExt::fn stick -->
Asks to stick `self`, which means that it will appear on all user
desktops. Note that you shouldn’t assume the window is definitely
stuck afterward, because other entities (e.g. the user or
[window manager][gtk-X11-arch] could unstick it
again, and some window managers do not support sticking
windows. But normally the window will end up stuck. Just don't
write code that crashes if not.

It’s permitted to call this function before showing a window.

You can track stickiness via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn unfullscreen -->
Asks to toggle off the fullscreen state for `self`. Note that you
shouldn’t assume the window is definitely not full screen
afterward, because other entities (e.g. the user or
[window manager][gtk-X11-arch]) could fullscreen it
again, and not all window managers honor requests to unfullscreen
windows. But normally the window will end up restored to its normal
state. Just don’t write code that crashes if not.

You can track the fullscreen state via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn unmaximize -->
Asks to unmaximize `self`. Note that you shouldn’t assume the
window is definitely unmaximized afterward, because other entities
(e.g. the user or [window manager][gtk-X11-arch])
could maximize it again, and not all window
managers honor requests to unmaximize. But normally the window will
end up unmaximized. Just don’t write code that crashes if not.

You can track maximization via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn unstick -->
Asks to unstick `self`, which means that it will appear on only
one of the user’s desktops. Note that you shouldn’t assume the
window is definitely unstuck afterward, because other entities
(e.g. the user or [window manager][gtk-X11-arch]) could
stick it again. But normally the window will
end up stuck. Just don’t write code that crashes if not.

You can track stickiness via the “window-state-event” signal
on `Widget`.
<!-- trait GtkWindowExt::fn connect_activate_default -->
The ::activate-default signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user activates the default widget
of `window`.
<!-- trait GtkWindowExt::fn connect_activate_focus -->
The ::activate-focus signal is a
[keybinding signal][`BindingSignal`]
which gets emitted when the user activates the currently
focused widget of `window`.
<!-- trait GtkWindowExt::fn connect_enable_debugging -->
The ::enable-debugging signal is a [keybinding signal][`BindingSignal`]
which gets emitted when the user enables or disables interactive
debugging. When `toggle` is `true`, interactive debugging is toggled
on or off, when it is `false`, the debugger will be pointed at the
widget under the pointer.

The default bindings for this signal are Ctrl-Shift-I
and Ctrl-Shift-D.
## `toggle`
toggle the debugger

# Returns

`true` if the key binding was handled
<!-- trait GtkWindowExt::fn connect_keys_changed -->
The ::keys-changed signal gets emitted when the set of accelerators
or mnemonics that are associated with `window` changes.
<!-- trait GtkWindowExt::fn get_property_accept_focus -->
Whether the window should receive the input focus.
<!-- trait GtkWindowExt::fn set_property_accept_focus -->
Whether the window should receive the input focus.
<!-- trait GtkWindowExt::fn get_property_application -->
The `Application` associated with the window.

The application will be kept alive for at least as long as it
has any windows associated with it (see `gio::ApplicationExt::hold`
for a way to keep it alive without windows).

Normally, the connection between the application and the window
will remain until the window is destroyed, but you can explicitly
remove it by setting the :application property to `None`.
<!-- trait GtkWindowExt::fn set_property_application -->
The `Application` associated with the window.

The application will be kept alive for at least as long as it
has any windows associated with it (see `gio::ApplicationExt::hold`
for a way to keep it alive without windows).

Normally, the connection between the application and the window
will remain until the window is destroyed, but you can explicitly
remove it by setting the :application property to `None`.
<!-- trait GtkWindowExt::fn get_property_attached_to -->
The widget to which this window is attached.
See `GtkWindowExt::set_attached_to`.

Examples of places where specifying this relation is useful are
for instance a `Menu` created by a `ComboBox`, a completion
popup window created by `Entry` or a typeahead search entry
created by `TreeView`.
<!-- trait GtkWindowExt::fn set_property_attached_to -->
The widget to which this window is attached.
See `GtkWindowExt::set_attached_to`.

Examples of places where specifying this relation is useful are
for instance a `Menu` created by a `ComboBox`, a completion
popup window created by `Entry` or a typeahead search entry
created by `TreeView`.
<!-- trait GtkWindowExt::fn get_property_decorated -->
Whether the window should be decorated by the window manager.
<!-- trait GtkWindowExt::fn set_property_decorated -->
Whether the window should be decorated by the window manager.
<!-- trait GtkWindowExt::fn get_property_deletable -->
Whether the window frame should have a close button.
<!-- trait GtkWindowExt::fn set_property_deletable -->
Whether the window frame should have a close button.
<!-- trait GtkWindowExt::fn get_property_focus_on_map -->
Whether the window should receive the input focus when mapped.
<!-- trait GtkWindowExt::fn set_property_focus_on_map -->
Whether the window should receive the input focus when mapped.
<!-- trait GtkWindowExt::fn get_property_focus_visible -->
Whether 'focus rectangles' are currently visible in this window.

This property is maintained by GTK+ based on user input
and should not be set by applications.
<!-- trait GtkWindowExt::fn set_property_focus_visible -->
Whether 'focus rectangles' are currently visible in this window.

This property is maintained by GTK+ based on user input
and should not be set by applications.
<!-- trait GtkWindowExt::fn get_property_gravity -->
The window gravity of the window. See `GtkWindowExt::move` and `gdk::Gravity` for
more details about window gravity.
<!-- trait GtkWindowExt::fn set_property_gravity -->
The window gravity of the window. See `GtkWindowExt::move` and `gdk::Gravity` for
more details about window gravity.
<!-- trait GtkWindowExt::fn get_property_hide_titlebar_when_maximized -->
Whether the titlebar should be hidden during maximization.
<!-- trait GtkWindowExt::fn set_property_hide_titlebar_when_maximized -->
Whether the titlebar should be hidden during maximization.
<!-- trait GtkWindowExt::fn get_property_icon_name -->
The :icon-name property specifies the name of the themed icon to
use as the window icon. See `IconTheme` for more details.
<!-- trait GtkWindowExt::fn set_property_icon_name -->
The :icon-name property specifies the name of the themed icon to
use as the window icon. See `IconTheme` for more details.
<!-- trait GtkWindowExt::fn get_property_mnemonics_visible -->
Whether mnemonics are currently visible in this window.

This property is maintained by GTK+ based on user input,
and should not be set by applications.
<!-- trait GtkWindowExt::fn set_property_mnemonics_visible -->
Whether mnemonics are currently visible in this window.

This property is maintained by GTK+ based on user input,
and should not be set by applications.
<!-- trait GtkWindowExt::fn set_property_startup_id -->
The :startup-id is a write-only property for setting window's
startup notification identifier. See `GtkWindowExt::set_startup_id`
for more details.
<!-- trait GtkWindowExt::fn get_property_transient_for -->
The transient parent of the window. See `GtkWindowExt::set_transient_for` for
more details about transient windows.
<!-- trait GtkWindowExt::fn set_property_transient_for -->
The transient parent of the window. See `GtkWindowExt::set_transient_for` for
more details about transient windows.
<!-- struct WindowGroup -->
A `WindowGroup` restricts the effect of grabs to windows
in the same group, thereby making window groups almost behave
like separate applications.

A window can be a member in at most one window group at a time.
Windows that have not been explicitly assigned to a group are
implicitly treated like windows of the default window group.

`WindowGroup` objects are referenced by each window in the group,
so once you have added all windows to a `WindowGroup`, you can drop
the initial reference to the window group with `gobject::ObjectExt::unref`. If the
windows in the window group are subsequently destroyed, then they will
be removed from the window group and drop their references on the window
group; when all window have been removed, the window group will be
freed.

# Implements

[`WindowGroupExt`](trait.WindowGroupExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait WindowGroupExt -->
Trait containing all `WindowGroup` methods.

# Implementors

[`WindowGroup`](struct.WindowGroup.html)
<!-- impl WindowGroup::fn new -->
Creates a new `WindowGroup` object. Grabs added with
`WidgetExt::grab_add` only affect windows within the same `WindowGroup`.

# Returns

a new `WindowGroup`.
<!-- trait WindowGroupExt::fn add_window -->
Adds a window to a `WindowGroup`.
## `window`
the `Window` to add
<!-- trait WindowGroupExt::fn get_current_device_grab -->
Returns the current grab widget for `device`, or `None` if none.
## `device`
a `gdk::Device`

# Returns

The grab widget, or `None`
<!-- trait WindowGroupExt::fn get_current_grab -->
Gets the current grab widget of the given group,
see `WidgetExt::grab_add`.

# Returns

the current grab widget of the group
<!-- trait WindowGroupExt::fn list_windows -->
Returns a list of the ``GtkWindows`` that belong to `self`.

# Returns

A
 newly-allocated list of windows inside the group.
<!-- trait WindowGroupExt::fn remove_window -->
Removes a window from a `WindowGroup`.
## `window`
the `Window` to remove
<!-- enum WindowPosition -->
Window placement can be influenced using this enumeration. Note that
using `WindowPosition::CenterAlways` is almost always a bad idea.
It won’t necessarily work well with all window managers or on all windowing systems.
<!-- enum WindowPosition::variant None -->
No influence is made on placement.
<!-- enum WindowPosition::variant Center -->
Windows should be placed in the center of the screen.
<!-- enum WindowPosition::variant Mouse -->
Windows should be placed at the current mouse position.
<!-- enum WindowPosition::variant CenterAlways -->
Keep window centered as it changes size, etc.
<!-- enum WindowPosition::variant CenterOnParent -->
Center the window on its transient
 parent (see `GtkWindowExt::set_transient_for`).
<!-- enum WindowType -->
A `Window` can be one of these types. Most things you’d consider a
“window” should have type `WindowType::Toplevel`; windows with this type
are managed by the window manager and have a frame by default (call
`GtkWindowExt::set_decorated` to toggle the frame). Windows with type
`WindowType::Popup` are ignored by the window manager; window manager
keybindings won’t work on them, the window manager won’t decorate the
window with a frame, many GTK+ features that rely on the window
manager will not work (e.g. resize grips and
maximization/minimization). `WindowType::Popup` is used to implement
widgets such as `Menu` or tooltips that you normally don’t think of
as windows per se. Nearly all windows should be `WindowType::Toplevel`.
In particular, do not use `WindowType::Popup` just to turn off
the window borders; use `GtkWindowExt::set_decorated` for that.
<!-- enum WindowType::variant Toplevel -->
A regular window, such as a dialog.
<!-- enum WindowType::variant Popup -->
A special window such as a tooltip.
<!-- enum WrapMode -->
Describes a type of line wrapping.
<!-- enum WrapMode::variant None -->
do not wrap lines; just make the text area wider
<!-- enum WrapMode::variant Char -->
wrap text, breaking lines anywhere the cursor can
 appear (between characters, usually - if you want to be technical,
 between graphemes, see `pango_get_log_attrs`)
<!-- enum WrapMode::variant Word -->
wrap text, breaking lines in between words
<!-- enum WrapMode::variant WordChar -->
wrap text, breaking lines in between words, or if
 that is not enough, also between graphemes