A #GtkAllocation-struct of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See [GtkWidget’s geometry management section][geometry-management] for more information. The GtkAboutDialog 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. GtkAboutDialog 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 #GtkAboutDialog::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 GtkAboutDialog 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 GtkAboutDialog, as shown in the following example: |[<!-- language="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 #GtkAboutDialog like any other #GtkDialog, e.g. using gtk_dialog_run(). In this case, you might need to know that the “Close” button returns the #GTK_RESPONSE_CANCEL response id. Creates a new #GtkAboutDialog. a newly created #GtkAboutDialog Creates a new section in the Credits page. A #GtkAboutDialog The name of the section The people who belong to that section Returns the string which are displayed in the artists tab of the secondary credits dialog. A %NULL-terminated string array containing the artists. The array is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the string which are displayed in the authors tab of the secondary credits dialog. A %NULL-terminated string array containing the authors. The array is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the comments string. The comments. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the copyright string. The copyright string. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the string which are displayed in the documenters tab of the secondary credits dialog. A %NULL-terminated string array containing the documenters. The array is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the license information. The license information. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Retrieves the license set using gtk_about_dialog_set_license_type() a #GtkLicense value a #GtkAboutDialog Returns the pixbuf displayed as logo in the about dialog. 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 g_object_ref() on it. a #GtkAboutDialog Returns the icon name displayed as logo in the about dialog. 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. a #GtkAboutDialog Returns the program name displayed in the about dialog. The program name. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the translator credits string which is displayed in the translators tab of the secondary credits dialog. The translator credits string. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the version string. The version string. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the website URL. The website URL. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns the label used for the website link. The label used for the website link. The string is owned by the about dialog and must not be modified. a #GtkAboutDialog Returns whether the license text in @about is automatically wrapped. %TRUE if the license text is wrapped a #GtkAboutDialog Sets the strings which are displayed in the artists tab of the secondary credits dialog. a #GtkAboutDialog a %NULL-terminated array of strings Sets the strings which are displayed in the authors tab of the secondary credits dialog. a #GtkAboutDialog a %NULL-terminated array of strings Sets the comments string to display in the about dialog. This should be a short string of one or two lines. a #GtkAboutDialog a comments string Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. a #GtkAboutDialog the copyright string Sets the strings which are displayed in the documenters tab of the secondary credits dialog. a #GtkAboutDialog a %NULL-terminated array of strings Sets the license information to be displayed in the secondary license dialog. If @license is %NULL, the license button is hidden. a #GtkAboutDialog the license information or %NULL Sets the license of the application showing the @about dialog from a list of known licenses. This function overrides the license set using gtk_about_dialog_set_license(). a #GtkAboutDialog the type of license Sets the pixbuf to be displayed as logo in the about dialog. If it is %NULL, the default window icon set with gtk_window_set_default_icon() will be used. a #GtkAboutDialog a #GdkPixbuf, or %NULL Sets the pixbuf to be displayed as logo in the about dialog. If it is %NULL, the default window icon set with gtk_window_set_default_icon() will be used. a #GtkAboutDialog an icon name, or %NULL Sets the name to display in the about dialog. If this is not set, it defaults to g_get_application_name(). a #GtkAboutDialog the program name 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: |[<!-- language="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 #GtkAboutDialog will detect if “translator-credits” is untranslated and hide the tab. a #GtkAboutDialog the translator credits Sets the version string to display in the about dialog. a #GtkAboutDialog the version string Sets the URL to use for the website link. a #GtkAboutDialog a URL string starting with "http://" Sets the label to be used for the website link. a #GtkAboutDialog the label used for the website link Sets whether the license text in @about is automatically wrapped. a #GtkAboutDialog whether to wrap the license The people who contributed artwork to the program, as a %NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The authors of the program, as a %NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. 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. Copyright information for the program. The people documenting the program, as a %NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. 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-%NULL value, the #GtkAboutDialog:license-type property is set to %GTK_LICENSE_CUSTOM as a side effect. The license of the program, as a value of the %GtkLicense enumeration. The #GtkAboutDialog will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If %GTK_LICENSE_UNKNOWN is used, the link used will be the same specified in the #GtkAboutDialog:website property. If %GTK_LICENSE_CUSTOM is used, the current contents of the #GtkAboutDialog:license property are used. For any other #GtkLicense value, the contents of the #GtkAboutDialog:license property are also set by this property as a side effect. A logo for the about box. If it is %NULL, the default window icon set with gtk_window_set_default_icon() will be used. A named icon to use as the logo for the about box. This property overrides the #GtkAboutDialog:logo property. The name of the program. If this is not set, it defaults to g_get_application_name(). 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. The version of the program. The URL for the link to the website of the program. This should be a string starting with "http://. The label for the link to the website of the program. Whether to wrap the text in the license dialog. 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(). %TRUE if the link has been activated the URI that is activated Accelerator flags used with gtk_accel_group_connect(). Accelerator is visible Accelerator not removable Mask A #GtkAccelGroup represents a group of keyboard accelerators, typically attached to a toplevel #GtkWindow (with gtk_window_add_accel_group()). Usually you won’t need to create a #GtkAccelGroup directly; instead, when using #GtkUIManager, GTK+ automatically sets up the accelerators for your menus in the ui manager’s #GtkAccelGroup. 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 gtk_label_new_with_mnemonic(). Menu items can have both accelerators and mnemonics, of course. Creates a new #GtkAccelGroup. a new #GtkAccelGroup object Finds the #GtkAccelGroup to which @closure is connected; see gtk_accel_group_connect(). the #GtkAccelGroup to which @closure is connected, or %NULL a #GClosure Finds the first accelerator in @accel_group that matches @accel_key and @accel_mods, and activates it. %TRUE if an accelerator was activated and handled this keypress a #GtkAccelGroup the quark for the accelerator name the #GObject, usually a #GtkWindow, on which to activate the accelerator accelerator keyval from a key event keyboard state mask from a key event Installs an accelerator in this group. When @accel_group 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. the accelerator group to install an accelerator in key value of the accelerator modifier combination of the accelerator a flag mask to configure this accelerator closure to be executed upon accelerator activation Installs an accelerator in this group, using an accelerator path to look up the appropriate key and modifiers (see gtk_accel_map_add_entry()). When @accel_group 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 #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). the accelerator group to install an accelerator in path used for determining key and modifiers closure to be executed upon accelerator activation Removes an accelerator previously installed through gtk_accel_group_connect(). Since 2.20 @closure can be %NULL. %TRUE if the closure was found and got disconnected the accelerator group to remove an accelerator from the closure to remove from this accelerator group, or %NULL to remove all closures Removes an accelerator previously installed through gtk_accel_group_connect(). %TRUE if there was an accelerator which could be removed, %FALSE otherwise the accelerator group to install an accelerator in key value of the accelerator modifier combination of the accelerator Finds the first entry in an accelerator group for which @find_func returns %TRUE and returns its #GtkAccelKey. the key of the first entry passing @find_func. The key is owned by GTK+ and must not be freed. a #GtkAccelGroup a function to filter the entries of @accel_group with data to pass to @find_func Locks are added and removed using gtk_accel_group_lock() and gtk_accel_group_unlock(). %TRUE if there are 1 or more locks on the @accel_group, %FALSE otherwise. a #GtkAccelGroup Gets a #GdkModifierType representing the mask for this @accel_group. For example, #GDK_CONTROL_MASK, #GDK_SHIFT_MASK, etc. the modifier mask for this accel group. a #GtkAccelGroup Locks the given accelerator group. Locking an acelerator group prevents the accelerators contained within it to be changed during runtime. Refer to gtk_accel_map_change_entry() about runtime accelerator changes. If called more than once, @accel_group remains locked until gtk_accel_group_unlock() has been called an equivalent number of times. a #GtkAccelGroup Queries an accelerator group for all entries matching @accel_key and @accel_mods. an array of @n_entries #GtkAccelGroupEntry elements, or %NULL. The array is owned by GTK+ and must not be freed. the accelerator group to query key value of the accelerator modifier combination of the accelerator location to return the number of entries found, or %NULL Undoes the last call to gtk_accel_group_lock() on this @accel_group. a #GtkAccelGroup The accel-activate signal is an implementation detail of #GtkAccelGroup and not meant to be used by applications. %TRUE if the accelerator was activated the object on which the accelerator was activated the accelerator keyval the modifier combination of the accelerator The accel-changed signal is emitted when an entry is added to or removed from the accel group. Widgets like #GtkAccelLabel which display an associated accelerator should connect to this signal, and rebuild their visual representation if the @accel_closure is theirs. the accelerator keyval the modifier combination of the accelerator the #GClosure of the accelerator The parent class. The accelerator keyval The accelerator modifiers The accelerator flags The #GtkAccelLabel widget is a subclass of #GtkLabel 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 gtk_accel_label_set_accel()). Instead, the #GtkAccelLabel displays the accelerators which have been added to a particular widget. This widget is set by calling gtk_accel_label_set_accel_widget(). For example, a #GtkMenuItem widget may have an accelerator added to emit the “activate” signal when the “Ctrl+S” key combination is pressed. A #GtkAccelLabel is created and added to the #GtkMenuItem, and gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the second argument. The #GtkAccelLabel will now display “Ctrl+S” after its label. Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem) automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls gtk_accel_label_set_accel_widget() to set it up for you. A #GtkAccelLabel will only display accelerators which have %GTK_ACCEL_VISIBLE set (see #GtkAccelFlags). A #GtkAccelLabel 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. |[<!-- language="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 |[<!-- language="plain" --> label ╰── accelerator ]| Like #GtkLabel, GtkAccelLabel has a main CSS node with the name label. It adds a subnode with name accelerator. Creates a new #GtkAccelLabel. a new #GtkAccelLabel. the label string. Must be non-%NULL. Gets the keyval and modifier mask set with gtk_accel_label_set_accel(). a #GtkAccelLabel return location for the keyval return location for the modifier mask Fetches the widget monitored by this accelerator label. See gtk_accel_label_set_accel_widget(). the object monitored by the accelerator label, or %NULL. a #GtkAccelLabel Returns the width needed to display the accelerator key(s). This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't be needed by applications. the width needed to display the accelerator key(s). a #GtkAccelLabel. 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. always returns %FALSE. a #GtkAccelLabel. Manually sets a keyval and modifier mask as the accelerator rendered by @accel_label. 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. a #GtkAccelLabel a keyval, or 0 the modifier mask for the accel Sets the closure to be monitored by this accelerator label. The closure must be connected to an accelerator group; see gtk_accel_group_connect(). Passing %NULL for @accel_closure will dissociate @accel_label from its current closure, if any. a #GtkAccelLabel the closure to monitor for accelerator changes, or %NULL Sets the widget to be monitored by this accelerator label. Passing %NULL for @accel_widget will dissociate @accel_label from its current widget, if any. a #GtkAccelLabel the widget to be monitored, or %NULL Accelerator maps are used to define runtime configurable accelerators. Functions for manipulating them are are usually used by higher level convenience mechanisms like #GtkUIManager and are thus considered “low-level”. You’ll want to use them if you’re manually creating menus that should have user-configurable accelerators. An accelerator is uniquely defined by: - accelerator path - accelerator key - accelerator modifiers The accelerator path must consist of “<WINDOWTYPE>/Category1/Category2/.../Action”, where WINDOWTYPE should be a unique application-specific identifier that corresponds to the kind of window the accelerator is being used in, e.g. “Gimp-Image”, “Abiword-Document” or “Gnumeric-Settings”. The “Category1/.../Action” portion is most appropriately chosen by the action the accelerator triggers, i.e. for accelerators on menu items, choose the item’s menu path, e.g. “File/Save As”, “Image/View/Zoom” or “Edit/Select All”. So a full valid accelerator path may look like: “<Gimp-Toolbox>/File/Dialogs/Tool Options...”. All accelerators are stored inside one global #GtkAccelMap that can be obtained using gtk_accel_map_get(). See [Monitoring changes][monitoring-changes] for additional details. # Manipulating accelerators New accelerators can be added using gtk_accel_map_add_entry(). To search for specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of existing accelerators should be done using gtk_accel_map_change_entry(). In order to avoid having some accelerators changed, they can be locked using gtk_accel_map_lock_path(). Unlocking is done using gtk_accel_map_unlock_path(). # Saving and loading accelerator maps Accelerator maps can be saved to and loaded from some external resource. For simple saving and loading from file, gtk_accel_map_save() and gtk_accel_map_load() are provided. Saving and loading can also be done by providing file descriptor to gtk_accel_map_save_fd() and gtk_accel_map_load_fd(). # Monitoring changes #GtkAccelMap object is only useful for monitoring changes of accelerators. By connecting to #GtkAccelMap::changed signal, one can monitor changes of all accelerators. It is also possible to monitor only single accelerator path by using it as a detail of the #GtkAccelMap::changed signal. Registers a new accelerator with the global accelerator map. This function should only be called once per @accel_path with the canonical @accel_key and @accel_mods for this path. To change the accelerator during runtime programatically, use gtk_accel_map_change_entry(). Set @accel_key and @accel_mods to 0 to request a removal of the accelerator. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). valid accelerator path the accelerator key the accelerator modifiers Adds a filter to the global list of accel path filters. Accel map entries whose accel path matches one of the filters are skipped by gtk_accel_map_foreach(). This function is intended for GTK+ modules that create their own menus, but don’t want them to be saved into the applications accelerator map dump. a pattern (see #GPatternSpec) Changes the @accel_key and @accel_mods currently associated with @accel_path. Due to conflicts with other accelerators, a change may not always be possible, @replace indicates whether other accelerators may be deleted to resolve such conflicts. A change will only occur if all conflicts could be resolved (which might not be the case if conflicting accelerators are locked). Successful changes are indicated by a %TRUE return value. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). %TRUE if the accelerator could be changed, %FALSE otherwise a valid accelerator path the new accelerator key the new accelerator modifiers %TRUE if other accelerators may be deleted upon conflicts Loops over the entries in the accelerator map whose accel path doesn’t match any of the filters added with gtk_accel_map_add_filter(), and execute @foreach_func on each. The signature of @foreach_func is that of #GtkAccelMapForeach, the @changed parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). data to be passed into @foreach_func function to be executed for each accel map entry which is not filtered out Loops over all entries in the accelerator map, and execute @foreach_func on each. The signature of @foreach_func is that of #GtkAccelMapForeach, the @changed parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). data to be passed into @foreach_func function to be executed for each accel map entry Gets the singleton global #GtkAccelMap object. This object is useful only for notification of changes to the accelerator map via the ::changed signal; it isn’t a parameter to the other accelerator map functions. the global #GtkAccelMap object Parses a file previously saved with gtk_accel_map_save() for accelerator specifications, and propagates them accordingly. a file containing accelerator specifications, in the GLib file name encoding Filedescriptor variant of gtk_accel_map_load(). Note that the file descriptor will not be closed by this function. a valid readable file descriptor #GScanner variant of gtk_accel_map_load(). a #GScanner which has already been provided with an input file Locks the given accelerator path. If the accelerator map doesn’t yet contain an entry for @accel_path, a new one is created. Locking an accelerator path prevents its accelerator from being changed during runtime. A locked accelerator path can be unlocked by gtk_accel_map_unlock_path(). Refer to gtk_accel_map_change_entry() for information about runtime accelerator changes. If called more than once, @accel_path remains locked until gtk_accel_map_unlock_path() has been called an equivalent number of times. Note that locking of individual accelerator paths is independent from locking the #GtkAccelGroup containing them. For runtime accelerator changes to be possible, both the accelerator path and its #GtkAccelGroup have to be unlocked. a valid accelerator path Looks up the accelerator entry for @accel_path and fills in @key. %TRUE if @accel_path is known, %FALSE otherwise a valid accelerator path the accelerator key to be filled in (optional) Saves current accelerator specifications (accelerator path, key and modifiers) to @file_name. The file is written in a format suitable to be read back in by gtk_accel_map_load(). the name of the file to contain accelerator specifications, in the GLib file name encoding Filedescriptor variant of gtk_accel_map_save(). Note that the file descriptor will not be closed by this function. a valid writable file descriptor Undoes the last call to gtk_accel_map_lock_path() on this @accel_path. Refer to gtk_accel_map_lock_path() for information about accelerator path locking. a valid accelerator path Notifies of a change in the global accelerator map. The path is also used as the detail for the signal, so it is possible to connect to changed::`accel_path`. the path of the accelerator that changed the key value for the new accelerator the modifier mask for the new accelerator User data passed to gtk_accel_map_foreach() or gtk_accel_map_foreach_unfiltered() Accel path of the current accelerator Key of the current accelerator Modifiers of the current accelerator Changed flag of the accelerator (if %TRUE, accelerator has changed during runtime and would need to be saved during an accelerator dump) The #GtkAccessible class is the base class for accessible implementations for #GtkWidget subclasses. It is a thin wrapper around #AtkObject, which adds facilities for associating a widget with its accessible object. An accessible implementation for a third-party widget should derive from #GtkAccessible and implement the suitable interfaces from ATK, such as #AtkText or #AtkSelection. To establish the connection between the widget class and its corresponding acccessible implementation, override the get_accessible vfunc in #GtkWidgetClass. This function specifies the callback function to be called when the widget corresponding to a GtkAccessible is destroyed. Use gtk_accessible_set_widget() and its vfuncs. a #GtkAccessible This function specifies the callback function to be called when the widget corresponding to a GtkAccessible is destroyed. Use gtk_accessible_set_widget() and its vfuncs. a #GtkAccessible Gets the #GtkWidget corresponding to the #GtkAccessible. The returned widget does not have a reference added, so you do not need to unref it. pointer to the #GtkWidget corresponding to the #GtkAccessible, or %NULL. a #GtkAccessible Sets the #GtkWidget corresponding to the #GtkAccessible. @accessible will not hold a reference to @widget. It is the caller’s responsibility to ensure that when @widget is destroyed, the widget is unset by calling this function again with @widget set to %NULL. a #GtkAccessible a #GtkWidget or %NULL to unset a #GtkAccessible > In GTK+ 3.10, GtkAction has been deprecated. Use #GAction > instead, and associate actions with #GtkActionable widgets. Use > #GMenuModel for creating menus with gtk_menu_new_from_model(). Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself. As well as the callback that is called when the action gets activated, the following also gets associated with the action: - a name (not translated, for path lookup) - a label (translated, for display) - an accelerator - whether label indicates a stock id - a tooltip (optional, translated) - a toolbar label (optional, shorter than label) The action will also have some state information: - visible (shown/hidden) - sensitive (enabled/disabled) Apart from regular actions, there are [toggle actions][GtkToggleAction], which can be toggled between two states and [radio actions][GtkRadioAction], of which only one in a group can be in the “active” state. Other actions can be implemented as #GtkAction subclasses. Each action can have one or more proxy widgets. To act as an action proxy, widget needs to implement #GtkActivatable interface. Proxies mirror the state of the action and should change when the action’s state changes. Properties that are always mirrored by proxies are #GtkAction:sensitive and #GtkAction:visible. #GtkAction:gicon, #GtkAction:icon-name, #GtkAction:label, #GtkAction:short-label and #GtkAction:stock-id properties are only mirorred if proxy widget has #GtkActivatable:use-action-appearance property set to %TRUE. When the proxy is activated, it should activate its action. Creates a new #GtkAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). See the [UI Definition section][XML-UI] for information on allowed action names. Use #GAction instead, associating it to a widget with #GtkActionable or creating a #GtkMenu with gtk_menu_new_from_model() a new #GtkAction A unique name for the action the label displayed in menu items and on buttons, or %NULL a tooltip for the action, or %NULL the stock icon to display in widgets representing the action, or %NULL Emits the “activate” signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated. It can also be used to manually activate an action. Use g_action_group_activate_action() on a #GAction instead the action object If @action provides a #GtkMenu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu. Use #GAction and #GMenuModel instead, and create a #GtkMenu with gtk_menu_new_from_model() the menu item provided by the action, or %NULL. a #GtkAction Creates a menu item widget that proxies for the given action. Use g_menu_item_new() and associate it with a #GAction instead. a menu item connected to the action. the action object Creates a toolbar item widget that proxies for the given action. Use a #GtkToolItem and associate it with a #GAction using gtk_actionable_set_action_name() instead a toolbar item connected to the action. the action object Emits the “activate” signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated. It can also be used to manually activate an action. Use g_action_group_activate_action() on a #GAction instead the action object Disable activation signals from the action This is needed when updating the state of your proxy #GtkActivatable widget could result in calling gtk_action_activate(), this is a convenience function to avoid recursing in those cases (updating toggle state for instance). Use g_simple_action_set_enabled() to disable the #GSimpleAction instead a #GtkAction Installs the accelerator for @action if @action has an accel path and group. See gtk_action_set_accel_path() and gtk_action_set_accel_group() Since multiple proxies may independently trigger the installation of the accelerator, the @action counts the number of times this function has been called and doesn’t remove the accelerator until gtk_action_disconnect_accelerator() has been called as many times. Use #GAction and the accelerator group on an associated #GtkMenu instead a #GtkAction This function is intended for use by action implementations to create icons displayed in the proxy widgets. Use g_menu_item_set_icon() to set an icon on a #GMenuItem, or gtk_container_add() to add a #GtkImage to a #GtkButton a widget that displays the icon for this action. the action object the size of the icon (#GtkIconSize) that should be created. If @action provides a #GtkMenu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu. Use #GAction and #GMenuModel instead, and create a #GtkMenu with gtk_menu_new_from_model() the menu item provided by the action, or %NULL. a #GtkAction Creates a menu item widget that proxies for the given action. Use g_menu_item_new() and associate it with a #GAction instead. a menu item connected to the action. the action object Creates a toolbar item widget that proxies for the given action. Use a #GtkToolItem and associate it with a #GAction using gtk_actionable_set_action_name() instead a toolbar item connected to the action. the action object Undoes the effect of one call to gtk_action_connect_accelerator(). Use #GAction and the accelerator group on an associated #GtkMenu instead a #GtkAction Returns the accel closure for this action. Use #GAction and #GtkMenu instead, which have no equivalent for getting the accel closure the accel closure for this action. The returned closure is owned by GTK+ and must not be unreffed or modified. the action object Returns the accel path for this action. Use #GAction and the accelerator path on an associated #GtkMenu instead the accel path for this action, or %NULL if none is set. The returned string is owned by GTK+ and must not be freed or modified. the action object Returns whether @action's menu item proxies will always show their image, if available. Use g_menu_item_get_attribute_value() on a #GMenuItem instead %TRUE if the menu item proxies will always show their image a #GtkAction Gets the gicon of @action. Use #GAction instead, and g_menu_item_get_attribute_value() to get an icon from a #GMenuItem associated with a #GAction The action’s #GIcon if one is set. a #GtkAction Gets the icon name of @action. Use #GAction instead, and g_menu_item_get_attribute_value() to get an icon from a #GMenuItem associated with a #GAction the icon name a #GtkAction Checks whether @action is important or not Use #GAction instead, and control and monitor whether labels are shown directly whether @action is important a #GtkAction Gets the label text of @action. Use #GAction instead, and get a label from a menu item with g_menu_item_get_attribute_value(). For #GtkActionable widgets, use the widget-specific API to get a label the label text a #GtkAction Returns the name of the action. Use g_action_get_name() on a #GAction instead the name of the action. The string belongs to GTK+ and should not be freed. the action object Returns the proxy widgets for an action. See also gtk_activatable_get_related_action(). a #GSList of proxy widgets. The list is owned by GTK+ and must not be modified. the action object Returns whether the action itself is sensitive. Note that this doesn’t necessarily mean effective sensitivity. See gtk_action_is_sensitive() for that. Use g_action_get_enabled() on a #GAction instead %TRUE if the action itself is sensitive. the action object Gets the short label text of @action. Use #GAction instead, which has no equivalent of short labels the short label text. a #GtkAction Gets the stock id of @action. Use #GAction instead, which has no equivalent of stock items the stock id a #GtkAction Gets the tooltip text of @action. Use #GAction instead, and get tooltips from associated #GtkActionable widgets with gtk_widget_get_tooltip_text() the tooltip text a #GtkAction Returns whether the action itself is visible. Note that this doesn’t necessarily mean effective visibility. See gtk_action_is_sensitive() for that. Use #GAction instead, and control and monitor the state of #GtkActionable widgets directly %TRUE if the action itself is visible. the action object Checks whether @action is visible when horizontal Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly whether @action is visible when horizontal a #GtkAction Checks whether @action is visible when horizontal Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly whether @action is visible when horizontal a #GtkAction Returns whether the action is effectively sensitive. Use g_action_get_enabled() on a #GAction instead %TRUE if the action and its associated action group are both sensitive. the action object Returns whether the action is effectively visible. Use #GAction instead, and control and monitor the state of #GtkActionable widgets directly %TRUE if the action and its associated action group are both visible. the action object Sets the #GtkAccelGroup in which the accelerator for this action will be installed. Use #GAction and the accelerator group on an associated #GtkMenu instead the action object a #GtkAccelGroup or %NULL Sets the accel path for this action. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). Use #GAction and the accelerator path on an associated #GtkMenu instead the action object the accelerator path Sets whether @action's menu item proxies will ignore the #GtkSettings:gtk-menu-images setting and always show their image, if available. Use this if the menu item would be useless or hard to use without their image. Use g_menu_item_set_icon() on a #GMenuItem instead, if the item should have an image a #GtkAction %TRUE if menuitem proxies should always show their image Sets the icon of @action. Use #GAction instead, and g_menu_item_set_icon() to set an icon on a #GMenuItem associated with a #GAction, or gtk_container_add() to add a #GtkImage to a #GtkButton a #GtkAction the #GIcon to set Sets the icon name on @action Use #GAction instead, and g_menu_item_set_icon() to set an icon on a #GMenuItem associated with a #GAction, or gtk_container_add() to add a #GtkImage to a #GtkButton a #GtkAction the icon name to set Sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not. Use #GAction instead, and control and monitor whether labels are shown directly the action object %TRUE to make the action important Sets the label of @action. Use #GAction instead, and set a label on a menu item with g_menu_item_set_label(). For #GtkActionable widgets, use the widget-specific API to set a label a #GtkAction the label text to set Sets the :sensitive property of the action to @sensitive. Note that this doesn’t necessarily mean effective sensitivity. See gtk_action_is_sensitive() for that. Use g_simple_action_set_enabled() on a #GSimpleAction instead the action object %TRUE to make the action sensitive Sets a shorter label text on @action. Use #GAction instead, which has no equivalent of short labels a #GtkAction the label text to set Sets the stock id on @action Use #GAction instead, which has no equivalent of stock items a #GtkAction the stock id Sets the tooltip text on @action Use #GAction instead, and set tooltips on associated #GtkActionable widgets with gtk_widget_set_tooltip_text() a #GtkAction the tooltip text Sets the :visible property of the action to @visible. Note that this doesn’t necessarily mean effective visibility. See gtk_action_is_visible() for that. Use #GAction instead, and control and monitor the state of #GtkActionable widgets directly the action object %TRUE to make the action visible Sets whether @action is visible when horizontal Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly a #GtkAction whether the action is visible horizontally Sets whether @action is visible when vertical Use #GAction instead, and control and monitor the visibility of associated widgets and menu items directly a #GtkAction whether the action is visible vertically Reenable activation signals from the action Use g_simple_action_set_enabled() to enable the #GSimpleAction instead a #GtkAction The GtkActionGroup this GtkAction is associated with, or NULL (for internal use). Lookup the #GAction using g_action_map_lookup_action() instead If %TRUE, the action's menu item proxies will ignore the #GtkSettings:gtk-menu-images setting and always show their image, if available. Use this property if the menu item would be useless or hard to use without their image. There is no corresponding replacement when using #GAction The #GIcon displayed in the #GtkAction. Note that the stock icon is preferred, if the #GtkAction:stock-id property holds the id of an existing stock icon. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Use the "icon" attribute on a #GMenuItem instead When TRUE, empty menu proxies for this action are hidden. There is no corresponding replacement when using #GAction The name of the icon from the icon theme. Note that the stock icon is preferred, if the #GtkAction:stock-id property holds the id of an existing stock icon, and the #GIcon is preferred if the #GtkAction:gicon property is set. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Use the "icon" attribute on a #GMenuItem instead Whether the action is considered important. When TRUE, toolitem proxies for this action show text in GTK_TOOLBAR_BOTH_HORIZ mode. There is no corresponding replacement when using #GAction The label used for menu items and buttons that activate this action. If the label is %NULL, GTK+ uses the stock label specified via the stock-id property. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Use the "label" attribute on #GMenuItem instead A unique name for the action. Use #GAction:name instead Whether the action is enabled. Use #GAction:enabled and #GSimpleAction:enabled instead A shorter label that may be used on toolbar buttons. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. There is no corresponding replacement when using #GAction The stock icon displayed in widgets representing this action. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. There is no corresponding replacement when using #GAction A tooltip for this action. Use gtk_widget_set_tooltip_text() instead Whether the action is visible. There is no corresponding replacement when using #GAction Whether the toolbar item is visible when the toolbar is in a horizontal orientation. There is no corresponding replacement when using #GAction When %TRUE, toolitem proxies for this action are represented in the toolbar overflow menu. There is no corresponding replacement when using #GAction Whether the toolbar item is visible when the toolbar is in a vertical orientation. There is no corresponding replacement when using #GAction The "activate" signal is emitted when the action is activated. Use #GSimpleAction::activate instead GtkActionBar 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 GtkActionBar has a single CSS node with name actionbar. Creates a new #GtkActionBar widget. a new #GtkActionBar Retrieves the center bar widget of the bar. the center #GtkWidget or %NULL. a #GtkActionBar Adds @child to @action_bar, packed with reference to the end of the @action_bar. A #GtkActionBar the #GtkWidget to be added to @action_bar Adds @child to @action_bar, packed with reference to the start of the @action_bar. A #GtkActionBar the #GtkWidget to be added to @action_bar Sets the center widget for the #GtkActionBar. a #GtkActionBar a widget to use for the center The parent class. the action object a menu item connected to the action. the action object a toolbar item connected to the action. the action object the menu item provided by the action, or %NULL. a #GtkAction #GtkActionEntry structs are used with gtk_action_group_add_actions() to construct actions. The name of the action. The stock id for the action, or the name of an icon from the icon theme. The label for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). If @label is %NULL, the label of the stock item with id @stock_id is used. The accelerator for the action, in the format understood by gtk_accelerator_parse(). The tooltip for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The function to call when the action is activated. Actions are organised into groups. An action group is essentially a map from names to #GtkAction objects. All actions that would make sense to use in a particular context should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most nontrivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window’s menus would be constructed from a combination of two action groups. ## Accelerators ## {#Action-Accel} Accelerators are handled by the GTK+ accelerator map. All actions are assigned an accelerator path (which normally has the form `<Actions>/group-name/action-name`) and a shortcut is associated with this accelerator path. All menuitems and toolitems take on this accelerator path. The GTK+ accelerator map code makes sure that the correct shortcut is displayed next to the menu item. # GtkActionGroup as GtkBuildable # {#GtkActionGroup-BUILDER-UI} The #GtkActionGroup implementation of the #GtkBuildable interface accepts #GtkAction objects as <child> elements in UI definitions. Note that it is probably more common to define actions and action groups in the code, since they are directly related to what the code can do. The GtkActionGroup implementation of the GtkBuildable interface supports a custom <accelerator> element, which has attributes named “key“ and “modifiers“ and allows to specify accelerators. This is similar to the <accelerator> element of #GtkWidget, the main difference is that it doesn’t allow you to specify a signal. ## A #GtkDialog UI definition fragment. ## |[ <object class="GtkActionGroup" id="actiongroup"> <child> <object class="GtkAction" id="About"> <property name="name">About</property> <property name="stock_id">gtk-about</property> <signal handler="about_activate" name="activate"/> </object> <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/> </child> </object> ]| Creates a new #GtkActionGroup object. The name of the action group is used when associating [keybindings][Action-Accel] with the actions. the new #GtkActionGroup the name of the action group. Looks up an action in the action group by name. the action, or %NULL if no action by that name exists the action group the name of the action Adds an action object to the action group. Note that this function does not set up the accel path of the action, which can lead to problems if a user tries to modify the accelerator of a menuitem associated with the action. Therefore you must either set the accel path yourself with gtk_action_set_accel_path(), or use `gtk_action_group_add_action_with_accel (..., NULL)`. the action group an action Adds an action object to the action group and sets up the accelerator. If @accelerator is %NULL, attempts to use the accelerator associated with the stock_id of the action. Accel paths are set to `<Actions>/group-name/action-name`. the action group the action to add the accelerator for the action, in the format understood by gtk_accelerator_parse(), or "" for no accelerator, or %NULL to use the stock accelerator This is a convenience function to create a number of actions and add them to the action group. The “activate” signals of the actions are connected to the callbacks and their accel paths are set to `<Actions>/group-name/action-name`. the action group an array of action descriptions the number of entries data to pass to the action callbacks This variant of gtk_action_group_add_actions() adds a #GDestroyNotify callback for @user_data. the action group an array of action descriptions the number of entries data to pass to the action callbacks destroy notification callback for @user_data This is a convenience routine to create a group of radio actions and add them to the action group. The “changed” signal of the first radio action is connected to the @on_change callback and the accel paths of the actions are set to `<Actions>/group-name/action-name`. the action group an array of radio action descriptions the number of entries the value of the action to activate initially, or -1 if no action should be activated the callback to connect to the changed signal data to pass to the action callbacks This variant of gtk_action_group_add_radio_actions() adds a #GDestroyNotify callback for @user_data. the action group an array of radio action descriptions the number of entries the value of the action to activate initially, or -1 if no action should be activated the callback to connect to the changed signal data to pass to the action callbacks destroy notification callback for @user_data This is a convenience function to create a number of toggle actions and add them to the action group. The “activate” signals of the actions are connected to the callbacks and their accel paths are set to `<Actions>/group-name/action-name`. the action group an array of toggle action descriptions the number of entries data to pass to the action callbacks This variant of gtk_action_group_add_toggle_actions() adds a #GDestroyNotify callback for @user_data. the action group an array of toggle action descriptions the number of entries data to pass to the action callbacks destroy notification callback for @user_data Gets the accelerator group. the accelerator group associated with this action group or %NULL if there is none. a #GtkActionGroup Looks up an action in the action group by name. the action, or %NULL if no action by that name exists the action group the name of the action Gets the name of the action group. the name of the action group. the action group Returns %TRUE if the group is sensitive. The constituent actions can only be logically sensitive (see gtk_action_is_sensitive()) if they are sensitive (see gtk_action_get_sensitive()) and their group is sensitive. %TRUE if the group is sensitive. the action group Returns %TRUE if the group is visible. The constituent actions can only be logically visible (see gtk_action_is_visible()) if they are visible (see gtk_action_get_visible()) and their group is visible. %TRUE if the group is visible. the action group Lists the actions in the action group. an allocated list of the action objects in the action group the action group Removes an action object from the action group. the action group an action Sets the accelerator group to be used by every action in this group. a #GtkActionGroup a #GtkAccelGroup to set or %NULL Changes the sensitivity of @action_group the action group new sensitivity Sets a function to be used for translating the @label and @tooltip of #GtkActionEntrys added by gtk_action_group_add_actions(). If you’re using gettext(), it is enough to set the translation domain with gtk_action_group_set_translation_domain(). a #GtkActionGroup a #GtkTranslateFunc data to be passed to @func and @notify a #GDestroyNotify function to be called when @action_group is destroyed and when the translation function is changed again Sets the translation domain and uses g_dgettext() for translating the @label and @tooltip of #GtkActionEntrys added by gtk_action_group_add_actions(). If you’re not using gettext() for localization, see gtk_action_group_set_translate_func(). a #GtkActionGroup the translation domain to use for g_dgettext() calls, or %NULL to use the domain set with textdomain() Changes the visible of @action_group. the action group new visiblity Translates a string using the function set with gtk_action_group_set_translate_func(). This is mainly intended for language bindings. the translation of @string a #GtkActionGroup a string The accelerator group the actions of this group should use. A name for the action. Whether the action group is enabled. Whether the action group is visible. The ::connect-proxy signal is emitted after connecting a proxy to an action in the group. Note that the proxy may have been connected to a different action before. This is intended for simple customizations for which a custom action class would be too clumsy, e.g. showing tooltips for menuitems in the statusbar. #GtkUIManager proxies the signal and provides global notification just before any action is connected to a proxy, which is probably more convenient to use. the action the proxy The ::disconnect-proxy signal is emitted after disconnecting a proxy from an action in the group. #GtkUIManager proxies the signal and provides global notification just before any action is connected to a proxy, which is probably more convenient to use. the action the proxy The ::post-activate signal is emitted just after the @action in the @action_group is activated This is intended for #GtkUIManager to proxy the signal and provide global notification just after any action is activated. the action The ::pre-activate signal is emitted just before the @action in the @action_group is activated This is intended for #GtkUIManager to proxy the signal and provide global notification just before any action is activated. the action The parent class. the action, or %NULL if no action by that name exists the action group the name of the action This interface provides a convenient way of associating widgets with actions on a #GtkApplicationWindow or #GtkApplication. It primarily consists of two properties: #GtkActionable:action-name and #GtkActionable: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 #GtkApplicationWindow or #GtkApplication, but other action groups that are added with gtk_widget_insert_action_group() will be consulted as well. Gets the action name for @actionable. See gtk_actionable_set_action_name() for more information. the action name, or %NULL if none is set a #GtkActionable widget Gets the current target value of @actionable. See gtk_actionable_set_action_target_value() for more information. the current target value a #GtkActionable widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL 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 #GtkApplicationWindow. Names are of the form “win.save” or “app.quit” for actions on the containing #GtkApplicationWindow or its associated #GtkApplication, respectively. This is the same form used for actions in the #GMenu associated with the window. a #GtkActionable widget an action name, or %NULL Sets the target value of an actionable widget. If @target_value is %NULL 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 #GtkActionable 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 #GAction 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). a #GtkActionable widget a #GVariant to set as the target value, or %NULL Gets the action name for @actionable. See gtk_actionable_set_action_name() for more information. the action name, or %NULL if none is set a #GtkActionable widget Gets the current target value of @actionable. See gtk_actionable_set_action_target_value() for more information. the current target value a #GtkActionable widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL 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 #GtkApplicationWindow. Names are of the form “win.save” or “app.quit” for actions on the containing #GtkApplicationWindow or its associated #GtkApplication, respectively. This is the same form used for actions in the #GMenu associated with the window. a #GtkActionable widget an action name, or %NULL Sets the target of an actionable widget. This is a convenience function that calls g_variant_new() for @format_string and uses the result to call gtk_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 (). a #GtkActionable widget a GVariant format string arguments appropriate for @format_string Sets the target value of an actionable widget. If @target_value is %NULL 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 #GtkActionable 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 #GAction 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). a #GtkActionable widget a #GVariant to set as the target value, or %NULL Sets the action-name and associated string target value of an actionable widget. @detailed_action_name is a string in the format accepted by g_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.) a #GtkActionable widget the detailed action name The interface vtable for #GtkActionable. the action name, or %NULL if none is set a #GtkActionable widget a #GtkActionable widget an action name, or %NULL the current target value a #GtkActionable widget a #GtkActionable widget a #GVariant to set as the target value, or %NULL Activatable widgets can be connected to a #GtkAction and reflects the state of its action. A #GtkActivatable can also provide feedback through its action, as they are responsible for activating their related actions. # Implementing GtkActivatable When extending a class that is already #GtkActivatable; it is only necessary to implement the #GtkActivatable->sync_action_properties() and #GtkActivatable->update() methods and chain up to the parent implementation, however when introducing a new #GtkActivatable class; the #GtkActivatable:related-action and #GtkActivatable:use-action-appearance properties need to be handled by the implementor. Handling these properties is mostly a matter of installing the action pointer and boolean flag on your instance, and calling gtk_activatable_do_set_related_action() and gtk_activatable_sync_action_properties() at the appropriate times. ## A class fragment implementing #GtkActivatable |[<!-- language="C" --> enum { ... PROP_ACTIVATABLE_RELATED_ACTION, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE } struct _FooBarPrivate { ... GtkAction *action; gboolean use_action_appearance; }; ... static void foo_bar_activatable_interface_init (GtkActivatableIface *iface); static void foo_bar_activatable_update (GtkActivatable *activatable, GtkAction *action, const gchar *property_name); static void foo_bar_activatable_sync_action_properties (GtkActivatable *activatable, GtkAction *action); ... static void foo_bar_class_init (FooBarClass *klass) { ... g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_RELATED_ACTION, "related-action"); g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE, "use-action-appearance"); ... } static void foo_bar_activatable_interface_init (GtkActivatableIface *iface) { iface->update = foo_bar_activatable_update; iface->sync_action_properties = foo_bar_activatable_sync_action_properties; } ... Break the reference using gtk_activatable_do_set_related_action()... static void foo_bar_dispose (GObject *object) { FooBar *bar = FOO_BAR (object); FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); ... if (priv->action) { gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), NULL); priv->action = NULL; } G_OBJECT_CLASS (foo_bar_parent_class)->dispose (object); } ... Handle the “related-action” and “use-action-appearance” properties ... static void foo_bar_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec) { FooBar *bar = FOO_BAR (object); FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); switch (prop_id) { ... case PROP_ACTIVATABLE_RELATED_ACTION: foo_bar_set_related_action (bar, g_value_get_object (value)); break; case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE: foo_bar_set_use_action_appearance (bar, g_value_get_boolean (value)); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; } } static void foo_bar_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec) { FooBar *bar = FOO_BAR (object); FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); switch (prop_id) { ... case PROP_ACTIVATABLE_RELATED_ACTION: g_value_set_object (value, priv->action); break; case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE: g_value_set_boolean (value, priv->use_action_appearance); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; } } static void foo_bar_set_use_action_appearance (FooBar *bar, gboolean use_appearance) { FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); if (priv->use_action_appearance != use_appearance) { priv->use_action_appearance = use_appearance; gtk_activatable_sync_action_properties (GTK_ACTIVATABLE (bar), priv->action); } } ... call gtk_activatable_do_set_related_action() and then assign the action pointer, no need to reference the action here since gtk_activatable_do_set_related_action() already holds a reference here for you... static void foo_bar_set_related_action (FooBar *bar, GtkAction *action) { FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar); if (priv->action == action) return; gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), action); priv->action = action; } ... Selectively reset and update activatable depending on the use-action-appearance property ... static void gtk_button_activatable_sync_action_properties (GtkActivatable *activatable, GtkAction *action) { GtkButtonPrivate *priv = GTK_BUTTON_GET_PRIVATE (activatable); if (!action) return; if (gtk_action_is_visible (action)) gtk_widget_show (GTK_WIDGET (activatable)); else gtk_widget_hide (GTK_WIDGET (activatable)); gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action)); ... if (priv->use_action_appearance) { if (gtk_action_get_stock_id (action)) foo_bar_set_stock (button, gtk_action_get_stock_id (action)); else if (gtk_action_get_label (action)) foo_bar_set_label (button, gtk_action_get_label (action)); ... } } static void foo_bar_activatable_update (GtkActivatable *activatable, GtkAction *action, const gchar *property_name) { FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (activatable); if (strcmp (property_name, "visible") == 0) { if (gtk_action_is_visible (action)) gtk_widget_show (GTK_WIDGET (activatable)); else gtk_widget_hide (GTK_WIDGET (activatable)); } else if (strcmp (property_name, "sensitive") == 0) gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action)); ... if (!priv->use_action_appearance) return; if (strcmp (property_name, "stock-id") == 0) foo_bar_set_stock (button, gtk_action_get_stock_id (action)); else if (strcmp (property_name, "label") == 0) foo_bar_set_label (button, gtk_action_get_label (action)); ... } ]| This is called to update the activatable completely, this is called internally when the #GtkActivatable:related-action property is set or unset and by the implementing class when #GtkActivatable:use-action-appearance changes. a #GtkActivatable the related #GtkAction or %NULL This is a utility function for #GtkActivatable implementors. When implementing #GtkActivatable you must call this when handling changes of the #GtkActivatable:related-action, and you must also use this to break references in #GObject->dispose(). This function adds a reference to the currently set related action for you, it also makes sure the #GtkActivatable->update() method is called when the related #GtkAction properties change and registers to the action’s proxy list. > Be careful to call this before setting the local > copy of the #GtkAction property, since this function uses > gtk_activatable_get_related_action() to retrieve the > previous action. a #GtkActivatable the #GtkAction to set Gets the related #GtkAction for @activatable. the related #GtkAction if one is set. a #GtkActivatable Gets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance. whether @activatable uses its actions appearance. a #GtkActivatable Sets the related action on the @activatable object. > #GtkActivatable implementors need to handle the #GtkActivatable:related-action > property and call gtk_activatable_do_set_related_action() when it changes. a #GtkActivatable the #GtkAction to set Sets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance > #GtkActivatable implementors need to handle the > #GtkActivatable:use-action-appearance property and call > gtk_activatable_sync_action_properties() to update @activatable > if needed. a #GtkActivatable whether to use the actions appearance This is called to update the activatable completely, this is called internally when the #GtkActivatable:related-action property is set or unset and by the implementing class when #GtkActivatable:use-action-appearance changes. a #GtkActivatable the related #GtkAction or %NULL The action that this activatable will activate and receive updates from for various states and possibly appearance. > #GtkActivatable implementors need to handle the this property and > call gtk_activatable_do_set_related_action() when it changes. Whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance. See the #GtkAction documentation directly to find which properties should be ignored by the #GtkActivatable when this property is %FALSE. > #GtkActivatable implementors need to handle this property > and call gtk_activatable_sync_action_properties() on the activatable > widget when it changes. > This method can be called with a %NULL action at times. a #GtkActivatable the related #GtkAction or %NULL The #GtkAdjustment 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 #GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for #GtkScrollbar and #GtkScale). The #GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the #GtkAdjustment to control the value. Creates a new #GtkAdjustment. a new #GtkAdjustment the initial value the minimum value the maximum value the step increment the page increment the page size Emits a #GtkAdjustment::changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed any of the #GtkAdjustment properties other than the value. GTK+ emits #GtkAdjustment::changed itself whenever any of the properties (other than value) change a #GtkAdjustment Emits a #GtkAdjustment::value-changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed the #GtkAdjustment:value property. GTK+ emits #GtkAdjustment::value-changed itself whenever the value changes a #GtkAdjustment Emits a #GtkAdjustment::changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed any of the #GtkAdjustment properties other than the value. GTK+ emits #GtkAdjustment::changed itself whenever any of the properties (other than value) change a #GtkAdjustment Updates the #GtkAdjustment:value property to ensure that the range between @lower and @upper is in the current page (i.e. between #GtkAdjustment:value and #GtkAdjustment:value + #GtkAdjustment:page-size). If the range is larger than the page size, then only the start of it will be in the current page. A #GtkAdjustment::value-changed signal will be emitted if the value is changed. a #GtkAdjustment the lower value the upper value Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the #GtkAdjustment::changed signal. See gtk_adjustment_set_lower() for an alternative way of compressing multiple emissions of #GtkAdjustment::changed into one. a #GtkAdjustment the new value the new minimum value the new maximum value the new step increment the new page increment the new page size Retrieves the minimum value of the adjustment. The current minimum value of the adjustment a #GtkAdjustment Gets the smaller of step increment and page increment. the minimum increment of @adjustment a #GtkAdjustment Retrieves the page increment of the adjustment. The current page increment of the adjustment a #GtkAdjustment Retrieves the page size of the adjustment. The current page size of the adjustment a #GtkAdjustment Retrieves the step increment of the adjustment. The current step increment of the adjustment. a #GtkAdjustment Retrieves the maximum value of the adjustment. The current maximum value of the adjustment a #GtkAdjustment Gets the current value of the adjustment. See gtk_adjustment_set_value(). The current value of the adjustment a #GtkAdjustment Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual setters, multiple #GtkAdjustment::changed signals will be emitted. However, since the emission of the #GtkAdjustment::changed signal is tied to the emission of the #GObject::notify signals of the changed properties, it’s possible to compress the #GtkAdjustment::changed signals into one by calling g_object_freeze_notify() and g_object_thaw_notify() around the calls to the individual setters. Alternatively, using a single g_object_set() for all the properties to change, or using gtk_adjustment_configure() has the same effect of compressing #GtkAdjustment::changed emissions. a #GtkAdjustment the new minimum value Sets the page increment of the adjustment. See gtk_adjustment_set_lower() about how to compress multiple emissions of the #GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new page increment Sets the page size of the adjustment. See gtk_adjustment_set_lower() about how to compress multiple emissions of the GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new page size Sets the step increment of the adjustment. See gtk_adjustment_set_lower() about how to compress multiple emissions of the #GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new step increment 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 gtk_adjustment_set_lower() about how to compress multiple emissions of the #GtkAdjustment::changed signal when setting multiple adjustment properties. a #GtkAdjustment the new maximum value Sets the #GtkAdjustment value. The value is clamped to lie between #GtkAdjustment:lower and #GtkAdjustment:upper. Note that for adjustments which are used in a #GtkScrollbar, the effective range of allowed values goes from #GtkAdjustment:lower to #GtkAdjustment:upper - #GtkAdjustment:page-size. a #GtkAdjustment the new value Emits a #GtkAdjustment::value-changed signal from the #GtkAdjustment. This is typically called by the owner of the #GtkAdjustment after it has changed the #GtkAdjustment:value property. GTK+ emits #GtkAdjustment::value-changed itself whenever the value changes a #GtkAdjustment The minimum value of the adjustment. The page increment of the adjustment. 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 #GtkSpinButton. The step increment of the adjustment. The maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. The value of the adjustment. Emitted when one or more of the #GtkAdjustment properties have been changed, other than the #GtkAdjustment:value property. Emitted when the #GtkAdjustment:value property has been changed. a #GtkAdjustment a #GtkAdjustment 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 #GtkWidget:expand flag inside a #GtkBox, then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space. Note that in horizontal context @GTK_ALIGN_START and @GTK_ALIGN_END are interpreted relative to text direction. GTK_ALIGN_BASELINE support 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 @GTK_ALIGN_FILL. stretch to fill all space if possible, center if no meaningful way to stretch snap to left or top side, leaving space on right or bottom snap to right or bottom side, leaving space on left or top center natural width of widget inside the allocation align the widget according to the baseline. Since 3.10. The #GtkAlignment widget controls the alignment and size of its child widget. It has four settings: xscale, yscale, xalign, and yalign. The scale settings are used to specify how much the child widget should expand to fill the space allocated to the #GtkAlignment. The values can range from 0 (meaning the child doesn’t expand at all) to 1 (meaning the child expands to fill all of the available space). The align settings are used to place the child widget within the available area. The values range from 0 (top or left) to 1 (bottom or right). Of course, if the scale settings are both set to 1, the alignment settings have no effect. GtkAlignment has been deprecated in 3.14 and should not be used in newly-written code. The desired effect can be achieved by using the #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the child widget. Creates a new #GtkAlignment. Use #GtkWidget alignment and margin properties the new #GtkAlignment the horizontal alignment of the child widget, from 0 (left) to 1 (right). the vertical alignment of the child widget, from 0 (top) to 1 (bottom). the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the #GtkAlignment. the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to @xscale. Gets the padding on the different sides of the widget. See gtk_alignment_set_padding (). Use #GtkWidget alignment and margin properties a #GtkAlignment location to store the padding for the top of the widget, or %NULL location to store the padding for the bottom of the widget, or %NULL location to store the padding for the left of the widget, or %NULL location to store the padding for the right of the widget, or %NULL Sets the #GtkAlignment values. Use #GtkWidget alignment and margin properties a #GtkAlignment. the horizontal alignment of the child widget, from 0 (left) to 1 (right). the vertical alignment of the child widget, from 0 (top) to 1 (bottom). the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the #GtkAlignment. the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to @xscale. Sets the padding on the different sides of the widget. The padding adds blank space to the sides of the widget. For instance, this can be used to indent the child widget towards the right by adding padding on the left. Use #GtkWidget alignment and margin properties a #GtkAlignment the padding at the top of the widget the padding at the bottom of the widget the padding at the left of the widget the padding at the right of the widget. The padding to insert at the bottom of the widget. Use gtk_widget_set_margin_bottom() instead The padding to insert at the left of the widget. Use gtk_widget_set_margin_start() instead The padding to insert at the right of the widget. Use gtk_widget_set_margin_end() instead The padding to insert at the top of the widget. Use gtk_widget_set_margin_top() instead Horizontal position of child in available space. A value of 0.0 will flush the child left (or right, in RTL locales); a value of 1.0 will flush the child right (or left, in RTL locales). Use gtk_widget_set_halign() on the child instead If available horizontal space is bigger than needed, how much of it to use for the child. A value of 0.0 means none; a value of 1.0 means all. Use gtk_widget_set_hexpand() on the child instead Vertical position of child in available space. A value of 0.0 will flush the child to the top; a value of 1.0 will flush the child to the bottom. Use gtk_widget_set_valign() on the child instead If available vertical space is bigger than needed, how much of it to use for the child. A value of 0.0 means none; a value of 1.0 means all. Use gtk_widget_set_vexpand() on the child instead The parent class. #GtkAppChooser 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 #GtkAppChooserWidget, #GtkAppChooserDialog and #GtkAppChooserButton. Applications are represented by GIO #GAppInfo 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 #GtkAppChooserWidget 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 #GtkAppChooser, use gtk_app_chooser_get_app_info(). Returns the currently selected application. a #GAppInfo for the currently selected application, or %NULL if none is selected. Free with g_object_unref() a #GtkAppChooser Returns the current value of the #GtkAppChooser:content-type property. the content type of @self. Free with g_free() a #GtkAppChooser Reloads the list of applications. a #GtkAppChooser The content type of the #GtkAppChooser object. See [GContentType][gio-GContentType] for more information about content types. The #GtkAppChooserButton is a widget that lets the user select an application. It implements the #GtkAppChooser interface. Initially, a #GtkAppChooserButton selects the first application in its list, which will either be the most-recently used application or, if #GtkAppChooserButton:show-default-item is %TRUE, the default application. The list of applications shown in a #GtkAppChooserButton includes the recommended applications for the given content type. When #GtkAppChooserButton:show-default-item is set, the default application is also included. To let the user chooser other applications, you can set the #GtkAppChooserButton:show-dialog-item property, which allows to open a full #GtkAppChooserDialog. It is possible to add custom items to the list, using gtk_app_chooser_button_append_custom_item(). These items cause the #GtkAppChooserButton::custom-item-activated signal to be emitted when they are selected. To track changes in the selected application, use the #GtkComboBox::changed signal. Creates a new #GtkAppChooserButton for applications that can handle content of the given type. a newly created #GtkAppChooserButton the content type to show applications for 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 #GtkAppChooserButton::custom-item-activated signal, to add a callback for the activation of a particular custom item in the list. See also gtk_app_chooser_button_append_separator(). a #GtkAppChooserButton the name of the custom item the label for the custom item the icon for the custom item Appends a separator to the list of applications that is shown in the popup. a #GtkAppChooserButton Returns the text to display at the top of the dialog. the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a #GtkAppChooserButton Returns the current value of the #GtkAppChooserButton:show-default-item property. the value of #GtkAppChooserButton:show-default-item a #GtkAppChooserButton Returns the current value of the #GtkAppChooserButton:show-dialog-item property. the value of #GtkAppChooserButton:show-dialog-item a #GtkAppChooserButton Selects a custom item previously added with gtk_app_chooser_button_append_custom_item(). Use gtk_app_chooser_refresh() to bring the selection to its initial state. a #GtkAppChooserButton the name of the custom item Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. a #GtkAppChooserButton a string containing Pango markup Sets whether the dropdown menu of this button should show the default application for the given content type at top. a #GtkAppChooserButton the new value for #GtkAppChooserButton:show-default-item Sets whether the dropdown menu of this button should show an entry to trigger a #GtkAppChooserDialog. a #GtkAppChooserButton the new value for #GtkAppChooserButton:show-dialog-item The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. The #GtkAppChooserButton:show-default-item property determines whether the dropdown menu should show the default application on top for the provided content type. The #GtkAppChooserButton:show-dialog-item property determines whether the dropdown menu should show an item that triggers a #GtkAppChooserDialog when clicked. Emitted when a custom item, previously added with gtk_app_chooser_button_append_custom_item(), is activated from the dropdown menu. the name of the activated item The parent class. #GtkAppChooserDialog shows a #GtkAppChooserWidget inside a #GtkDialog. Note that #GtkAppChooserDialog does not have any interesting methods of its own. Instead, you should get the embedded #GtkAppChooserWidget using gtk_app_chooser_dialog_get_widget() and call its methods if the generic #GtkAppChooser interface is not sufficient for your needs. To set the heading that is shown above the #GtkAppChooserWidget, use gtk_app_chooser_dialog_set_heading(). Creates a new #GtkAppChooserDialog for the provided #GFile, to allow the user to select an application for it. a newly created #GtkAppChooserDialog a #GtkWindow, or %NULL flags for this dialog a #GFile Creates a new #GtkAppChooserDialog for the provided content type, to allow the user to select an application for it. a newly created #GtkAppChooserDialog a #GtkWindow, or %NULL flags for this dialog a content type string Returns the text to display at the top of the dialog. the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a #GtkAppChooserDialog Returns the #GtkAppChooserWidget of this dialog. the #GtkAppChooserWidget of @self a #GtkAppChooserDialog Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. a #GtkAppChooserDialog a string containing Pango markup The GFile used by the #GtkAppChooserDialog. The dialog's #GtkAppChooserWidget content type will be guessed from the file, if present. The text to show at the top of the dialog. The string may contain Pango markup. The parent class. #GtkAppChooserWidget is a widget for selecting applications. It is the main building block for #GtkAppChooserDialog. 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. #GtkAppChooserWidget offers detailed control over what applications are shown, using the #GtkAppChooserWidget:show-default, #GtkAppChooserWidget:show-recommended, #GtkAppChooserWidget:show-fallback, #GtkAppChooserWidget:show-other and #GtkAppChooserWidget:show-all properties. See the #GtkAppChooser documentation for more information about these groups of applications. To keep track of the selected application, use the #GtkAppChooserWidget::application-selected and #GtkAppChooserWidget::application-activated signals. # CSS nodes GtkAppChooserWidget has a single CSS node with name appchooser. Creates a new #GtkAppChooserWidget for applications that can handle content of the given type. a newly created #GtkAppChooserWidget the content type to show applications for Returns the text that is shown if there are not applications that can handle the content type. the value of #GtkAppChooserWidget:default-text a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-all property. the value of #GtkAppChooserWidget:show-all a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-default property. the value of #GtkAppChooserWidget:show-default a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-fallback property. the value of #GtkAppChooserWidget:show-fallback a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-other property. the value of #GtkAppChooserWidget:show-other a #GtkAppChooserWidget Returns the current value of the #GtkAppChooserWidget:show-recommended property. the value of #GtkAppChooserWidget:show-recommended a #GtkAppChooserWidget Sets the text that is shown if there are not applications that can handle the content type. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:default-text Sets whether the app chooser should show all applications in a flat list. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-all Sets whether the app chooser should show the default handler for the content type in a separate section. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-default Sets whether the app chooser should show related applications for the content type in a separate section. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-fallback Sets whether the app chooser should show applications which are unrelated to the content type. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-other Sets whether the app chooser should show recommended applications for the content type in a separate section. a #GtkAppChooserWidget the new value for #GtkAppChooserWidget:show-recommended The #GtkAppChooserWidget:default-text property determines the text that appears in the widget when there are no applications for the given content type. See also gtk_app_chooser_widget_set_default_text(). If the #GtkAppChooserWidget:show-all property is %TRUE, the app chooser presents all applications in a single list, without subsections for default, recommended or related applications. 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. The #GtkAppChooserWidget: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. The #GtkAppChooserWidget:show-other property determines whether the app chooser should show a section for other applications. The #GtkAppChooserWidget: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. 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. the activated #GAppInfo Emitted when an application item is selected from the widget's list. the selected #GAppInfo Emitted when a context menu is about to popup over an application item. Clients can insert menu items into the provided #GtkMenu 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. the #GtkMenu to populate the current #GAppInfo The parent class. #GtkApplication 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, GtkApplication 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 GtkApplication works fine with plain #GtkWindows, it is recommended to use it together with #GtkApplicationWindow. When GDK threads are enabled, GtkApplication 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 g_action_group_activate_action(). The same applies to actions associated with #GtkApplicationWindow and to the “activate” and “open” #GApplication methods. ## Automatic resources ## {#automatic-resources} #GtkApplication will automatically load menus from the #GtkBuilder resource located at "gtk/menus.ui", relative to the application's resource base path (see g_application_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 gtk_application_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 gtk_application_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 gtk_application_set_app_menu() and gtk_application_set_menubar(). #GtkApplication 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 gtk_icon_theme_add_resource_path() for more information. If there is a resource located at "gtk/help-overlay.ui" which defines a #GtkShortcutsWindow with ID "help_overlay" then GtkApplication associates an instance of this shortcuts window with each #GtkApplicationWindow 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) GtkApplication optionally registers with a session manager of the users session (if you set the #GtkApplication: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 gtk_application_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 GtkApplication](https://wiki.gnome.org/HowDoI/GtkApplication), [Getting Started with GTK+: Basics](https://developer.gnome.org/gtk3/stable/gtk-getting-started.html#id-1.2.3.3) Creates a new #GtkApplication instance. When using #GtkApplication, 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 #GApplication::startup signal. Therefore, #GtkApplication subclasses should chain up in their #GApplication::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-%NULL, the application ID must be valid. See g_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. a new #GtkApplication instance The application ID. the application flags Installs an accelerator that will cause the named action to be activated when the key combination specificed by @accelerator is pressed. @accelerator must be a string that can be parsed by gtk_accelerator_parse(), e.g. "<Primary>q" or “<Control><Alt>p”. @action_name must be the name of an action as it would be used in the app menu, i.e. actions that have been added to the application are referred to with an “app.” prefix, and window-specific actions with a “win.” prefix. GtkApplication also extracts accelerators out of “accel” attributes in the #GMenuModels passed to gtk_application_set_app_menu() and gtk_application_set_menubar(), which is usually more convenient than calling this function for each accelerator. Use gtk_application_set_accels_for_action() instead a #GtkApplication accelerator string the name of the action to activate parameter to pass when activating the action, or %NULL if the action does not accept an activation parameter Adds a window to @application. This call can only happen after the @application has started; typically, you should add new application windows in response to the emission of the #GApplication::activate signal. This call is equivalent to setting the #GtkWindow:application property of @window to @application. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with gtk_application_remove_window(). GTK+ will keep the @application running as long as it has any windows. a #GtkApplication a #GtkWindow Gets the accelerators that are currently associated with the given action. accelerators for @detailed_action_name, as a %NULL-terminated array. Free with g_strfreev() when no longer needed a #GtkApplication a detailed action name, specifying an action and target to obtain accelerators for 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. %NULL 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. a %NULL-terminated array of actions for @accel a #GtkApplication an accelerator that can be parsed by gtk_accelerator_parse() 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. the active window, or %NULL if there isn't one. a #GtkApplication Returns the menu model that has been set with gtk_application_set_app_menu(). the application menu of @application or %NULL if no application menu has been set. a #GtkApplication Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information. Gets the menu with the given id from the automatically loaded resources a #GtkApplication the id of the menu to look up Returns the menu model that has been set with gtk_application_set_menubar(). the menubar for windows of @application a #GtkApplication Returns the #GtkApplicationWindow with the given ID. The ID of a #GtkApplicationWindow can be retrieved with gtk_application_window_get_id(). the window with ID @id, or %NULL if there is no window with this ID a #GtkApplication an identifier number Gets a list of the #GtkWindows associated with @application. 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. a #GList of #GtkWindow a #GtkApplication 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 gtk_application_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. A non-zero cookie that is used to uniquely identify this request. It should be used as an argument to gtk_application_uninhibit() in order to remove the request. If the platform does not support inhibiting or the request failed for some reason, 0 is returned. the #GtkApplication a #GtkWindow, or %NULL what types of actions should be inhibited a short, human-readable string that explains why these operations are 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). %TRUE if any of the actions specified in @flags are inhibited the #GtkApplication what types of actions should be queried Lists the detailed action names which have associated accelerators. See gtk_application_set_accels_for_action(). a %NULL-terminated array of strings, free with g_strfreev() when done a #GtkApplication 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 gtk_application_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 gtk_application_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 gtk_application_set_app_menu() anyway, then this menu will be replaced with your own. %TRUE if you should set an app menu a #GtkApplication Removes an accelerator that has been previously added with gtk_application_add_accelerator(). Use gtk_application_set_accels_for_action() instead a #GtkApplication the name of the action to activate parameter to pass when activating the action, or %NULL if the action does not accept an activation parameter Remove a window from @application. If @window belongs to @application then this call is equivalent to setting the #GtkWindow:application property of @window to %NULL. The application may stop running as a result of a call to this function. a #GtkApplication a #GtkWindow 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 g_action_parse_detailed_name() and g_action_print_detailed_name(). a #GtkApplication a detailed action name, specifying an action and target to associate accelerators with a list of accelerators in the format understood by gtk_accelerator_parse() Sets or unsets the application menu for @application. This can only be done in the primary instance of the application, after it has been registered. #GApplication::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 #GActionMap interface to add actions, to respond to the user selecting these menu items. a #GtkApplication a #GMenuModel, or %NULL Sets or unsets the menubar for windows of @application. 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. #GApplication::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 #GActionMap interface to add actions, to respond to the user selecting these menu items. a #GtkApplication a #GMenuModel, or %NULL Removes an inhibitor that has been established with gtk_application_inhibit(). Inhibitors are also cleared when the application exits. the #GtkApplication a cookie that was returned by gtk_application_inhibit() Set this property to %TRUE to register with the session manager. This property is %TRUE if GTK+ believes that the screensaver is currently active. GTK+ only tracks session state (including this) when #GtkApplication::register-session is set to %TRUE. Tracking the screensaver state is supported on Linux. Emitted when the session manager is about to end the session, only if #GtkApplication::register-session is %TRUE. Applications can connect to this signal and call gtk_application_inhibit() with %GTK_APPLICATION_INHIBIT_LOGOUT to delay the end of the session until state has been saved. Emitted when a #GtkWindow is added to @application through gtk_application_add_window(). the newly-added #GtkWindow Emitted when a #GtkWindow is removed from @application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). the #GtkWindow that is being removed The parent class. Types of user actions that may be blocked by gtk_application_inhibit(). Inhibit ending the user session by logging out or by shutting down the computer Inhibit user switching Inhibit suspending the session or computer Inhibit the session being marked as idle (and possibly locked) #GtkApplicationWindow is a #GtkWindow subclass that offers some extra functionality for better integration with #GtkApplication features. Notably, it can handle both the application menu as well as the menubar. See gtk_application_set_app_menu() and gtk_application_set_menubar(). This class implements the #GActionGroup and #GActionMap interfaces, to let you add window-specific actions that will be exported by the associated #GtkApplication, 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 #GMenuModel. Note that widgets that are placed inside a #GtkApplicationWindow can also activate these actions, if they implement the #GtkActionable interface. As with #GtkApplication, 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 #GtkSettings:gtk-shell-shows-app-menu and #GtkSettings: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 #GtkApplicationWindow will automatically show a #GtkMenuBar for it. This behaviour can be overridden with the #GtkApplicationWindow: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 GtkApplicationWindow with a menubar |[<!-- language="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 #GtkBuilder for #GMenuModel 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 #GtkBuilder 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 #GtkBuilder 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 #GtkTextDirection 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 Creates a new #GtkApplicationWindow. a newly created #GtkApplicationWindow a #GtkApplication Gets the #GtkShortcutsWindow that has been set up with a prior call to gtk_application_window_set_help_overlay(). the help overlay associated with @window, or %NULL a #GtkApplicationWindow Returns the unique ID of the window. If the window has not yet been added to a #GtkApplication, returns `0`. the unique ID for @window, or `0` if the window has not yet been added to a #GtkApplication a #GtkApplicationWindow Returns whether the window will display a menubar for the app menu and menubar as needed. %TRUE if @window will display a menubar when needed a #GtkApplicationWindow Associates a shortcuts window with the application window, and sets up an action with the name win.show-help-overlay to present it. @window takes resposibility for destroying @help_overlay. a #GtkApplicationWindow a #GtkShortcutsWindow Sets whether the window will display a menubar for the app menu and menubar as needed. a #GtkApplicationWindow whether to show a menubar when needed 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 gtk_application_set_app_menu() and gtk_application_set_menubar(). If %FALSE, the window will not display a menubar, regardless of whether the desktop shell is showing the menus or not. The parent class. GtkArrow should be used to draw simple arrows that need to point in one of the four cardinal directions (up, down, left, or right). The style of the arrow can be one of shadow in, shadow out, etched in, or etched out. Note that these directions and style types may be amended in versions of GTK+ to come. GtkArrow will fill any space alloted to it, but since it is inherited from #GtkMisc, it can be padded and/or aligned, to fill exactly the space the programmer desires. Arrows are created with a call to gtk_arrow_new(). The direction or style of an arrow can be changed after creation by using gtk_arrow_set(). GtkArrow has been deprecated; you can simply use a #GtkImage with a suitable icon name, such as “pan-down-symbolic“. When replacing GtkArrow by an image, pay attention to the fact that GtkArrow is doing automatic flipping between #GTK_ARROW_LEFT and #GTK_ARROW_RIGHT, depending on the text direction. To get the same effect with an image, use the icon names “pan-start-symbolic“ and “pan-end-symbolic“, which react to the text direction. Creates a new #GtkArrow widget. Use a #GtkImage with a suitable icon. the new #GtkArrow widget. a valid #GtkArrowType. a valid #GtkShadowType. Sets the direction and style of the #GtkArrow, @arrow. Use a #GtkImage with a suitable icon. a widget of type #GtkArrow. a valid #GtkArrowType. a valid #GtkShadowType. Used to specify the placement of scroll arrows in scrolling menus. Place one arrow on each end of the menu. Place both arrows at the top of the menu. Place both arrows at the bottom of the menu. Used to indicate the direction in which an arrow should point. Represents an upward pointing arrow. Represents a downward pointing arrow. Represents a left pointing arrow. Represents a right pointing arrow. No arrow. Since 2.10. The #GtkAspectFrame 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. #GtkAspectFrame derives from #GtkFrame, 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 GtkAspectFrame uses a CSS node with name frame. Create a new #GtkAspectFrame. the new #GtkAspectFrame. Label text. Horizontal alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. Set parameters for an existing #GtkAspectFrame. a #GtkAspectFrame Horizontal alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the allocation of the #GtkAspectFrame. This ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. The parent class. A #GtkAssistant 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 GtkAssistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the [type][GtkAssistantPageType] 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 #GTK_ASSISTANT_PAGE_CUSTOM page type and handle buttons yourself. # GtkAssistant as GtkBuildable The GtkAssistant implementation of the #GtkBuildable interface exposes the @action_area as internal children with the name “action_area”. To add pages to an assistant in #GtkBuilder, simply add it as a child to the GtkAssistant object, and set its child properties as necessary. # CSS nodes GtkAssistant has a single CSS node with the name assistant. Creates a new #GtkAssistant. a newly created #GtkAssistant Adds a widget to the action area of a #GtkAssistant. a #GtkAssistant a #GtkWidget Appends a page to the @assistant. the index (starting at 0) of the inserted page a #GtkAssistant a #GtkWidget 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. a #GtkAssistant Returns the page number of the current page. The index (starting from 0) of the current page in the @assistant, or -1 if the @assistant has no pages, or no current page. a #GtkAssistant Returns the number of pages in the @assistant the number of pages in the @assistant a #GtkAssistant Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num is out of bounds a #GtkAssistant the index of a page in the @assistant, or -1 to get the last page Gets whether @page is complete. %TRUE if @page is complete. a #GtkAssistant a page of @assistant Gets whether page has padding. %TRUE if @page has padding a #GtkAssistant a page of @assistant Gets the header image for @page. Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead. the header image for @page, or %NULL if there’s no header image for the page a #GtkAssistant a page of @assistant Gets the side image for @page. Since GTK+ 3.2, sidebar images are not shown anymore. the side image for @page, or %NULL if there’s no side image for the page a #GtkAssistant a page of @assistant Gets the title for @page. the title for @page a #GtkAssistant a page of @assistant Gets the page type of @page. the page type of @page a #GtkAssistant a page of @assistant Inserts a page in the @assistant at a given position. the index (starting from 0) of the inserted page a #GtkAssistant a #GtkWidget the index (starting at 0) at which to insert the page, or -1 to append the page to the @assistant 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 #GTK_ASSISTANT_PAGE_CUSTOM type. a #GtkAssistant Prepends a page to the @assistant. the index (starting at 0) of the inserted page a #GtkAssistant a #GtkWidget 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 #GTK_ASSISTANT_PAGE_CUSTOM type. a #GtkAssistant Removes a widget from the action area of a #GtkAssistant. a #GtkAssistant a #GtkWidget Removes the @page_num’s page from @assistant. a #GtkAssistant the index of a page in the @assistant, or -1 to remove the last page Switches the page to @page_num. Note that this will only be necessary in custom buttons, as the @assistant flow can be set with gtk_assistant_set_forward_page_func(). a #GtkAssistant 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 @assistant, nothing will be done. 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 %NULL will make the assistant to use the default forward function, which just goes to the next visible page. a #GtkAssistant the #GtkAssistantPageFunc, or %NULL to use the default one user data for @page_func destroy notifier for @data Sets whether @page contents are complete. This will make @assistant update the buttons state to be able to continue the task. a #GtkAssistant a page of @assistant the completeness status of the page Sets whether the assistant is adding padding around the page. a #GtkAssistant a page of @assistant whether this page has padding Sets a header image for @page. Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead. a #GtkAssistant a page of @assistant the new header image @page Sets a side image for @page. This image used to be displayed in the side area of the assistant when @page is the current page. Since GTK+ 3.2, sidebar images are not shown anymore. a #GtkAssistant a page of @assistant the new side image @page Sets a title for @page. The title is displayed in the header area of the assistant when @page is the current page. a #GtkAssistant a page of @assistant the new title for @page Sets the page type for @page. The page type determines the page behavior in the @assistant. a #GtkAssistant a page of @assistant the new type for @page Forces @assistant 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. a #GtkAssistant %TRUE if the assistant uses a #GtkHeaderBar 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. The ::apply signal is emitted when the apply button is clicked. The default behavior of the #GtkAssistant 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 %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this operation within the #GtkAssistant::prepare signal of the progress page. The ::cancel signal is emitted when then the cancel button is clicked. 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 %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. 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. the current page The parent class. A function used by gtk_assistant_set_forward_page_func() to know which is the next page given a current one. It’s called both for computing the next page when the user presses the “forward” button and for handling the behavior of the “last” button. The next page number. The page number used to calculate the next page. user data. An enum for determining the page role inside the #GtkAssistant. It's used to handle buttons sensitivity and visibility. Note that an assistant needs to end its page flow with a page of type %GTK_ASSISTANT_PAGE_CONFIRM, %GTK_ASSISTANT_PAGE_SUMMARY or %GTK_ASSISTANT_PAGE_PROGRESS to be correct. The Cancel button will only be shown if the page isn’t “committed”. See gtk_assistant_commit() for details. The page has regular contents. Both the Back and forward buttons will be shown. The page contains an introduction to the assistant task. Only the Forward button will be shown if there is a next page. The page lets the user confirm or deny the changes. The Back and Apply buttons will be shown. The page informs the user of the changes done. Only the Close button will be shown. 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. Used for when other page types are not appropriate. No buttons will be shown, and the application must add its own buttons through gtk_assistant_add_action_widget(). Denotes the expansion properties that a widget will have when it (or its parent) is resized. the widget should expand to take up any extra space in its container that has been allocated. the widget should shrink as and when possible. the widget should fill the space allocated to it. Like gtk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. This macro should be used to emit a warning about and unexpected @type value in a #GtkBuildable add_child implementation. the #GtkBuildable on which the warning ocurred the unexpected type value 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 #GtkBaselinePosition to select where to put the baseline inside the extra availible space. Align the baseline at the top Center the baseline Align the baseline at the bottom The #GtkBin 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 #GtkBin, including #GtkWindow, #GtkButton, #GtkFrame, #GtkHandleBox or #GtkScrolledWindow. Gets the child of the #GtkBin, or %NULL if the bin contains no child widget. The returned widget does not have a reference added, so you do not need to unref it. the child of @bin, or %NULL if it does not have a child. a #GtkBin The parent class. A #GtkBindingArg holds the data associated with an argument for a key binding signal emission as stored in #GtkBindingSignal. implementation detail Each key binding element of a binding sets binding list is represented by a GtkBindingEntry. key value to match key modifiers to match binding set this entry belongs to implementation detail implementation detail implementation detail linked list of entries maintained by binding set implementation detail action signals of this entry Override or install a new key binding for @keyval with @modifiers on @binding_set. When the binding is activated, @signal_name will be emitted on the target widget, with @n_args @Varargs used as arguments. Each argument to the signal must be passed as a pair of varargs: the #GType of the argument, followed by the argument value (which must be of the given type). There must be @n_args pairs in total. ## Adding a Key Binding |[<!-- language="C" --> GtkBindingSet *binding_set; GdkModifierType modmask = GDK_CONTROL_MASK; int count = 1; gtk_binding_entry_add_signal (binding_set, GDK_KEY_space, modmask, "move-cursor", 2, GTK_TYPE_MOVEMENT_STEP, GTK_MOVEMENT_PAGES, G_TYPE_INT, count, G_TYPE_BOOLEAN, FALSE); ]| a #GtkBindingSet to install an entry for key value of binding to install key modifier of binding to install signal to execute upon activation number of arguments to @signal_name arguments to @signal_name Parses a signal description from @signal_desc and incorporates it into @binding_set. Signal descriptions may either bind a key combination to one or more signals: |[ bind "key" { "signalname" (param, ...) ... } ]| Or they may also unbind a key combination: |[ unbind "key" ]| Key combinations must be in a format that can be parsed by gtk_accelerator_parse(). %G_TOKEN_NONE if the signal was successfully parsed and added, the expected token otherwise a #GtkBindingSet a signal description Override or install a new key binding for @keyval with @modifiers on @binding_set. a #GtkBindingSet to add a signal to key value key modifier signal name to be bound list of #GtkBindingArg signal arguments Remove a binding previously installed via gtk_binding_entry_add_signal() on @binding_set. a #GtkBindingSet to remove an entry of key value of binding to remove key modifier of binding to remove Install a binding on @binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated. a #GtkBindingSet to skip an entry of key value of binding to skip key modifier of binding to skip A binding set maintains a list of activatable key bindings. A single binding set can match multiple types of widgets. Similar to style contexts, can be matched by any information contained in a widgets #GtkWidgetPath. When a binding within a set is matched upon activation, an action signal is emitted on the target widget to carry out the actual activation. unique name of this binding set unused unused unused unused the key binding entries in this binding set implementation detail whether this binding set stems from a CSS file and is reset upon theme changes Find a key binding matching @keyval and @modifiers within @binding_set and activate the binding on @object. %TRUE if a binding was found and activated a #GtkBindingSet set to activate key value of the binding key modifier of the binding object to activate when binding found This function was used internally by the GtkRC parsing mechanism to assign match patterns to #GtkBindingSet structures. In GTK+ 3, these match patterns are unused. a #GtkBindingSet to add a path to path type the pattern applies to the actual match pattern binding priority This function returns the binding set named after the type name of the passed in class structure. New binding sets are created on demand by this function. the binding set corresponding to @object_class a valid #GObject class Find a binding set by its globally unique name. The @set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class(). %NULL or the specified binding set unique binding set name GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation. new binding set unique name of this binding set A GtkBindingSignal stores the necessary information to activate a widget in response to a key press via a signal emission. implementation detail the action signal to be emitted number of arguments specified for the signal the arguments specified for the signal A struct that specifies a border around a rectangular area that can be of different width on each side. The width of the left border The width of the right border The width of the top border The width of the bottom border Allocates a new #GtkBorder-struct and initializes its elements to zero. a newly allocated #GtkBorder-struct. Free with gtk_border_free() Copies a #GtkBorder-struct. a copy of @border_. a #GtkBorder-struct Frees a #GtkBorder-struct. a #GtkBorder-struct Describes how the border of a UI element should be rendered. No visible border A single line segment Looks as if the content is sunken into the canvas Looks as if the content is coming out of the canvas Same as @GTK_BORDER_STYLE_NONE A series of round dots A series of square-ended dashes Two parallel lines with some space between them Looks as if it were carved in the canvas Looks as if it were coming out of the canvas The GtkBox widget arranges child widgets into a single row or column, depending upon the value of its #GtkOrientable:orientation property. Within the other dimension, all children are allocated the same size. Of course, the #GtkWidget:halign and #GtkWidget:valign properties can be used on the children to influence their allocation. GtkBox uses a notion of packing. Packing refers to adding widgets with reference to a particular position in a #GtkContainer. For a GtkBox, there are two reference positions: the start and the end of the box. For a vertical #GtkBox, the start is defined as the top of the box and the end is defined as the bottom. For a horizontal #GtkBox the start is defined as the left side and the end is defined as the right side. Use repeated calls to gtk_box_pack_start() to pack widgets into a GtkBox from start to end. Use gtk_box_pack_end() to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same GtkBox. Because GtkBox is a #GtkContainer, you may also use gtk_container_add() to insert widgets into the box, and they will be packed with the default values for expand and fill child properties. Use gtk_container_remove() to remove widgets from the GtkBox. Use gtk_box_set_homogeneous() to specify whether or not all children of the GtkBox are forced to get the same amount of space. Use gtk_box_set_spacing() to determine how much space will be minimally placed between all children in the GtkBox. Note that spacing is added between the children, while padding added by gtk_box_pack_start() or gtk_box_pack_end() is added on either side of the widget it belongs to. Use gtk_box_reorder_child() to move a GtkBox child to a different place in the box. Use gtk_box_set_child_packing() to reset the expand, fill and padding child properties. Use gtk_box_query_child_packing() to query these fields. # CSS nodes GtkBox 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. Creates a new #GtkBox. a new #GtkBox. the box’s orientation. the number of pixels to place by default between children. Gets the value set by gtk_box_set_baseline_position(). the baseline position a #GtkBox Retrieves the center widget of the box. the center widget or %NULL in case no center widget is set. a #GtkBox Returns whether the box is homogeneous (all children are the same size). See gtk_box_set_homogeneous(). %TRUE if the box is homogeneous. a #GtkBox Gets the value set by gtk_box_set_spacing(). spacing between children a #GtkBox Adds @child to @box, packed with reference to the end of @box. The @child is packed after (away from end of) any other child packed with reference to the end of @box. a #GtkBox the #GtkWidget to be added to @box %TRUE if the new child is to be given extra space allocated to @box. The extra space will be divided evenly between all children of @box that use this option %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 #GtkBox and the full width of a vertical #GtkBox. This option affects the other dimension extra space in pixels to put between this child and its neighbors, over and above the global amount specified by #GtkBox:spacing property. If @child is a widget at one of the reference ends of @box, then @padding pixels are also put between @child and the reference edge of @box Adds @child to @box, packed with reference to the start of @box. The @child is packed after any other child packed with reference to the start of @box. a #GtkBox the #GtkWidget to be added to @box %TRUE if the new child is to be given extra space allocated to @box. The extra space will be divided evenly between all children that use this option %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 #GtkBox and the full width of a vertical #GtkBox. This option affects the other dimension extra space in pixels to put between this child and its neighbors, over and above the global amount specified by #GtkBox:spacing property. If @child is a widget at one of the reference ends of @box, then @padding pixels are also put between @child and the reference edge of @box Obtains information about how @child is packed into @box. a #GtkBox the #GtkWidget of the child to query pointer to return location for expand child property pointer to return location for fill child property pointer to return location for padding child property pointer to return location for pack-type child property Moves @child to a new @position in the list of @box children. The list contains widgets packed #GTK_PACK_START as well as widgets packed #GTK_PACK_END, in the order that these widgets were added to @box. A widget’s position in the @box children list determines where the widget is packed into @box. 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. a #GtkBox the #GtkWidget to move the new position for @child in the list of children of @box, starting from 0. If negative, indicates the end of the list 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. a #GtkBox a #GtkBaselinePosition 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. a #GtkBox the widget to center Sets the way @child is packed into @box. a #GtkBox the #GtkWidget of the child to set the new value of the expand child property the new value of the fill child property the new value of the padding child property the new value of the pack-type child property Sets the #GtkBox:homogeneous property of @box, controlling whether or not all children of @box are given equal space in the box. a #GtkBox a boolean value, %TRUE to create equal allotments, %FALSE for variable allotments Sets the #GtkBox:spacing property of @box, which is the number of pixels to place between children of @box. a #GtkBox the number of pixels to put between children The parent class. GtkBuildable allows objects to extend and customize their deserialization from [GtkBuilder UI descriptions][BUILDER-UI]. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects. The GtkBuildable 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 #GtkBuilder. 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 #GtkBuilder format or run any extra routines at deserialization time. Adds a child to @buildable. @type is an optional string describing how the child should be added. a #GtkBuildable a #GtkBuilder child to add kind of child or %NULL Constructs a child of @buildable with the name @name. #GtkBuilder calls this function if a “constructor” has been specified in the UI definition. the constructed child A #GtkBuildable #GtkBuilder used to construct this object name of child to construct This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. a #GtkBuildable a #GtkBuilder child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start This is called at the end of each custom element handled by the buildable. A #GtkBuildable #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions This is called for each unknown element under <child>. %TRUE if a object has a custom implementation, %FALSE if it doesn't. a #GtkBuildable a #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag a #GMarkupParser to fill in return location for user data that will be passed in to parser functions Get the internal child called @childname of the @buildable object. the internal child of the buildable object a #GtkBuildable a #GtkBuilder name of child Gets the name of the @buildable object. #GtkBuilder sets the name based on the [GtkBuilder UI definition][BUILDER-UI] used to construct the @buildable. the name set with gtk_buildable_set_name() a #GtkBuildable Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk_builder_add_from_file() or gtk_builder_add_from_string() is called on a builder. a #GtkBuildable a #GtkBuilder Sets the property name @name to @value on the @buildable object. a #GtkBuildable a #GtkBuilder name of property value of property Sets the name of the @buildable object. a #GtkBuildable name to set Adds a child to @buildable. @type is an optional string describing how the child should be added. a #GtkBuildable a #GtkBuilder child to add kind of child or %NULL Constructs a child of @buildable with the name @name. #GtkBuilder calls this function if a “constructor” has been specified in the UI definition. the constructed child A #GtkBuildable #GtkBuilder used to construct this object name of child to construct This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. a #GtkBuildable a #GtkBuilder child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start This is called at the end of each custom element handled by the buildable. A #GtkBuildable #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions This is called for each unknown element under <child>. %TRUE if a object has a custom implementation, %FALSE if it doesn't. a #GtkBuildable a #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag a #GMarkupParser to fill in return location for user data that will be passed in to parser functions Get the internal child called @childname of the @buildable object. the internal child of the buildable object a #GtkBuildable a #GtkBuilder name of child Gets the name of the @buildable object. #GtkBuilder sets the name based on the [GtkBuilder UI definition][BUILDER-UI] used to construct the @buildable. the name set with gtk_buildable_set_name() a #GtkBuildable Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk_builder_add_from_file() or gtk_builder_add_from_string() is called on a builder. a #GtkBuildable a #GtkBuilder Sets the property name @name to @value on the @buildable object. a #GtkBuildable a #GtkBuilder name of property value of property Sets the name of the @buildable object. a #GtkBuildable name to set The #GtkBuildableIface interface contains method that are necessary to allow #GtkBuilder to construct an object from a #GtkBuilder UI definition. the parent class a #GtkBuildable name to set the name set with gtk_buildable_set_name() a #GtkBuildable a #GtkBuildable a #GtkBuilder child to add kind of child or %NULL a #GtkBuildable a #GtkBuilder name of property value of property the constructed child A #GtkBuildable #GtkBuilder used to construct this object name of child to construct %TRUE if a object has a custom implementation, %FALSE if it doesn't. a #GtkBuildable a #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag a #GMarkupParser to fill in return location for user data that will be passed in to parser functions A #GtkBuildable #GtkBuilder used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions a #GtkBuildable a #GtkBuilder child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start a #GtkBuildable a #GtkBuilder the internal child of the buildable object a #GtkBuildable a #GtkBuilder name of child A GtkBuilder is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To create a GtkBuilder from a user interface description, call gtk_builder_new_from_file(), gtk_builder_new_from_resource() or gtk_builder_new_from_string(). In the (unusual) case that you want to add user interface descriptions from multiple sources to the same GtkBuilder you can call gtk_builder_new() to get an empty builder and populate it by (multiple) calls to gtk_builder_add_from_file(), gtk_builder_add_from_resource() or gtk_builder_add_from_string(). A GtkBuilder 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 gtk_widget_destroy() to get rid of them and all the widgets they contain. The functions gtk_builder_get_object() and gtk_builder_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 gtk_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 g_object_ref() to keep them beyond the lifespan of the builder. The function gtk_builder_connect_signals() and variants thereof can be used to connect handlers to the named signals in the description. # GtkBuilder UI Definitions # {#BUILDER-UI} GtkBuilder 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 “GtkBuilder UI definitions” or just “UI definitions” if the context is clear. Do not confuse GtkBuilder UI Definitions with [GtkUIManager UI Definitions][XML-UI], which are more limited in scope. It is common to use `.ui` as the filename extension for files containing GtkBuilder 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 gtk_builder_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, GtkBuilder allows to use an object that has been constructed by a #GtkUIManager in another part of the UI definition by specifying the id of the #GtkUIManager 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 gtk_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. GtkBuilder 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 g_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 gtk_builder_expose_object(). In general, GtkBuilder 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 g_object_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 g_module_symbol(), but this can be changed by passing a custom #GtkBuilderConnectFunc to gtk_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 #GtkDialog). This can be achieved by setting the “internal-child” property of the <child> element to a true value. Note that GtkBuilder 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 GtkBuilder UI Definition |[ <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 [GtkWidget documentation][composite-templates] for details. Creates a new empty builder object. This function is only useful if you intend to make multiple calls to gtk_builder_add_from_file(), gtk_builder_add_from_resource() or gtk_builder_add_from_string() in order to merge multiple UI descriptions into a single builder. Most users will probably want to use gtk_builder_new_from_file(), gtk_builder_new_from_resource() or gtk_builder_new_from_string(). a new (empty) #GtkBuilder object Builds the [GtkBuilder 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. a #GtkBuilder containing the described interface filename of user interface description file Builds the [GtkBuilder 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. a #GtkBuilder containing the described interface a #GResource resource path Builds the user interface described by @string (in the [GtkBuilder UI definition][BUILDER-UI] format). If @string is %NULL-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. a #GtkBuilder containing the interface described by @string a user interface (XML) description the length of @string, or -1 Looks up a type by name, using the virtual function that #GtkBuilder has for that purpose. This is mainly used when implementing the #GtkBuildable interface on a type. the #GType found for @type_name or #G_TYPE_INVALID if no type was found a #GtkBuilder type name to lookup Adds the @callback_symbol to the scope of @builder under the given @callback_name. Using this function overrides the behavior of gtk_builder_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. a #GtkBuilder The name of the callback, as expected in the XML The callback pointer A convenience function to add many callbacks instead of calling gtk_builder_add_callback_symbol() for each symbol. a #GtkBuilder The name of the callback, as expected in the XML The callback pointer A list of callback name and callback symbol pairs terminated with %NULL Parses a file containing a [GtkBuilder UI definition][BUILDER-UI] and merges it with the current contents of @builder. Most users will probably want to use gtk_builder_new_from_file(). If an error occurs, 0 will be returned and @error will be assigned a #GError 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 #GtkBuilder 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(). A positive value on success, 0 if an error occurred a #GtkBuilder the name of the file to parse Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI] and merges it with the current contents of @builder. Most users will probably want to use gtk_builder_new_from_resource(). If an error occurs, 0 will be returned and @error will be assigned a #GError 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(). A positive value on success, 0 if an error occurred a #GtkBuilder the path of the resource file to parse Parses a string containing a [GtkBuilder UI definition][BUILDER-UI] and merges it with the current contents of @builder. Most users will probably want to use gtk_builder_new_from_string(). Upon errors 0 will be returned and @error will be assigned a #GError 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(). A positive value on success, 0 if an error occurred a #GtkBuilder the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Parses a file containing a [GtkBuilder UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of @builder. Upon errors 0 will be returned and @error will be assigned a #GError 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 #GtkTreeView that depends on its #GtkTreeModel), you have to explicitly list all of them in @object_ids. A positive value on success, 0 if an error occurred a #GtkBuilder the name of the file to parse nul-terminated array of objects to build Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of @builder. Upon errors 0 will be returned and @error will be assigned a #GError 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 #GtkTreeView that depends on its #GtkTreeModel), you have to explicitly list all of them in @object_ids. A positive value on success, 0 if an error occurred a #GtkBuilder the path of the resource file to parse nul-terminated array of objects to build Parses a string containing a [GtkBuilder UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of @builder. Upon errors 0 will be returned and @error will be assigned a #GError 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 #GtkTreeView that depends on its #GtkTreeModel), you have to explicitly list all of them in @object_ids. A positive value on success, 0 if an error occurred a #GtkBuilder the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) nul-terminated array of objects to build This method is a simpler variation of gtk_builder_connect_signals_full(). It uses symbols explicitly added to @builder with prior calls to gtk_builder_add_callback_symbol(). In the case that symbols are not explicitly added; it uses #GModule’s introspective features (by opening the module %NULL) 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 gtk_builder_add_callback_symbol() is called for all signal callbacks which are referenced by the loaded XML, this function will require that #GModule be supported on the platform. If you rely on #GModule 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. a #GtkBuilder user data to pass back with all signals This function can be thought of the interpreted language binding version of gtk_builder_connect_signals(), except that it does not require GModule to function correctly. a #GtkBuilder the function used to connect the signals arbitrary data that will be passed to the connection function Add @object to the @builder object pool so it can be referenced just like any other object built by builder. a #GtkBuilder the name of the object exposed to the builder the object to expose 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. A positive value on success, 0 if an error occurred a #GtkBuilder the widget that is being extended the type that the template is for the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Gets the #GtkApplication associated with the builder. The #GtkApplication 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 g_application_get_default(). If you want to use another application for constructing proxies, use gtk_builder_set_application(). the application being used by the builder, or %NULL a #GtkBuilder Gets the object named @name. Note that this function does not increment the reference count of the returned object. the object named @name or %NULL if it could not be found in the object tree. a #GtkBuilder name of object to get Gets all objects that have been constructed by @builder. Note that this function does not increment the reference counts of the returned objects. a newly-allocated #GSList containing all the objects constructed by the #GtkBuilder instance. It should be freed by g_slist_free() a #GtkBuilder Gets the translation domain of @builder. the translation domain. This string is owned by the builder object and must not be modified or freed. a #GtkBuilder Looks up a type by name, using the virtual function that #GtkBuilder has for that purpose. This is mainly used when implementing the #GtkBuildable interface on a type. the #GType found for @type_name or #G_TYPE_INVALID if no type was found a #GtkBuilder type name to lookup Fetches a symbol previously added to @builder with gtk_builder_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 gtk_builder_connect_signals_full() The callback symbol in @builder for @callback_name, or %NULL a #GtkBuilder The name of the callback Sets the application associated with @builder. You only need this function if there is more than one #GApplication in your process. @application cannot be %NULL. a #GtkBuilder a #GtkApplication Sets the translation domain of @builder. See #GtkBuilder:translation-domain. a #GtkBuilder the translation domain or %NULL This function demarshals a value from a string. This function calls g_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, #GdkColor, #GdkRGBA and #GtkAdjustment type values. Support for #GtkWidget type values is still to come. Upon errors %FALSE will be returned and @error will be assigned a #GError from the #GTK_BUILDER_ERROR domain. %TRUE on success a #GtkBuilder the #GParamSpec for the property the string representation of the value the #GValue to store the result in Like gtk_builder_value_from_string(), this function demarshals a value from a string, but takes a #GType instead of #GParamSpec. This function calls g_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 #GError from the #GTK_BUILDER_ERROR domain. %TRUE on success a #GtkBuilder the #GType of the value the string representation of the value the #GValue to store the result in The translation domain used when translating property values that have been marked as translatable in interface descriptions. If the translation domain is %NULL, #GtkBuilder uses gettext(), otherwise g_dgettext(). the #GType found for @type_name or #G_TYPE_INVALID if no type was found a #GtkBuilder type name to lookup This is the signature of a function used to connect signals. It is used by the gtk_builder_connect_signals() and gtk_builder_connect_signals_full() methods. It is mainly intended for interpreted language bindings, but could be useful where the programmer wants more control over the signal connection process. Note that this function can only be called once, subsequent calls will do nothing. a #GtkBuilder object to connect a signal to name of the signal name of the handler a #GObject, if non-%NULL, use g_signal_connect_object() #GConnectFlags to use user data Error codes that identify various errors that can occur while using #GtkBuilder. A type-func attribute didn’t name a function that returns a #GType. The input contained a tag that #GtkBuilder can’t handle. An attribute that is required by #GtkBuilder was missing. #GtkBuilder found an attribute that it doesn’t understand. #GtkBuilder found a tag that it doesn’t understand. A required property value was missing. #GtkBuilder couldn’t parse some attribute value. The input file requires a newer version of GTK+. An object id occurred twice. A specified object type is of the same type or derived from the type of the composite class being extended with builder XML. The wrong type was specified in a composite class’s template XML The specified property is unknown for the object class. The specified signal is unknown for the object class. An object id is unknown The #GtkButton 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 #GtkButton widget can hold any valid child widget. That is, it can hold almost any other standard #GtkWidget. The most commonly used child is the #GtkLabel. # CSS nodes GtkButton 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 GtkButton include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class. Button-like widgets like #GtkToggleButton, #GtkMenuButton, #GtkVolumeButton, #GtkLockButton, #GtkColorButton, #GtkFontButton or #GtkFileChooserButton use style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file to differentiate themselves from a plain GtkButton. Creates a new #GtkButton widget. To add a child widget to the button, use gtk_container_add(). The newly created #GtkButton widget. 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 gtk_button_new() and gtk_button_set_image(). a new #GtkButton displaying the themed icon an icon name or %NULL an icon size (#GtkIconSize) Creates a new #GtkButton containing the image and text from a [stock item][gtkstock]. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. If @stock_id is unknown, then it will be treated as a mnemonic label (as for gtk_button_new_with_mnemonic()). Stock items are deprecated. Use gtk_button_new_with_label() instead. a new #GtkButton the name of the stock item Creates a #GtkButton widget with a #GtkLabel child containing the given text. The newly created #GtkButton widget. The text you want the #GtkLabel to hold. Creates a new #GtkButton 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. a new #GtkButton The text of the button, with an underscore in front of the mnemonic character Emits a #GtkButton::clicked signal to the given #GtkButton. The #GtkButton you want to send the signal to. Emits a #GtkButton::enter signal to the given #GtkButton. Use the #GtkWidget::enter-notify-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::leave signal to the given #GtkButton. Use the #GtkWidget::leave-notify-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::pressed signal to the given #GtkButton. Use the #GtkWidget::button-press-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::released signal to the given #GtkButton. Use the #GtkWidget::button-release-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::clicked signal to the given #GtkButton. The #GtkButton you want to send the signal to. Emits a #GtkButton::enter signal to the given #GtkButton. Use the #GtkWidget::enter-notify-event signal. The #GtkButton you want to send the signal to. Gets the alignment of the child in the button. Access the child widget directly if you need to control its alignment. a #GtkButton return location for horizontal alignment return location for vertical alignment Returns whether the button will ignore the #GtkSettings:gtk-button-images setting and always show the image, if available. %TRUE if the button will always show the image a #GtkButton Returns the button’s event window if it is realized, %NULL otherwise. This function should be rarely needed. @button’s event window. a #GtkButton Returns whether the button grabs focus when it is clicked with the mouse. See gtk_button_set_focus_on_click(). Use gtk_widget_get_focus_on_click() instead %TRUE if the button grabs focus when it is clicked with the mouse. a #GtkButton Gets the widget that is currenty set as the image of @button. This may have been explicitly set by gtk_button_set_image() or constructed by gtk_button_new_from_stock(). a #GtkWidget or %NULL in case there is no image a #GtkButton Gets the position of the image relative to the text inside the button. the position a #GtkButton Fetches the text from the label of the button, as set by gtk_button_set_label(). If the label text has not been set the return value will be %NULL. This will be the case if you create an empty button with gtk_button_new() to use as a container. The text of the label widget. This string is owned by the widget and must not be modified or freed. a #GtkButton Returns the current relief style of the given #GtkButton. The current #GtkReliefStyle The #GtkButton you want the #GtkReliefStyle from. Returns whether the button label is a stock item. %TRUE if the button label is used to select a stock item instead of being used directly as the label text. a #GtkButton Returns whether an embedded underline in the button label indicates a mnemonic. See gtk_button_set_use_underline (). %TRUE if an embedded underline in the button label indicates the mnemonic accelerator keys. a #GtkButton Emits a #GtkButton::leave signal to the given #GtkButton. Use the #GtkWidget::leave-notify-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::pressed signal to the given #GtkButton. Use the #GtkWidget::button-press-event signal. The #GtkButton you want to send the signal to. Emits a #GtkButton::released signal to the given #GtkButton. Use the #GtkWidget::button-release-event signal. The #GtkButton you want to send the signal to. Sets the alignment of the child. This property has no effect unless the child is a #GtkMisc or a #GtkAlignment. Access the child widget directly if you need to control its alignment. a #GtkButton the horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned the vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned If %TRUE, the button will ignore the #GtkSettings: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. a #GtkButton %TRUE if the menuitem should always show the image 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. Use gtk_widget_set_focus_on_click() instead a #GtkButton whether the button grabs focus when clicked with the mouse Set the image of @button to the given widget. The image will be displayed if the label text is %NULL or if #GtkButton:always-show-image is %TRUE. You don’t have to call gtk_widget_show() on @image yourself. a #GtkButton a widget to set as the image for the button, or %NULL to unset Sets the position of the image relative to the text inside the button. a #GtkButton the position Sets the text of the label of the button to @str. This text is also used to select the stock item if gtk_button_set_use_stock() is used. This will also clear any previously set labels. a #GtkButton a string Sets the relief style of the edges of the given #GtkButton widget. Two styles exist, %GTK_RELIEF_NORMAL and %GTK_RELIEF_NONE. The default style is, as one can guess, %GTK_RELIEF_NORMAL. The deprecated value %GTK_RELIEF_HALF behaves the same as %GTK_RELIEF_NORMAL. The #GtkButton you want to set relief styles of The GtkReliefStyle as described above If %TRUE, the label set on the button is used as a stock id to select the stock item for the button. a #GtkButton %TRUE if the button should use a stock item If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key. a #GtkButton %TRUE if underlines in the text indicate mnemonics If %TRUE, the button will ignore the #GtkSettings: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. The child widget to appear next to the button text. The position of the image relative to the text inside the button. If the child of the button is a #GtkMisc or #GtkAlignment, this property can be used to control its horizontal alignment. 0.0 is left aligned, 1.0 is right aligned. Access the child widget directly if you need to control its alignment. If the child of the button is a #GtkMisc or #GtkAlignment, this property can be used to control its vertical alignment. 0.0 is top aligned, 1.0 is bottom aligned. Access the child widget directly if you need to control its alignment. The ::activate signal on GtkButton 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 #GtkButton::clicked signal. Emitted when the button has been activated (pressed and released). Emitted when the pointer enters the button. Use the #GtkWidget::enter-notify-event signal. Emitted when the pointer leaves the button. Use the #GtkWidget::leave-notify-event signal. Emitted when the button is pressed. Use the #GtkWidget::button-press-event signal. Emitted when the button is released. Use the #GtkWidget::button-release-event signal. Creates a new #GtkButtonBox. a new #GtkButtonBox. the box's orientation. Returns whether the child is exempted from homogenous sizing. %TRUE if the child is not subject to homogenous sizing a #GtkButtonBox a child of @widget Returns whether @child should appear in a secondary group of children. whether @child should appear in a secondary group of children. a #GtkButtonBox a child of @widget Retrieves the method being used to arrange the buttons in a button box. the method used to lay out buttons in @widget. a #GtkButtonBox Sets whether the child is exempted from homogeous sizing. a #GtkButtonBox a child of @widget the new value 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 %GTK_BUTTONBOX_START, %GTK_BUTTONBOX_SPREAD or %GTK_BUTTONBOX_EDGE, and before the other children if the style is %GTK_BUTTONBOX_END. For horizontal button boxes, the definition of before/after depends on direction of the widget (see gtk_widget_set_direction()). If the style is %GTK_BUTTONBOX_START or %GTK_BUTTONBOX_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. a #GtkButtonBox a child of @widget if %TRUE, the @child appears in a secondary group of the button box. Changes the way buttons are arranged in their container. a #GtkButtonBox the new layout style The parent class. Used to dictate the style that a #GtkButtonBox uses to layout the buttons it contains. Buttons are evenly spread across the box. Buttons are placed at the edges of the box. Buttons are grouped towards the start of the box, (on the left for a HBox, or the top for a VBox). Buttons are grouped towards the end of the box, (on the right for a HBox, or the bottom for a VBox). Buttons are centered in the box. Since 2.12. 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 gtk_box_set_homogeneous() and gtk_box_set_spacing() manually). Since 3.12. The parent class. The #GtkButton you want to send the signal to. The #GtkButton you want to send the signal to. The #GtkButton you want to send the signal to. The #GtkButton you want to send the signal to. The #GtkButton you want to send the signal to. The role specifies the desired appearance of a #GtkModelButton. A plain button A check button A radio button Prebuilt sets of buttons for the dialog. If none of these choices are appropriate, simply use %GTK_BUTTONS_NONE then call gtk_dialog_add_buttons(). > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO > and %GTK_BUTTONS_OK_CANCEL are discouraged by the > [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/). no buttons at all an OK button a Close button a Cancel button Yes and No buttons OK and Cancel buttons This macro should be used to emit a standard warning about unexpected properties in set_cell_property() and get_cell_property() implementations. the #GObject on which set_cell_property() or get_cell_property() was called the numeric id of the property the #GParamSpec of the property Returns %TRUE if the version of the GTK+ header files is the same as or newer than the passed-in version. major version (e.g. 1 for version 1.2.5) minor version (e.g. 2 for version 1.2.5) micro version (e.g. 5 for version 1.2.5) This macro should be used to emit a standard warning about unexpected properties in set_child_property() and get_child_property() implementations. the #GObject on which set_child_property() or get_child_property() was called the numeric id of the property the #GParamSpec of the property #GtkCalendar is a widget that displays a Gregorian calendar, one month at a time. It can be created with gtk_calendar_new(). The month and year currently displayed can be altered with gtk_calendar_select_month(). The exact day can be selected from the displayed month using gtk_calendar_select_day(). To place a visual marker on a particular day, use gtk_calendar_mark_day() and to remove the marker, gtk_calendar_unmark_day(). Alternative, all marks can be cleared with gtk_calendar_clear_marks(). The way in which the calendar itself is displayed can be altered using gtk_calendar_set_display_options(). The selected date can be retrieved from a #GtkCalendar using gtk_calendar_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. Creates a new calendar, with the current date being selected. a newly #GtkCalendar widget Remove all visual markers. a #GtkCalendar Obtains the selected date from a #GtkCalendar. a #GtkCalendar location to store the year as a decimal number (e.g. 2011), or %NULL location to store the month number (between 0 and 11), or %NULL location to store the day number (between 1 and 31), or %NULL Returns if the @day of the @calendar is already marked. whether the day is marked. a #GtkCalendar the day number between 1 and 31. Queries the height of detail cells, in rows. See #GtkCalendar:detail-width-chars. The height of detail cells, in rows. a #GtkCalendar. Queries the width of detail cells, in characters. See #GtkCalendar:detail-width-chars. The width of detail cells, in characters. a #GtkCalendar. Returns the current display options of @calendar. the display options. a #GtkCalendar Places a visual marker on a particular day. a #GtkCalendar the day number to mark between 1 and 31. Selects a day from the current month. a #GtkCalendar. the day number between 1 and 31, or 0 to unselect the currently selected day. Shifts the calendar to a different month. a #GtkCalendar a month number between 0 and 11. the year the month is in. 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 #GtkCalendar: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 #GtkCalendar:show-details is not set. The size of the details area can be restricted by setting the #GtkCalendar:detail-width-chars and #GtkCalendar:detail-height-rows properties. a #GtkCalendar. a function providing details for each day. data to pass to @func invokations. a function for releasing @data. Updates the height of detail cells. See #GtkCalendar:detail-height-rows. a #GtkCalendar. detail height in rows. Updates the width of detail cells. See #GtkCalendar:detail-width-chars. a #GtkCalendar. detail width in characters. Sets display options (whether to display the heading and the month headings). a #GtkCalendar the display options to set Removes the visual marker from a particular day. a #GtkCalendar. the day number to unmark between 1 and 31. 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. Height of a detail cell, in rows. A value of 0 allows any width. See gtk_calendar_set_detail_func(). Width of a detail cell, in characters. A value of 0 allows any width. See gtk_calendar_set_detail_func(). The selected month (as a number between 0 and 11). This property gets initially set to the current month. Determines whether the selected month can be changed. Determines whether day names are displayed. 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. Determines whether a heading is displayed. Determines whether week numbers are displayed. The selected year. This property gets initially set to the current year. Emitted when the user selects a day. Emitted when the user double-clicks a day. Emitted when the user clicks a button to change the selected month on a calendar. Emitted when the user switched to the next month. Emitted when user switched to the next year. Emitted when the user switched to the previous month. Emitted when user switched to the previous year. This kind of functions provide Pango markup with detail information for the specified day. Examples for such details are holidays or appointments. The function returns %NULL when no information is available. Newly allocated string with Pango markup with details for the specified day or %NULL. a #GtkCalendar. the year for which details are needed. the month for which details are needed. the day of @month for which details are needed. the data passed with gtk_calendar_set_detail_func(). These options can be used to influence the display and behaviour of a #GtkCalendar. Specifies that the month and year should be displayed. Specifies that three letter day descriptions should be present. Prevents the user from switching months with the calendar. Displays each week numbers of the current year, down the left side of the calendar. Just show an indicator, not the full details text when details are provided. See gtk_calendar_set_detail_func(). The type of the callback functions used for e.g. iterating over the children of a container, see gtk_container_foreach(). the widget to operate on user-supplied data The type of the callback functions used for iterating over the cell renderers and their allocated areas inside a #GtkCellArea, see gtk_cell_area_foreach_alloc(). %TRUE to stop iterating over cells. the cell renderer to operate on the area allocated to @renderer inside the rectangle provided to gtk_cell_area_foreach_alloc(). the background area for @renderer inside the background area provided to gtk_cell_area_foreach_alloc(). user-supplied data The #GtkCellArea is an abstract class for #GtkCellLayout widgets (also referred to as "layouting widgets") to interface with an arbitrary number of #GtkCellRenderers and interact with the user for a given #GtkTreeModel 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 #GtkCellArea directly unless they are implementing a cell-layouting widget themselves. # Requesting area sizes As outlined in [GtkWidget’s geometry management section][geometry-management], GTK+ uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. #GtkCellArea uses the same semantics to calculate the size of an area for an arbitrary number of #GtkTreeModel 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 #GtkTreeViewColumn always lines up the areas from top to bottom while a #GtkIconView 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 #GtkCellArea uses a #GtkCellAreaContext 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 #GtkCellAreaContext is an opaque object specific to the #GtkCellArea which created it (see gtk_cell_area_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 #GtkCellAreaContext which was used to request the sizes for a given #GtkTreeModel 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 #GtkTreeModel one would do the following: |[<!-- language="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 #GtkCellAreaContext object and can be consulted at any time. This can be useful since #GtkCellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The #GtkCellLayout 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 #GtkWidgetClass.get_preferred_width() it can simply consult the width accumulated so far in the #GtkCellAreaContext 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: |[<!-- language="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 #GtkCellAreaContext. Requesting the height for width (or width for height) of an area is a similar task except in this case the #GtkCellAreaContext 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 #GtkCellArea). In order to request the height for width of all the rows at the root level of a #GtkTreeModel one would do the following: |[<!-- language="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 #GtkWidgetClass.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 #GtkWidgetClass.draw() time. A crude example of how to render all the rows at the root level runs as follows: |[<!-- language="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 #GtkWidget::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 gtk_cell_area_event() API as they come in. Usually #GtkCellArea 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 #GtkCellArea::focus-changed signal to fire; as well as #GtkCellArea::add-editable in the case that an editable cell was clicked and needs to start editing. You can call gtk_cell_area_stop_editing() at any time to cancel any cell editing that is currently in progress. The #GtkCellArea drives keyboard focus from cell to cell in a way similar to #GtkWidget. For layouting widgets that support giving focus to cells it’s important to remember to pass %GTK_CELL_RENDERER_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 #GtkWidgetClass.focus() virtual method. The layouting widget is always responsible for knowing where #GtkTreeModel rows are rendered inside the widget, so at #GtkWidgetClass.focus() time the layouting widget should use the #GtkCellArea methods to navigate focus inside the area and then observe the GtkDirectionType to pass the focus to adjacent rows and areas. A basic example of how the #GtkWidgetClass.focus() virtual method should be implemented: |[<!-- language="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 GtkDirectionType values to the way it lays out its cells. # Cell Properties The #GtkCellArea introduces cell properties for #GtkCellRenderers in very much the same way that #GtkContainer 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 #GtkCellAreaBox 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 #GtkCellAreaContext. Use gtk_cell_area_class_install_cell_property() to install cell properties for a cell area class and gtk_cell_area_class_find_cell_property() or gtk_cell_area_class_list_cell_properties() to get information about existing cell properties. To set the value of a cell property, use gtk_cell_area_cell_set_property(), gtk_cell_area_cell_set() or gtk_cell_area_cell_set_valist(). To obtain the value of a cell property, use gtk_cell_area_cell_get_property(), gtk_cell_area_cell_get() or gtk_cell_area_cell_get_valist(). Activates @area, 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. Whether @area was successfully activated. a #GtkCellArea the #GtkCellAreaContext in context with the current row data the #GtkWidget that @area is rendering on the size and location of @area relative to @widget’s allocation the #GtkCellRendererState flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Adds @renderer to @area with the default child cell properties. a #GtkCellArea the #GtkCellRenderer to add to @area Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a #GtkCellArea the #GtkTreeModel to pull values from the #GtkTreeIter in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible 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, #GtkIconView 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. #GtkIconView 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. a newly created #GtkCellAreaContext copy of @context. a #GtkCellArea the #GtkCellAreaContext to copy Creates a #GtkCellAreaContext to be used with @area for all purposes. #GtkCellAreaContext 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 #GtkCellAreaContext which was used to request the size of those rows of data). a newly created #GtkCellAreaContext which can be used with @area. a #GtkCellArea Delegates event handling to a #GtkCellArea. %TRUE if the event was handled by @area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #GdkEvent to handle the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing #GtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a #GtkCellArea the #GtkDirectionType Calls @callback for every #GtkCellRenderer in @area. a #GtkCellArea the #GtkCellCallback to call user provided data pointer Calls @callback for every #GtkCellRenderer in @area with the allocated rectangle inside @cell_area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the #GtkCellAllocCallback to call user provided data pointer Retrieves a cell area’s initial minimum and natural height. @area 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 gtk_cell_area_context_get_preferred_height() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_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 gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the width for which to check the height of this area location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s initial minimum and natural width. @area 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 gtk_cell_area_context_get_preferred_width() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_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 gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the height for which to check the width of this area location to store the minimum width, or %NULL location to store the natural width, or %NULL Gets whether the area prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by @area. a #GtkCellArea Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a #GtkCellArea Removes @renderer from @area. a #GtkCellArea the #GtkCellRenderer to remove from @area Renders @area’s cells according to @area’s layout onto @widget at the given coordinates. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #cairo_t to render with the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Activates @area, 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. Whether @area was successfully activated. a #GtkCellArea the #GtkCellAreaContext in context with the current row data the #GtkWidget that @area is rendering on the size and location of @area relative to @widget’s allocation the #GtkCellRendererState flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. This is used by #GtkCellArea subclasses when handling events to activate cells, the base #GtkCellArea class activates cells for keyboard events for free in its own GtkCellArea->activate() implementation. whether cell activation was successful a #GtkCellArea the #GtkWidget that @area is rendering onto the #GtkCellRenderer in @area to activate the #GdkEvent for which cell activation should occur the #GdkRectangle in @widget relative coordinates of @renderer for the current row. the #GtkCellRendererState for @renderer Adds @renderer to @area with the default child cell properties. a #GtkCellArea the #GtkCellRenderer to add to @area 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. a #GtkCellArea the #GtkCellRenderer expected to have focus the #GtkCellRenderer to add to @renderer’s focus area Adds @renderer to @area, setting cell properties at the same time. See gtk_cell_area_add() and gtk_cell_area_cell_set() for more details. a #GtkCellArea a #GtkCellRenderer to be placed inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a #GtkCellArea the #GtkTreeModel to pull values from the #GtkTreeIter in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Connects an @attribute to apply values from @column for the #GtkTreeModel in use. a #GtkCellArea the #GtkCellRenderer to connect an attribute for the attribute name the #GtkTreeModel column to fetch attribute values from Disconnects @attribute for the @renderer in @area so that attribute will no longer be updated with values from the model. a #GtkCellArea the #GtkCellRenderer to disconnect an attribute for the attribute name Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped. the model column, or -1 a #GtkCellArea a #GtkCellRenderer an attribute on the renderer Gets the values of one or more cell properties for @renderer in @area. a #GtkCellArea a #GtkCellRenderer which is inside @area the name of the first cell property to get return location for the first cell property, followed optionally by more name/return location pairs, followed by %NULL Gets the value of a cell property for @renderer in @area. a #GtkCellArea a #GtkCellRenderer inside @area the name of the property to get a location to return the value Gets the values of one or more cell properties for @renderer in @area. a #GtkCellArea a #GtkCellRenderer inside @area the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Sets one or more cell properties for @cell in @area. a #GtkCellArea a #GtkCellRenderer which is a cell inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Sets a cell property for @renderer in @area. a #GtkCellArea a #GtkCellRenderer inside @area the name of the cell property to set the value to set the cell property to Sets one or more cell properties for @renderer in @area. a #GtkCellArea a #GtkCellRenderer which inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name 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, #GtkIconView 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. #GtkIconView 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. a newly created #GtkCellAreaContext copy of @context. a #GtkCellArea the #GtkCellAreaContext to copy Creates a #GtkCellAreaContext to be used with @area for all purposes. #GtkCellAreaContext 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 #GtkCellAreaContext which was used to request the size of those rows of data). a newly created #GtkCellAreaContext which can be used with @area. a #GtkCellArea Delegates event handling to a #GtkCellArea. %TRUE if the event was handled by @area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #GdkEvent to handle the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing #GtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a #GtkCellArea the #GtkDirectionType Calls @callback for every #GtkCellRenderer in @area. a #GtkCellArea the #GtkCellCallback to call user provided data pointer Calls @callback for every #GtkCellRenderer in @area with the allocated rectangle inside @cell_area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the #GtkCellAllocCallback to call user provided data pointer Derives the allocation of @renderer inside @area if @area were to be renderered in @cell_area. a #GtkCellArea the #GtkCellAreaContext used to hold sizes for @area. the #GtkWidget that @area is rendering on the #GtkCellRenderer to get the allocation for the whole allocated area for @area in @widget for this row where to store the allocation for @renderer Gets the #GtkCellRenderer at @x and @y coordinates inside @area and optionally returns the full cell allocation for it inside @cell_area. the #GtkCellRenderer at @x and @y. a #GtkCellArea the #GtkCellAreaContext used to hold sizes for @area. the #GtkWidget that @area is rendering on the whole allocated area for @area in @widget for this row the x position the y position where to store the inner allocated area of the returned cell renderer, or %NULL. Gets the current #GtkTreePath string for the currently applied #GtkTreeIter, this is implicitly updated when gtk_cell_area_apply_attributes() is called and can be used to interact with renderers from #GtkCellArea subclasses. The current #GtkTreePath string for the current attributes applied to @area. This string belongs to the area and should not be freed. a #GtkCellArea Gets the #GtkCellEditable widget currently used to edit the currently edited cell. The currently active #GtkCellEditable widget a #GtkCellArea Gets the #GtkCellRenderer in @area that is currently being edited. The currently edited #GtkCellRenderer a #GtkCellArea Retrieves the currently focused cell for @area the currently focused cell in @area. a #GtkCellArea Gets the #GtkCellRenderer which is expected to be focusable for which @renderer is, or may be a sibling. This is handy for #GtkCellArea 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. the #GtkCellRenderer for which @renderer is a sibling, or %NULL. a #GtkCellArea the #GtkCellRenderer Gets the focus sibling cell renderers for @renderer. A #GList of #GtkCellRenderers. The returned list is internal and should not be freed. a #GtkCellArea the #GtkCellRenderer expected to have focus Retrieves a cell area’s initial minimum and natural height. @area 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 gtk_cell_area_context_get_preferred_height() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_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 gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the width for which to check the height of this area location to store the minimum height, or %NULL location to store the natural height, or %NULL Retrieves a cell area’s initial minimum and natural width. @area 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 gtk_cell_area_context_get_preferred_width() after a series of requests. a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_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 gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the height for which to check the width of this area location to store the minimum width, or %NULL location to store the natural width, or %NULL Gets whether the area prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by @area. a #GtkCellArea Checks if @area contains @renderer. %TRUE if @renderer is in the @area. a #GtkCellArea the #GtkCellRenderer to check This is a convenience function for #GtkCellArea implementations to get the inner area where a given #GtkCellRenderer will be rendered. It removes any padding previously added by gtk_cell_area_request_renderer(). a #GtkCellArea the #GtkWidget that @area is rendering onto the @widget relative coordinates where one of @area’s cells is to be placed the return location for the inner cell area Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a #GtkCellArea Returns whether @sibling is one of @renderer’s focus siblings (see gtk_cell_area_add_focus_sibling()). %TRUE if @sibling is a focus sibling of @renderer a #GtkCellArea the #GtkCellRenderer expected to have focus the #GtkCellRenderer to check against @renderer’s sibling list Removes @renderer from @area. a #GtkCellArea the #GtkCellRenderer to remove from @area Removes @sibling from @renderer’s focus sibling list (see gtk_cell_area_add_focus_sibling()). a #GtkCellArea the #GtkCellRenderer expected to have focus the #GtkCellRenderer to remove from @renderer’s focus area Renders @area’s cells according to @area’s layout onto @widget at the given coordinates. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #cairo_t to render with the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. whether @area should paint focus on focused cells for focused rows or not. This is a convenience function for #GtkCellArea implementations to request size for cell renderers. It’s important to use this function to request size and then use gtk_cell_area_inner_cell_area() at render and event time since this function will add padding around the cell for focus painting. a #GtkCellArea the #GtkCellRenderer to request size for the #GtkOrientation in which to request size the #GtkWidget that @area is rendering onto the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned. location to store the minimum size, or %NULL location to store the natural size, or %NULL Explicitly sets the currently focused cell to @renderer. This is generally called by implementations of #GtkCellAreaClass.focus() or #GtkCellAreaClass.event(), however it can also be used to implement functions such as gtk_tree_view_set_cursor_on_cell(). a #GtkCellArea the #GtkCellRenderer to give focus to 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 gtk_cell_area_get_edited_cell() and gtk_cell_area_get_edit_widget(). a #GtkCellArea whether editing was canceled. The widget currently editing the edited cell This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that is currently edited This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that currently has focus Indicates that editing has started on @renderer and that @editable should be added to the owning cell-layouting widget at @cell_area. the #GtkCellRenderer that started the edited the #GtkCellEditable widget to add the #GtkWidget relative #GdkRectangle coordinates where @editable should be added the #GtkTreePath string this edit was initiated for This signal is emitted whenever applying attributes to @area from @model the #GtkTreeModel to apply the attributes from the #GtkTreeIter indicating which row to apply the attributes of whether the view shows children for this row whether the view is currently showing the children of this row 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. the #GtkCellRenderer that has focus the current #GtkTreePath string set for @area Indicates that editing finished on @renderer and that @editable should be removed from the owning cell-layouting widget. the #GtkCellRenderer that finished editeding the #GtkCellEditable widget to remove The #GtkCellAreaBox renders cell renderers into a row or a column depending on its #GtkOrientation. GtkCellAreaBox uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a #GtkCellAreaBox. There are two reference positions: the start and the end of the box. When the #GtkCellAreaBox is oriented in the %GTK_ORIENTATION_VERTICAL orientation, the start is defined as the top of the box and the end is defined as the bottom. In the %GTK_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 #GtkCellAreaBox align child cell property with gtk_cell_area_cell_set_property() or by specifying the "align" argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end(). Creates a new #GtkCellAreaBox. a newly created #GtkCellAreaBox Gets the spacing added between cell renderers. the space added between cell renderers in @box. a #GtkCellAreaBox Adds @renderer to @box, packed with reference to the end of @box. The @renderer is packed after (away from end of) any other #GtkCellRenderer packed with reference to the end of @box. a #GtkCellAreaBox the #GtkCellRenderer to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Adds @renderer to @box, packed with reference to the start of @box. The @renderer is packed after any other #GtkCellRenderer packed with reference to the start of @box. a #GtkCellAreaBox the #GtkCellRenderer to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Sets the spacing to add between cell renderers in @box. a #GtkCellAreaBox the space to add between #GtkCellRenderers The amount of space to reserve between cells. a #GtkCellArea the #GtkCellRenderer to add to @area a #GtkCellArea the #GtkCellRenderer to remove from @area a #GtkCellArea the #GtkCellCallback to call user provided data pointer a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the #GtkCellAllocCallback to call user provided data pointer %TRUE if the event was handled by @area. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #GdkEvent to handle the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. a #GtkCellArea the #GtkCellAreaContext for this row of data. the #GtkWidget that @area is rendering to the #cairo_t to render with the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the #GtkCellRendererState for @area in this row. whether @area should paint focus on focused cells for focused rows or not. a #GtkCellArea the #GtkTreeModel to pull values from the #GtkTreeIter in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible a newly created #GtkCellAreaContext which can be used with @area. a #GtkCellArea a newly created #GtkCellAreaContext copy of @context. a #GtkCellArea the #GtkCellAreaContext to copy The #GtkSizeRequestMode preferred by @area. a #GtkCellArea a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum width, or %NULL location to store the natural width, or %NULL a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the width for which to check the height of this area location to store the minimum height, or %NULL location to store the natural height, or %NULL a #GtkCellArea the #GtkCellAreaContext to perform this request with the #GtkWidget where @area will be rendering location to store the minimum height, or %NULL location to store the natural height, or %NULL a #GtkCellArea the #GtkCellAreaContext which has already been requested for widths. the #GtkWidget where @area will be rendering the height for which to check the width of this area location to store the minimum width, or %NULL location to store the natural width, or %NULL %TRUE if focus remains inside @area as a result of this call. a #GtkCellArea the #GtkDirectionType whether @area can do anything when activated. a #GtkCellArea Whether @area was successfully activated. a #GtkCellArea the #GtkCellAreaContext in context with the current row data the #GtkWidget that @area is rendering on the size and location of @area relative to @widget’s allocation the #GtkCellRendererState flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Finds a cell property of a cell area class by name. the #GParamSpec of the child property or %NULL if @aclass has no child property with that name. a #GtkCellAreaClass the name of the child property to find Installs a cell property on a cell area class. a #GtkCellAreaClass the id for the property the #GParamSpec for the property Returns all cell properties of a cell area class. a newly allocated %NULL-terminated array of #GParamSpec*. The array must be freed with g_free(). a #GtkCellAreaClass location to return the number of cell properties found The #GtkCellAreaContext object is created by a given #GtkCellArea implementation via its #GtkCellAreaClass.create_context() virtual method and is used to store cell sizes and alignments for a series of #GtkTreeModel rows that are requested and rendered in the same context. #GtkCellLayout 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 #GtkTreeModel row also be used for the same row when calling other #GtkCellArea APIs such as gtk_cell_area_render() and gtk_cell_area_event(). Allocates a width and/or a height for all rows which are to be rendered with @context. 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 #GtkTreeView when #GtkTreeView:fixed-height-mode is enabled. Since 3.0 a #GtkCellAreaContext the allocated width for all #GtkTreeModel rows rendered with @context, or -1. the allocated height for all #GtkTreeModel rows rendered with @context, or -1. Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed width for allocation location to store the minimum height, or %NULL location to store the natural height, or %NULL Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed height for allocation location to store the minimum width, or %NULL location to store the natural width, or %NULL Resets any previously cached request and allocation data. When underlying #GtkTreeModel 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 gtk_cell_area_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 gtk_cell_area_get_preferred_height_for_width(). Since 3.0 a #GtkCellAreaContext Allocates a width and/or a height for all rows which are to be rendered with @context. 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 #GtkTreeView when #GtkTreeView:fixed-height-mode is enabled. Since 3.0 a #GtkCellAreaContext the allocated width for all #GtkTreeModel rows rendered with @context, or -1. the allocated height for all #GtkTreeModel rows rendered with @context, or -1. Fetches the current allocation size for @context. If the context was not allocated in width or height, or if the context was recently reset with gtk_cell_area_context_reset(), the returned value will be -1. a #GtkCellAreaContext location to store the allocated width, or %NULL location to store the allocated height, or %NULL Fetches the #GtkCellArea this @context 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 #GtkCellAreaContextClass.allocate() time it’s important to know details about any cell spacing that the #GtkCellArea is configured with in order to compute a proper allocation. the #GtkCellArea this context was created by. a #GtkCellAreaContext Gets the accumulative preferred height for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are 0. a #GtkCellAreaContext location to store the minimum height, or %NULL location to store the natural height, or %NULL Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed width for allocation location to store the minimum height, or %NULL location to store the natural height, or %NULL Gets the accumulative preferred width for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are 0. a #GtkCellAreaContext location to store the minimum width, or %NULL location to store the natural width, or %NULL Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a #GtkCellArea, the returned values are -1. a #GtkCellAreaContext a proposed height for allocation location to store the minimum width, or %NULL location to store the natural width, or %NULL 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 #GtkCellAreaContext implementations during the request process over a series of #GtkTreeModel rows to progressively push the requested height over a series of gtk_cell_area_get_preferred_height() requests. a #GtkCellAreaContext the proposed new minimum height for @context the proposed new natural height for @context 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 #GtkCellAreaContext implementations during the request process over a series of #GtkTreeModel rows to progressively push the requested width over a series of gtk_cell_area_get_preferred_width() requests. a #GtkCellAreaContext the proposed new minimum width for @context the proposed new natural width for @context Resets any previously cached request and allocation data. When underlying #GtkTreeModel 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 gtk_cell_area_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 gtk_cell_area_get_preferred_height_for_width(). Since 3.0 a #GtkCellAreaContext The #GtkCellArea this context was created by The minimum height for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_height(). The minimum width for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_width(). The natural height for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_height(). The natural width for the #GtkCellArea in this context for all #GtkTreeModel rows that this context was requested for using gtk_cell_area_get_preferred_width(). a #GtkCellAreaContext the allocated width for all #GtkTreeModel rows rendered with @context, or -1. the allocated height for all #GtkTreeModel rows rendered with @context, or -1. a #GtkCellAreaContext a #GtkCellAreaContext a proposed width for allocation location to store the minimum height, or %NULL location to store the natural height, or %NULL a #GtkCellAreaContext a proposed height for allocation location to store the minimum width, or %NULL location to store the natural width, or %NULL The type of the callback functions used for iterating over the cell renderers of a #GtkCellArea, see gtk_cell_area_foreach(). %TRUE to stop iterating over cells. the cell renderer to operate on user-supplied data The #GtkCellEditable interface must be implemented for widgets to be usable to edit the contents of a #GtkTreeView cell. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc. Emits the #GtkCellEditable::editing-done signal. A #GtkCellEditable Emits the #GtkCellEditable::remove-widget signal. A #GtkCellEditable Begins editing on a @cell_editable. The #GtkCellRenderer for the cell creates and returns a #GtkCellEditable from gtk_cell_renderer_start_editing(), configured for the #GtkCellRenderer type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit #GtkCellEditable::editing-done. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A #GtkCellEditable The #GdkEvent that began the editing process, or %NULL if editing was initiated programmatically Emits the #GtkCellEditable::editing-done signal. A #GtkCellEditable Emits the #GtkCellEditable::remove-widget signal. A #GtkCellEditable Begins editing on a @cell_editable. The #GtkCellRenderer for the cell creates and returns a #GtkCellEditable from gtk_cell_renderer_start_editing(), configured for the #GtkCellRenderer type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit #GtkCellEditable::editing-done. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A #GtkCellEditable The #GdkEvent that began the editing process, or %NULL if editing was initiated programmatically Indicates whether editing on the cell has been canceled. This signal is a sign for the cell renderer to update its value from the @cell_editable. Implementations of #GtkCellEditable are responsible for emitting this signal when they are done editing, e.g. #GtkEntry 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 #GtkCellRenderer, etc. gtk_cell_editable_editing_done() is a convenience method for emitting #GtkCellEditable::editing-done. 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 #GtkCellEditable are responsible for emitting this signal when they are done editing. It must be emitted after the #GtkCellEditable::editing-done signal, to give the cell renderer a chance to update the cell's value before the widget is removed. gtk_cell_editable_remove_widget() is a convenience method for emitting #GtkCellEditable::remove-widget. A #GtkCellEditable A #GtkCellEditable A #GtkCellEditable The #GdkEvent that began the editing process, or %NULL if editing was initiated programmatically #GtkCellLayout is an interface to be implemented by all objects which want to provide a #GtkTreeViewColumn like API for packing cells, setting attributes and data funcs. One of the notable features provided by implementations of GtkCellLayout 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 gtk_cell_layout_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 gtk_cell_layout_set_cell_data_func() that is called to determine the value of the attribute for each cell that is rendered. # GtkCellLayouts as GtkBuildable Implementations of GtkCellLayout which also implement the GtkBuildable interface (#GtkCellView, #GtkIconView, #GtkComboBox, #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer 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: |[ <object class="GtkCellView"> <child> <object class="GtkCellRendererText"/> <attributes> <attribute name="text">0</attribute> </attributes> </child>" </object> ]| Furthermore for implementations of GtkCellLayout that use a #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea) [cell properties][cell-properties] can also be defined in the format by specifying the custom <cell-packing> attribute which can contain multiple <property> elements defined in the normal way. Here is a UI definition fragment specifying cell properties: |[ <object class="GtkTreeViewColumn"> <child> <object class="GtkCellRendererText"/> <cell-packing> <property name="align">True</property> <property name="expand">False</property> </cell-packing> </child>" </object> ]| # Subclassing GtkCellLayout implementations When subclassing a widget that implements #GtkCellLayout like #GtkIconView or #GtkComboBox, there are some considerations related to the fact that these widgets internally use a #GtkCellArea. The cell area is exposed as a construct-only property by these widgets. This means that it is possible to e.g. do |[<!-- language="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). |[<!-- language="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. Adds an attribute mapping to the list in @cell_layout. 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 #GtkCellRendererText get its values from column 2. a #GtkCellLayout a #GtkCellRenderer an attribute on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a #GtkCellLayout Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a #GtkCellLayout a #GtkCellRenderer to clear the attribute mapping on Returns the underlying #GtkCellArea which might be @cell_layout if called on a #GtkCellArea or might be %NULL if no #GtkCellArea is used by @cell_layout. the cell area used by @cell_layout, or %NULL in case no cell area is used. a #GtkCellLayout Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a #GtkCellLayout Adds the @cell to the end of @cell_layout. 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. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. 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. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a #GtkCellLayout a #GtkCellRenderer to reorder new position to insert @cell at Sets the #GtkCellLayoutDataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a #GtkCellLayout a #GtkCellRenderer the #GtkCellLayoutDataFunc to use, or %NULL user data for @func destroy notify for @func_data Adds an attribute mapping to the list in @cell_layout. 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 #GtkCellRendererText get its values from column 2. a #GtkCellLayout a #GtkCellRenderer an attribute on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a #GtkCellLayout Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a #GtkCellLayout a #GtkCellRenderer to clear the attribute mapping on Returns the underlying #GtkCellArea which might be @cell_layout if called on a #GtkCellArea or might be %NULL if no #GtkCellArea is used by @cell_layout. the cell area used by @cell_layout, or %NULL in case no cell area is used. a #GtkCellLayout Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a #GtkCellLayout Adds the @cell to the end of @cell_layout. 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. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. 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. a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a #GtkCellLayout a #GtkCellRenderer to reorder new position to insert @cell at Sets the attributes in list as the attributes of @cell_layout. The attributes should be in attribute/column order, as in gtk_cell_layout_add_attribute(). All existing attributes are removed, and replaced with the new attributes. a #GtkCellLayout a #GtkCellRenderer a %NULL-terminated list of attributes Sets the #GtkCellLayoutDataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a #GtkCellLayout a #GtkCellRenderer the #GtkCellLayoutDataFunc to use, or %NULL user data for @func destroy notify for @func_data A function which should set the value of @cell_layout’s cell renderer(s) as appropriate. a #GtkCellLayout the cell renderer whose value is to be set the model a #GtkTreeIter indicating the row to set the value for user data passed to gtk_cell_layout_set_cell_data_func() a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout a #GtkCellLayout a #GtkCellRenderer %TRUE if @cell is to be given extra space allocated to @cell_layout a #GtkCellLayout a #GtkCellLayout a #GtkCellRenderer an attribute on the renderer the column position on the model to get the attribute from a #GtkCellLayout a #GtkCellRenderer the #GtkCellLayoutDataFunc to use, or %NULL user data for @func destroy notify for @func_data a #GtkCellLayout a #GtkCellRenderer to clear the attribute mapping on a #GtkCellLayout a #GtkCellRenderer to reorder new position to insert @cell at a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a #GtkCellLayout the cell area used by @cell_layout, or %NULL in case no cell area is used. a #GtkCellLayout The #GtkCellRenderer is a base class of a set of objects used for rendering a cell to a #cairo_t. These objects are used primarily by the #GtkTreeView widget, though they aren’t tied to them in any specific way. It is worth noting that #GtkCellRenderer is not a #GtkWidget and cannot be treated as such. The primary use of a #GtkCellRenderer is for drawing a certain graphical elements on a #cairo_t. 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 gtk_cell_renderer_get_size(). Finally, the cell is rendered in the correct location using gtk_cell_renderer_render(). There are a number of rules that must be followed when writing a new #GtkCellRenderer. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a #GtkStyle change. The #GtkCellRenderer 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 #GtkCellRendererToggle, which toggles when it gets activated by a mouse click, or it can be “editable” like #GtkCellRendererText, which allows the user to edit the text using a widget implementing the #GtkCellEditable interface, e.g. #GtkEntry. To make a cell renderer activatable or editable, you have to implement the #GtkCellRendererClass.activate or #GtkCellRendererClass.start_editing virtual functions, respectively. Many properties of #GtkCellRenderer 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. Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, #GtkCellRendererToggle toggles when it gets a mouse click. %TRUE if the event was consumed/handled a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would acually be used to render. Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by this renderer. a #GtkCellRenderer instance Obtains the width and height needed to render the cell. Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_render(). If @cell_area is not %NULL, fills in the x and y offsets (if set) of the cell relative to this location. Please note that the values set in @width and @height, as well as those in @x_offset and @y_offset are inclusive of the xpad and ypad properties. Use gtk_cell_renderer_get_preferred_size() instead. a #GtkCellRenderer the widget the renderer is rendering to The area a cell will be allocated, or %NULL location to return x offset of cell relative to @cell_area, or %NULL location to return y offset of cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Invokes the virtual render function of the #GtkCellRenderer. 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 #GtkCellRenderer 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. a #GtkCellRenderer a cairo context to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Starts editing the contents of this @cell, through a new #GtkCellEditable widget created by the #GtkCellRendererClass.start_editing virtual function. A new #GtkCellEditable for editing this @cell, or %NULL if editing is not possible a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, #GtkCellRendererToggle toggles when it gets a mouse click. %TRUE if the event was consumed/handled a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would acually be used to render. Fills in @xalign and @yalign with the appropriate values of @cell. A #GtkCellRenderer location to fill in with the x alignment of the cell, or %NULL location to fill in with the y alignment of the cell, or %NULL Fills in @width and @height with the appropriate size of @cell. A #GtkCellRenderer location to fill in with the fixed width of the cell, or %NULL location to fill in with the fixed height of the cell, or %NULL Fills in @xpad and @ypad with the appropriate values of @cell. A #GtkCellRenderer location to fill in with the x padding of the cell, or %NULL location to fill in with the y padding of the cell, or %NULL Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location for storing the minimum size, or %NULL location for storing the natural size, or %NULL Retreives a renderer’s natural size when rendered to @widget. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL Retreives a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The #GtkSizeRequestMode preferred by this renderer. a #GtkCellRenderer instance Returns the cell renderer’s sensitivity. %TRUE if the cell renderer is sensitive A #GtkCellRenderer Obtains the width and height needed to render the cell. Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_render(). If @cell_area is not %NULL, fills in the x and y offsets (if set) of the cell relative to this location. Please note that the values set in @width and @height, as well as those in @x_offset and @y_offset are inclusive of the xpad and ypad properties. Use gtk_cell_renderer_get_preferred_size() instead. a #GtkCellRenderer the widget the renderer is rendering to The area a cell will be allocated, or %NULL location to return x offset of cell relative to @cell_area, or %NULL location to return y offset of cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Translates the cell renderer state to #GtkStateFlags, based on the cell renderer and widget sensitivity, and the given #GtkCellRendererState. the widget state flags applying to @cell a #GtkCellRenderer, or %NULL a #GtkWidget, or %NULL cell renderer state Returns the cell renderer’s visibility. %TRUE if the cell renderer is visible A #GtkCellRenderer Checks whether the cell renderer can do something when activated. %TRUE if the cell renderer can do anything when activated A #GtkCellRenderer Invokes the virtual render function of the #GtkCellRenderer. 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 #GtkCellRenderer 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. a #GtkCellRenderer a cairo context to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Sets the renderer’s alignment within its available space. A #GtkCellRenderer the x alignment of the cell renderer the y alignment of the cell renderer Sets the renderer size to be explicit, independent of the properties set. A #GtkCellRenderer the width of the cell renderer, or -1 the height of the cell renderer, or -1 Sets the renderer’s padding. A #GtkCellRenderer the x padding of the cell renderer the y padding of the cell renderer Sets the cell renderer’s sensitivity. A #GtkCellRenderer the sensitivity of the cell Sets the cell renderer’s visibility. A #GtkCellRenderer the visibility of the cell Starts editing the contents of this @cell, through a new #GtkCellEditable widget created by the #GtkCellRendererClass.start_editing virtual function. A new #GtkCellEditable for editing this @cell, or %NULL if editing is not possible a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Informs the cell renderer that the editing is stopped. If @canceled is %TRUE, the cell renderer will emit the #GtkCellRenderer::editing-canceled signal. This function should be called by cell renderer implementations in response to the #GtkCellEditable::editing-done signal of #GtkCellEditable. A #GtkCellRenderer %TRUE if the editing has been canceled Cell background as a #GdkColor Use #GtkCellRenderer:cell-background-rgba instead. Cell background as a #GdkRGBA 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: gtk_cell_renderer_stop_editing(). 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 #GtkEntryCompletion or setting up additional columns in a #GtkComboBox. See gtk_cell_editable_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: |[<!-- language="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); } } ]| the #GtkCellEditable the path identifying the edited cell #GtkCellRendererAccel 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 #GtkCellRendererAccel cell renderer was added in GTK+ 2.10. Creates a new #GtkCellRendererAccel. the new cell renderer The keyval of the accelerator. 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 %GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP then bare modifiers can be set as accelerators by tapping (ie: pressing and immediately releasing) them. The modifier mask of the accelerator. 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. Gets emitted when the user has removed the accelerator. the path identifying the row of the edited cell Gets emitted when the user has selected a new accelerator. the path identifying the row of the edited cell the new accelerator keyval the new acclerator modifier mask the keycode of the new accelerator 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. GTK+ accelerators mode Other accelerator mode GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP: Bare modifiers mode The #GtkSizeRequestMode preferred by this renderer. a #GtkCellRenderer instance a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to location to store the minimum size, or %NULL location to store the natural size, or %NULL a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to the size which is available for allocation location for storing the minimum size, or %NULL location for storing the preferred size, or %NULL a #GtkCellRenderer instance the #GtkWidget this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would acually be used to render. a #GtkCellRenderer the widget the renderer is rendering to The area a cell will be allocated, or %NULL location to return x offset of cell relative to @cell_area, or %NULL location to return y offset of cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL a #GtkCellRenderer a cairo context to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering %TRUE if the event was consumed/handled a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags A new #GtkCellEditable for editing this @cell, or %NULL if editing is not possible a #GtkCellRenderer a #GdkEvent widget that received the event widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Sets the type to be used for creating accessibles for cells rendered by cell renderers of @renderer_class. Note that multiple accessibles will be created. This function should only be called from class init functions of cell renderers. class to set the accessible type for The object type that implements the accessible for @widget_class. The type must be a subtype of #GtkRendererCellAccessible #GtkCellRendererCombo renders text in a cell like #GtkCellRendererText from which it is derived. But while #GtkCellRendererText offers a simple entry to edit the text, #GtkCellRendererCombo offers a #GtkComboBox widget to edit the text. The values to display in the combo box are taken from the tree model specified in the #GtkCellRendererCombo: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 #GtkCellRendererCombo:text-column property. Further properties of the combo box can be set in a handler for the #GtkCellRenderer::editing-started signal. The #GtkCellRendererCombo cell renderer was added in GTK+ 2.6. Creates a new #GtkCellRendererCombo. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. 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 #GtkTreeView. the new cell renderer If %TRUE, the cell renderer will include an entry and allow to enter values other than the ones in the popup list. Holds a tree model containing the possible values for the combo box. Use the text_column property to specify the column holding the values. 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. #GtkCellRendererCombo automatically adds a text cell renderer for this column to its combo box. 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 GtkComboBox, GtkCellRendererCombo::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 GtkTreeModel set via the model property on GtkCellRendererCombo. 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. a string of the path identifying the edited cell (relative to the tree view model) the new iter selected in the combo box (relative to the combo box model) Identifies how the user can interact with a particular cell. 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. The cell can be clicked. The cell can be edited or otherwise modified. A #GtkCellRendererPixbuf can be used to render an image in a cell. It allows to render either a given #GdkPixbuf (set via the #GtkCellRendererPixbuf:pixbuf property) or a named icon (set via the #GtkCellRendererPixbuf:icon-name property). To support the tree view, #GtkCellRendererPixbuf also supports rendering two alternative pixbufs, when the #GtkCellRenderer:is-expander property is %TRUE. If the #GtkCellRenderer:is-expanded property is %TRUE and the #GtkCellRendererPixbuf:pixbuf-expander-open property is set to a pixbuf, it renders that pixbuf, if the #GtkCellRenderer:is-expanded property is %FALSE and the #GtkCellRendererPixbuf:pixbuf-expander-closed property is set to a pixbuf, it renders that one. Creates a new #GtkCellRendererPixbuf. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. 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 #GtkTreeView. the new cell renderer Specifies whether the rendered pixbuf should be colorized according to the #GtkCellRendererState. Cell renderers always follow state. The GIcon representing the icon to display. If the icon theme is changed, the image will be updated automatically. The name of the themed icon to display. This property only has an effect if not overridden by "stock_id" or "pixbuf" properties. Use #GtkCellRendererPixbuf:icon-name instead. The #GtkIconSize value that specifies the size of the rendered icon. #GtkCellRendererProgress renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar. The #GtkCellRendererProgress cell renderer was added in GTK+ 2.6. Creates a new #GtkCellRendererProgress. the new cell renderer 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. The "text" property determines the label which will be drawn over the progress bar. Setting this property to %NULL causes the default label to be displayed. Setting this property to an empty string causes no label to be displayed. 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. The "text-yalign" property controls the vertical alignment of the text in the progress bar. Valid values range from 0 (top) to 1 (bottom). The "value" property determines the percentage to which the progress bar will be "filled in". #GtkCellRendererSpin renders text in a cell like #GtkCellRendererText from which it is derived. But while #GtkCellRendererText offers a simple entry to edit the text, #GtkCellRendererSpin offers a #GtkSpinButton 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. #GtkCellRendererSpin also has properties for the #GtkCellRendererSpin:climb-rate and the number of #GtkCellRendererSpin:digits to display. Other #GtkSpinButton properties can be set in a handler for the #GtkCellRenderer::editing-started signal. The #GtkCellRendererSpin cell renderer was added in GTK+ 2.10. Creates a new #GtkCellRendererSpin. a new #GtkCellRendererSpin The adjustment that holds the value of the spinbutton. This must be non-%NULL for the cell renderer to be editable. The acceleration rate when you hold down a button. The number of decimal places to display. GtkCellRendererSpinner renders a spinning animation in a cell, very similar to #GtkSpinner. It can often be used as an alternative to a #GtkCellRendererProgress for displaying indefinite activity, instead of actual progress. To start the animation in a cell, set the #GtkCellRendererSpinner:active property to %TRUE and increment the #GtkCellRendererSpinner: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. gtk_tree_view_column_add_attribute(). Returns a new cell renderer which will show a spinner to indicate activity. a new #GtkCellRenderer 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 #GtkSpinner widget draws one full cycle of the animation, consisting of 12 frames, in 750 milliseconds. The #GtkIconSize value that specifies the size of the rendered spinner. Tells how a cell is to be rendered. The cell is currently selected, and probably has a selection colored background to render to. The mouse is hovering over the cell. The cell is drawn in an insensitive manner The cell is in a sorted row The cell is in the focus row. The cell is in a row that can be expanded. Since 3.4 The cell is in a row that is expanded. Since 3.4 A #GtkCellRendererText 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 #GtkCellRendererText:ellipsize property allows it. If the #GtkCellRenderer:mode is %GTK_CELL_RENDERER_MODE_EDITABLE, the #GtkCellRendererText allows to edit its text using an entry. Creates a new #GtkCellRendererText. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. 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 #GtkTreeView the new cell renderer 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. A #GtkCellRendererText Number of rows of text each cell renderer is allocated, or -1 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 #GtkCellRenderer, on the other hand, sets the horizontal alignment of the whole text. Background color as a #GdkColor Use #GtkCellRendererText:background-rgba instead. Background color as a #GdkRGBA 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_ELLIPSIZE_NONE turns off ellipsizing. See the wrap-width property for another way of making the text fit into a given width. Foreground color as a #GdkColor Use #GtkCellRendererText:foreground-rgba instead. Foreground color as a #GdkRGBA 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 #GtkCellLayout and all of the cell's siblings have received their natural width. The text that will be displayed in the #GtkCellRenderer if #GtkCellRendererText:editable is %TRUE and the cell is empty. Since 3.6 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. 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. 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. 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. the path identifying the edited cell the new text #GtkCellRendererToggle renders a toggle button in a cell. The button is drawn as a radio or a checkbutton, depending on the #GtkCellRendererToggle:radio property. When activated, it emits the #GtkCellRendererToggle::toggled signal. Creates a new #GtkCellRendererToggle. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with #GtkTreeViewColumn, you can bind a property to a value in a #GtkTreeModel. 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. the new cell renderer Returns whether the cell renderer is activatable. See gtk_cell_renderer_toggle_set_activatable(). %TRUE if the cell renderer is activatable. a #GtkCellRendererToggle Returns whether the cell renderer is active. See gtk_cell_renderer_toggle_set_active(). %TRUE if the cell renderer is active. a #GtkCellRendererToggle Returns whether we’re rendering radio toggles rather than checkboxes. %TRUE if we’re rendering radio toggles rather than checkboxes a #GtkCellRendererToggle Makes the cell renderer activatable. a #GtkCellRendererToggle. the value to set. Activates or deactivates a cell renderer. a #GtkCellRendererToggle. the value to set. 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 #GtkTreeView, you set up a per-row setting using #GtkTreeViewColumn to associate model columns with cell renderer properties). a #GtkCellRendererToggle %TRUE to make the toggle look like a radio button 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. string representation of #GtkTreePath describing the event location A #GtkCellView displays a single row of a #GtkTreeModel using a #GtkCellArea and #GtkCellAreaContext. A #GtkCellAreaContext can be provided to the #GtkCellView 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 #GtkComboBox). #GtkCellView is #GtkOrientable in order to decide in which orientation the underlying #GtkCellAreaContext should be allocated. Taking the #GtkComboBox 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 GtkCellView has a single CSS node with name cellview. Creates a new #GtkCellView widget. A newly created #GtkCellView widget. Creates a new #GtkCellView widget with a specific #GtkCellArea to layout cells and a specific #GtkCellAreaContext. 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. A newly created #GtkCellView widget. the #GtkCellArea to layout cells the #GtkCellAreaContext in which to calculate cell geometry Creates a new #GtkCellView widget, adds a #GtkCellRendererText to it, and makes it show @markup. The text can be marked up with the [Pango text markup language][PangoMarkupFormat]. A newly created #GtkCellView widget. the text to display in the cell view Creates a new #GtkCellView widget, adds a #GtkCellRendererPixbuf to it, and makes it show @pixbuf. A newly created #GtkCellView widget. the image to display in the cell view Creates a new #GtkCellView widget, adds a #GtkCellRendererText to it, and makes it show @text. A newly created #GtkCellView widget. the text to display in the cell view Returns a #GtkTreePath referring to the currently displayed row. If no row is currently displayed, %NULL is returned. the currently displayed row or %NULL a #GtkCellView Gets whether @cell_view is configured to draw all of its cells in a sensitive state. whether @cell_view draws all of its cells in a sensitive state a #GtkCellView Gets whether @cell_view is configured to request space to fit the entire #GtkTreeModel. whether @cell_view requests space to fit the entire #GtkTreeModel. a #GtkCellView Returns the model for @cell_view. If no model is used %NULL is returned. a #GtkTreeModel used or %NULL a #GtkCellView Sets @requisition to the size needed by @cell_view to display the model row pointed to by @path. Combo box formerly used this to calculate the sizes for cellviews, now you can achieve this by either using the #GtkCellView:fit-model property or by setting the currently displayed row of the #GtkCellView and using gtk_widget_get_preferred_size(). %TRUE a #GtkCellView a #GtkTreePath return location for the size Sets the background color of @view. Use gtk_cell_view_set_background_rgba() instead. a #GtkCellView the new background color Sets the background color of @cell_view. a #GtkCellView the new background color Sets the row of the model that is currently displayed by the #GtkCellView. 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 #GtkCellView becomes temporarily empty. a #GtkCellView a #GtkTreePath or %NULL to unset. Sets whether @cell_view should draw all of its cells in a sensitive state, this is used by #GtkComboBox menus to ensure that rows with insensitive cells that contain children appear sensitive in the parent menu item. a #GtkCellView whether to draw all cells in a sensitive state. Sets whether @cell_view should request space to fit the entire #GtkTreeModel. This is used by #GtkComboBox to ensure that the cell view displayed on the combo box’s button always gets enough space and does not resize when selection changes. a #GtkCellView whether @cell_view should request space for the whole model. Sets the model for @cell_view. If @cell_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. a #GtkCellView a #GtkTreeModel The background color as a #GdkColor Use #GtkCellView:background-rgba instead. The background color as a #GdkRGBA The #GtkCellArea rendering cells If no area is specified when creating the cell view with gtk_cell_view_new_with_context() a horizontally oriented #GtkCellAreaBox will be used. since 3.0 The #GtkCellAreaContext 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. #GtkComboBox 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 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 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 The model for cell view since 2.10 The parent class. A #GtkCheckButton places a discrete #GtkToggleButton next to a widget, (usually a #GtkLabel). See the section on #GtkToggleButton widgets for more information about toggle/check buttons. The important signal ( #GtkToggleButton::toggled ) is also inherited from #GtkToggleButton. # CSS nodes |[<!-- language="plain" --> checkbutton ├── check ╰── <child> ]| A GtkCheckButton with indicator (see gtk_toggle_button_set_mode()) has a main CSS node with name checkbutton and a subnode with name check. |[<!-- language="plain" --> button.check ├── check ╰── <child> ]| A GtkCheckButton 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. Creates a new #GtkCheckButton. a #GtkWidget. Creates a new #GtkCheckButton with a #GtkLabel to the right of it. a #GtkWidget. the text for the check button. Creates a new #GtkCheckButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the check button. a new #GtkCheckButton The text of the button, with an underscore in front of the mnemonic character A #GtkCheckMenuItem is a menu item that maintains the state of a boolean value in addition to a #GtkMenuItem usual role in activating application code. A check box indicating the state of the boolean value is displayed at the left side of the #GtkMenuItem. Activating the #GtkMenuItem toggles the value. # CSS nodes |[<!-- language="plain" --> menuitem ├── check.left ╰── <child> ]| GtkCheckMenuItem has a main CSS node with name menuitem, and a subnode with name check, which gets the .left or .right style class. Creates a new #GtkCheckMenuItem. a new #GtkCheckMenuItem. Creates a new #GtkCheckMenuItem with a label. a new #GtkCheckMenuItem. the string to use for the label. Creates a new #GtkCheckMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. a new #GtkCheckMenuItem The text of the button, with an underscore in front of the character Emits the #GtkCheckMenuItem::toggled signal. a #GtkCheckMenuItem. Returns whether the check menu item is active. See gtk_check_menu_item_set_active (). %TRUE if the menu item is checked. a #GtkCheckMenuItem Returns whether @check_menu_item looks like a #GtkRadioMenuItem Whether @check_menu_item looks like a #GtkRadioMenuItem a #GtkCheckMenuItem Retrieves the value set by gtk_check_menu_item_set_inconsistent(). %TRUE if inconsistent a #GtkCheckMenuItem Sets the active state of the menu item’s check box. a #GtkCheckMenuItem. boolean value indicating whether the check box is active. Sets whether @check_menu_item is drawn like a #GtkRadioMenuItem a #GtkCheckMenuItem whether @check_menu_item is drawn like a #GtkRadioMenuItem 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, gtk_check_menu_item_set_inconsistent() only affects visual appearance, it doesn’t affect the semantics of the widget. a #GtkCheckMenuItem %TRUE to display an “inconsistent” third state check Emits the #GtkCheckMenuItem::toggled signal. a #GtkCheckMenuItem. This signal is emitted when the state of the check box is changed. A signal handler can use gtk_check_menu_item_get_active() to discover the new state. The parent class. a #GtkCheckMenuItem. The #GtkClipboard 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 #GdkAtom. (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 gtk_clipboard_set_text()), or you can supply a callback to be called at a later time when the data is needed (via gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().) Providing a callback also avoids having to make copies of the data when it is not needed. gtk_clipboard_set_with_data() and gtk_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 (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 gtk_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, gtk_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 gtk_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, gtk_clipboard_request_text() and gtk_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+.) Returns the clipboard object for the given selection. See gtk_clipboard_get_for_display() for complete details. 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. a #GdkAtom which identifies the clipboard to use Returns the default clipboard object for use with cut/copy/paste menu items and keyboard shortcuts. the default clipboard object. the #GdkDisplay for which the clipboard is to be retrieved. 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”. 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. the #GdkDisplay for which the clipboard is to be retrieved or created. a #GdkAtom which identifies the clipboard to use. Clears the contents of the clipboard. Generally this should only be called between the time you call gtk_clipboard_set_with_owner() or gtk_clipboard_set_with_data(), and when the @clear_func you supplied is called. Otherwise, the clipboard may be owned by someone else. a #GtkClipboard Gets the #GdkDisplay associated with @clipboard the #GdkDisplay associated with @clipboard a #GtkClipboard If the clipboard contents callbacks were set with gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or gtk_clipboard_clear() has not subsequently called, returns the owner set by gtk_clipboard_set_with_owner(). the owner of the clipboard, if any; otherwise %NULL. a #GtkClipboard Gets the selection that this clipboard is for. the selection a #GtkClipboard Requests the contents of clipboard as the given target. When the results of the result are later received the supplied callback will be called. a #GtkClipboard an atom representing the form into which the clipboard owner should convert the selection. 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 to pass to @callback Requests the contents of the clipboard as image. When the image is later received, it will be converted to a #GdkPixbuf, and @callback will be called. The @pixbuf parameter to @callback will contain the resulting #GdkPixbuf if the request succeeded, or %NULL 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. a #GtkClipboard 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 to pass to @callback. 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 %NULL 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. a #GtkClipboard a #GtkTextBuffer 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 to pass to @callback. 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 %NULL if it failed. a #GtkClipboard 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 to pass to @callback. 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 %NULL 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. a #GtkClipboard 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 to pass to @callback. 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 %NULL 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. a #GtkClipboard 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 to pass to @callback. 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. a #GtkClipboard array containing information about which forms should be stored or %NULL to indicate that all forms should be stored. number of elements in @targets Sets the contents of the clipboard to the given #GdkPixbuf. GTK+ will take responsibility for responding for requests for the image, and for converting the image into the requested format. a #GtkClipboard object a #GdkPixbuf 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. a #GtkClipboard object a UTF-8 string. length of @text, in bytes, or -1, in which case the length will be determined with strlen(). 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. %TRUE if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored. a #GtkClipboard array containing information about the available forms for the clipboard data number of elements in @targets function to call to get the actual clipboard data when the clipboard contents are set again, this function will be called, and @get_func will not be subsequently called. user data to pass to @get_func and @clear_func. 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 gtk_clipboard_set_with_data() is that instead of an generic @user_data pointer, a #GObject is passed in. %TRUE if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored. a #GtkClipboard array containing information about the available forms for the clipboard data number of elements in @targets function to call to get the actual clipboard data when the clipboard contents are set again, this function will be called, and @get_func will not be subsequently called an object that “owns” the data. This object will be passed to the callbacks when called Stores the current clipboard data somewhere so that it will stay around after the application has quit. a #GtkClipboard 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. a newly-allocated #GtkSelectionData object or %NULL if retrieving the given target failed. If non-%NULL, this value must be freed with gtk_selection_data_free() when you are finished with it. a #GtkClipboard an atom representing the form into which the clipboard owner should convert the selection. Requests the contents of the clipboard as image and converts the result to a #GdkPixbuf. This function waits for the data to be received using the main loop, so events, timeouts, etc, may be dispatched during the wait. a newly-allocated #GdkPixbuf object which must be disposed with g_object_unref(), or %NULL 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.) a #GtkClipboard 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. a newly-allocated binary block of data which must be freed with g_free(), or %NULL 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.) a #GtkClipboard a #GtkTextBuffer return location for the format of the returned data return location for the length of the returned data Returns a list of targets that are present on the clipboard, or %NULL 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. %TRUE if any targets are present on the clipboard, otherwise %FALSE. a #GtkClipboard location to store an array of targets. The result stored here must be freed with g_free(). location to store number of items in @targets. 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. a newly-allocated UTF-8 string which must be freed with g_free(), or %NULL 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.) a #GtkClipboard 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. a newly-allocated %NULL-terminated array of strings which must be freed with g_strfreev(), or %NULL 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.) a #GtkClipboard 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 gtk_clipboard_wait_for_image() since it doesn’t need to retrieve the actual image data. %TRUE is there is an image available, %FALSE otherwise. a #GtkClipboard 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 gtk_clipboard_wait_for_rich_text() since it doesn’t need to retrieve the actual text. %TRUE is there is rich text available, %FALSE otherwise. a #GtkClipboard a #GtkTextBuffer 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. %TRUE if the target is available, %FALSE otherwise. a #GtkClipboard A #GdkAtom indicating which target to look for. 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 gtk_clipboard_wait_for_text() since it doesn’t need to retrieve the actual text. %TRUE is there is text available, %FALSE otherwise. a #GtkClipboard 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 gtk_clipboard_wait_for_uris() since it doesn’t need to retrieve the actual URI data. %TRUE is there is an URI list available, %FALSE otherwise. a #GtkClipboard The ::owner-change signal is emitted when GTK+ receives an event that indicates that the ownership of the selection associated with @clipboard has changed. the @GdkEventOwnerChange event A function that will be called when the contents of the clipboard are changed or cleared. Once this has called, the @user_data_or_owner argument will not be used again. the #GtkClipboard the @user_data argument passed to gtk_clipboard_set_with_data(), or the @owner argument passed to gtk_clipboard_set_with_owner() A function that will be called to provide the contents of the selection. If multiple types of data were advertised, the requested type can be determined from the @info parameter or by checking the target field of @selection_data. If the data could successfully be converted into then it should be stored into the @selection_data object by calling gtk_selection_data_set() (or related functions such as gtk_selection_data_set_text()). If no data is set, the requestor will be informed that the attempt to get the data failed. the #GtkClipboard a #GtkSelectionData argument in which the requested data should be stored. the info field corresponding to the requested target from the #GtkTargetEntry array passed to gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner(). the @user_data argument passed to gtk_clipboard_set_with_data(), or the @owner argument passed to gtk_clipboard_set_with_owner() A function to be called when the results of gtk_clipboard_request_image() are received, or when the request fails. the #GtkClipboard the received image the @user_data supplied to gtk_clipboard_request_image(). A function to be called when the results of gtk_clipboard_request_contents() are received, or when the request fails. the #GtkClipboard a #GtkSelectionData containing the data was received. If retrieving the data failed, then then length field of @selection_data will be negative. the @user_data supplied to gtk_clipboard_request_contents(). A function to be called when the results of gtk_clipboard_request_rich_text() are received, or when the request fails. the #GtkClipboard The format of the rich text the rich text received, as a UTF-8 encoded string, or %NULL if retrieving the data failed. Length of the text. the @user_data supplied to gtk_clipboard_request_rich_text(). A function to be called when the results of gtk_clipboard_request_targets() are received, or when the request fails. the #GtkClipboard the supported targets, as array of #GdkAtom, or %NULL if retrieving the data failed. the length of the @atoms array. the @user_data supplied to gtk_clipboard_request_targets(). A function to be called when the results of gtk_clipboard_request_text() are received, or when the request fails. the #GtkClipboard the text received, as a UTF-8 encoded string, or %NULL if retrieving the data failed. the @user_data supplied to gtk_clipboard_request_text(). A function to be called when the results of gtk_clipboard_request_uris() are received, or when the request fails. the #GtkClipboard the received URIs the @user_data supplied to gtk_clipboard_request_uris(). The #GtkColorButton 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 GtkColorButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .color style class. 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. a new color button Creates a new color button. Use gtk_color_button_new_with_rgba() instead. a new color button A #GdkColor to set the current color with Creates a new color button. a new color button A #GdkRGBA to set the current color with Returns the current alpha value. Use gtk_color_chooser_get_rgba() instead. an integer between 0 and 65535 a #GtkColorButton Sets @color to be the current color in the #GtkColorButton widget. Use gtk_color_chooser_get_rgba() instead. a #GtkColorButton a #GdkColor to fill in with the current color Sets @rgba to be the current color in the #GtkColorButton widget. Use gtk_color_chooser_get_rgba() instead. a #GtkColorButton a #GdkRGBA to fill in with the current color Gets the title of the color selection dialog. An internal string, do not free the return value a #GtkColorButton Does the color selection dialog use the alpha channel ? Use gtk_color_chooser_get_use_alpha() instead. %TRUE if the color sample uses alpha channel, %FALSE if not a #GtkColorButton Sets the current opacity to be @alpha. Use gtk_color_chooser_set_rgba() instead. a #GtkColorButton an integer between 0 and 65535 Sets the current color to be @color. Use gtk_color_chooser_set_rgba() instead. a #GtkColorButton A #GdkColor to set the current color with Sets the current color to be @rgba. Use gtk_color_chooser_set_rgba() instead. a #GtkColorButton a #GdkRGBA to set the current color with Sets the title for the color selection dialog. a #GtkColorButton String containing new window title Sets whether or not the color button should use the alpha channel. Use gtk_color_chooser_set_use_alpha() instead. a #GtkColorButton %TRUE if color button should use alpha channel, %FALSE if not The selected opacity value (0 fully transparent, 65535 fully opaque). The selected color. Use #GtkColorButton:rgba instead. The RGBA color. 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. The title of the color selection dialog 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. The ::color-set signal is emitted when the user selects a color. When handling this signal, use gtk_color_button_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. #GtkColorChooser 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 #GtkColorChooserWidget, #GtkColorChooserDialog and #GtkColorButton. 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 #GtkColorChooserWidget 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 %NULL, removes all previously added palettes. a #GtkColorChooser %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette, or %NULL Gets the currently-selected color. a #GtkColorChooser a #GdkRGBA to fill in with the current color Sets the color. a #GtkColorChooser the new color 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 #GtkColorChooserWidget 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 %NULL, removes all previously added palettes. a #GtkColorChooser %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette, or %NULL Gets the currently-selected color. a #GtkColorChooser a #GdkRGBA to fill in with the current color Returns whether the color chooser shows the alpha channel. %TRUE if the color chooser uses the alpha channel, %FALSE if not a #GtkColorChooser Sets the color. a #GtkColorChooser the new color Sets whether or not the color chooser should use the alpha channel. a #GtkColorChooser %TRUE if color chooser should use alpha channel, %FALSE if not The ::rgba property contains the currently selected color, as a #GdkRGBA struct. The property can be set to change the current selection programmatically. When ::use-alpha is %TRUE, colors may have alpha (translucency) information. When it is %FALSE, the #GdkRGBA struct obtained via the #GtkColorChooser: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). 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. the color The #GtkColorChooserDialog widget is a dialog for choosing a color. It implements the #GtkColorChooser interface. Creates a new #GtkColorChooserDialog. a new #GtkColorChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL a #GtkColorChooser a #GdkRGBA to fill in with the current color a #GtkColorChooser the new color a #GtkColorChooser %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette, or %NULL The #GtkColorChooserWidget 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 gtk_color_chooser_set_rgba(). To get the selected color use gtk_color_chooser_get_rgba(). The #GtkColorChooserWidget is used in the #GtkColorChooserDialog to provide a dialog for selecting colors. # CSS names GtkColorChooserWidget has a single CSS node with name colorchooser. Creates a new #GtkColorChooserWidget. a new #GtkColorChooserWidget 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. The parent class. Creates a new GtkColorSelection. a new #GtkColorSelection Parses a color palette string; the string is a colon-separated list of color names readable by gdk_color_parse(). %TRUE if a palette was successfully parsed a string encoding a color palette return location for allocated array of #GdkColor return location for length of array Encodes a palette as a string, useful for persistent storage. allocated string encoding the palette an array of colors length of the array Installs a global function to be called whenever the user tries to modify the palette in a color selection. This function should save the new palette contents, and update the #GtkSettings:gtk-color-palette GtkSettings property so all GtkColorSelection widgets will be modified. the previous change palette hook (that was replaced) a function to call when the custom palette needs saving Returns the current alpha value. an integer between 0 and 65535 a #GtkColorSelection Sets @color to be the current color in the GtkColorSelection widget. Use gtk_color_selection_get_current_rgba() instead. a #GtkColorSelection a #GdkColor to fill in with the current color Sets @rgba to be the current color in the GtkColorSelection widget. a #GtkColorSelection a #GdkRGBA to fill in with the current color Determines whether the colorsel has an opacity control. %TRUE if the @colorsel has an opacity control, %FALSE if it does't a #GtkColorSelection Determines whether the color selector has a color palette. %TRUE if the selector has a palette, %FALSE if it hasn't a #GtkColorSelection Returns the previous alpha value. an integer between 0 and 65535 a #GtkColorSelection Fills @color in with the original color value. Use gtk_color_selection_get_previous_rgba() instead. a #GtkColorSelection a #GdkColor to fill in with the original color value Fills @rgba in with the original color value. a #GtkColorSelection a #GdkRGBA to fill in with the original color value Gets the current state of the @colorsel. %TRUE if the user is currently dragging a color around, and %FALSE if the selection has stopped a #GtkColorSelection Sets the current opacity to be @alpha. The first time this is called, it will also set the original opacity to be @alpha too. a #GtkColorSelection an integer between 0 and 65535 Sets the current color to be @color. The first time this is called, it will also set the original color to be @color too. Use gtk_color_selection_set_current_rgba() instead. a #GtkColorSelection a #GdkColor to set the current color with Sets the current color to be @rgba. The first time this is called, it will also set the original color to be @rgba too. a #GtkColorSelection A #GdkRGBA to set the current color with Sets the @colorsel to use or not use opacity. a #GtkColorSelection %TRUE if @colorsel can set the opacity, %FALSE otherwise Shows and hides the palette based upon the value of @has_palette. a #GtkColorSelection %TRUE if palette is to be visible, %FALSE otherwise Sets the “previous” alpha to be @alpha. This function should be called with some hesitations, as it might seem confusing to have that alpha change. a #GtkColorSelection an integer between 0 and 65535 Sets the “previous” color to be @color. This function should be called with some hesitations, as it might seem confusing to have that color change. Calling gtk_color_selection_set_current_color() will also set this color the first time it is called. Use gtk_color_selection_set_previous_rgba() instead. a #GtkColorSelection a #GdkColor to set the previous color with Sets the “previous” color to be @rgba. This function should be called with some hesitations, as it might seem confusing to have that color change. Calling gtk_color_selection_set_current_rgba() will also set this color the first time it is called. a #GtkColorSelection a #GdkRGBA to set the previous color with The current GdkColor color. Use #GtkColorSelection:current-rgba instead. The current RGBA color. This signal is emitted when the color changes in the #GtkColorSelection according to its update policy. Array of colors Number of colors in the array Array of colors Number of colors in the array The parent class. Creates a new #GtkColorSelectionDialog. a #GtkColorSelectionDialog. a string containing the title text for the dialog. Retrieves the #GtkColorSelection widget embedded in the dialog. the embedded #GtkColorSelection a #GtkColorSelectionDialog A GtkComboBox is a widget that allows the user to choose from a list of valid choices. The GtkComboBox displays the selected choice. When activated, the GtkComboBox 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 GtkComboBox 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 GtkComboBox implements the #GtkCellLayout 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 GtkComboBox to contain a #GtkEntry. This entry can be accessed by calling gtk_bin_get_child() on the combo box. For a simple list of textual choices, the model-view API of GtkComboBox can be a bit overwhelming. In this case, #GtkComboBoxText offers a simple alternative. Both GtkComboBox and #GtkComboBoxText can contain an entry. # CSS nodes |[<!-- language="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. |[<!-- language="plain" --> combobox ├── box.linked │ ├── entry.combo │ ╰── button.combo │ ╰── box │ ╰── arrow ╰── window.popup ]| A GtkComboBox 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. Creates a new empty #GtkComboBox. A new #GtkComboBox. Creates a new empty #GtkComboBox using @area to layout cells. A new #GtkComboBox. the #GtkCellArea to use to layout cell renderers Creates a new empty #GtkComboBox with an entry. The new combo box will use @area to layout cells. A new #GtkComboBox. the #GtkCellArea to use to layout cell renderers Creates a new empty #GtkComboBox with an entry. A new #GtkComboBox. Creates a new #GtkComboBox with the model initialized to @model. A new #GtkComboBox. A #GtkTreeModel. Creates a new empty #GtkComboBox with an entry and with the model initialized to @model. A new #GtkComboBox A #GtkTreeModel 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 #GtkTreePath of the active item. An integer which is the index of the currently active item, or -1 if there’s no active item. A #GtkComboBox Returns the ID of the active row of @combo_box. This value is taken from the active row and the column specified by the #GtkComboBox:id-column property of @combo_box (see gtk_combo_box_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 #GtkComboBox:id-column property of @combo_box is not set, or if no row is active, or if the active row has a %NULL ID value, then %NULL is returned. the ID of the active row, or %NULL a #GtkComboBox Sets @iter to point to the currently active item, if any item is active. Otherwise, @iter is left unchanged. %TRUE if @iter was set, %FALSE otherwise A #GtkComboBox A #GtkTreeIter Gets the current value of the :add-tearoffs property. the current value of the :add-tearoffs property. a #GtkComboBox Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. %GTK_SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, %GTK_SENSITIVITY_OFF if the button is always insensitive or %GTK_SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to be selected. a #GtkComboBox Returns the column with column span information for @combo_box. the column span column. A #GtkComboBox Returns the column which @combo_box is using to get the strings from to display in the internal entry. A column in the data source model of @combo_box. A #GtkComboBox. Returns whether the combo box grabs focus when it is clicked with the mouse. See gtk_combo_box_set_focus_on_click(). Use gtk_widget_get_focus_on_click() instead %TRUE if the combo box grabs focus when it is clicked with the mouse. a #GtkComboBox Returns whether the combo box has an entry. whether there is an entry in @combo_box. a #GtkComboBox Returns the column which @combo_box is using to get string IDs for values from. A column in the data source model of @combo_box. A #GtkComboBox Returns the #GtkTreeModel which is acting as data source for @combo_box. A #GtkTreeModel which was passed during construction. A #GtkComboBox 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. the accessible object corresponding to the combo box’s popup. a #GtkComboBox Gets whether the popup uses a fixed width matching the allocated width of the combo box. %TRUE if the popup uses a fixed width a #GtkComboBox Returns the current row separator function. the current row separator function. a #GtkComboBox Returns the column with row span information for @combo_box. the row span column. A #GtkComboBox Gets the current title of the menu in tearoff mode. See gtk_combo_box_set_add_tearoffs(). the menu’s title in tearoff mode. This is an internal copy of the string which must not be freed. a #GtkComboBox 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. the wrap width. A #GtkComboBox Hides the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. a #GtkComboBox Pops up the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. Before calling this, @combo_box must be mapped, or nothing will happen. a #GtkComboBox Pops up the menu or dropdown list of @combo_box, the popup window will be grabbed so only @device and its associated pointer/keyboard are the only #GdkDevices able to send events to it. a #GtkComboBox a #GdkDevice Sets the active item of @combo_box to be the item at @index. A #GtkComboBox An index in the model passed during construction, or -1 to have no active item Changes the active row of @combo_box to the one that has an ID equal to @active_id, or unsets the active row if @active_id is %NULL. Rows having a %NULL ID string cannot be made active by this function. If the #GtkComboBox:id-column property of @combo_box is unset or if no row has the given ID then the function does nothing and returns %FALSE. %TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE. a #GtkComboBox the ID of the row to select, or %NULL Sets the current active item to be the one referenced by @iter, or unsets the active item if @iter is %NULL. A #GtkComboBox The #GtkTreeIter, or %NULL Sets whether the popup menu should have a tearoff menu item. a #GtkComboBox %TRUE to add tearoff menu items Sets whether the dropdown button of the combo box should be always sensitive (%GTK_SENSITIVITY_ON), never sensitive (%GTK_SENSITIVITY_OFF) or only if there is at least one item to display (%GTK_SENSITIVITY_AUTO). a #GtkComboBox specify the sensitivity of the dropdown button Sets the column with column span information for @combo_box to be @column_span. The column span column contains integers which indicate how many columns an item should span. A #GtkComboBox A column in the model passed during construction Sets the model column which @combo_box should use to get strings from to be @text_column. The column @text_column in the model of @combo_box must be of type %G_TYPE_STRING. This is only relevant if @combo_box has been created with #GtkComboBox:has-entry as %TRUE. A #GtkComboBox A column in @model to get the strings from for the internal entry 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. Use gtk_widget_set_focus_on_click() instead a #GtkComboBox whether the combo box grabs focus when clicked with the mouse Sets the model column which @combo_box should use to get string IDs for values from. The column @id_column in the model of @combo_box must be of type %G_TYPE_STRING. A #GtkComboBox A column in @model to get string IDs for values from Sets the model used by @combo_box to be @model. Will unset a previously set model (if applicable). If model is %NULL, then it will unset the model. Note that this function does not clear the cell renderers, you have to call gtk_cell_layout_clear() yourself if you need to set up different cell renderers for the new model. A #GtkComboBox A #GtkTreeModel Specifies whether the popup’s width should be a fixed width matching the allocated width of the combo box. a #GtkComboBox whether to use a fixed popup width 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 %NULL, no separators are drawn. This is the default value. a #GtkComboBox a #GtkTreeViewRowSeparatorFunc user data to pass to @func, or %NULL destroy notifier for @data, or %NULL Sets the column with row span information for @combo_box to be @row_span. The row span column contains integers which indicate how many rows an item should span. A #GtkComboBox. A column in the model passed during construction. Sets the menu’s title in tearoff mode. a #GtkComboBox a title for the menu in tearoff mode Sets the wrap width of @combo_box 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. A #GtkComboBox Preferred number of columns 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 #GtkTreePath of the active item. The value of the ID column of the active row. The add-tearoffs property controls whether generated menus have tearoff menu items. Note that this only affects menu style combo boxes. Whether the dropdown button is sensitive when the model is empty. The #GtkCellArea used to layout cell renderers for this combo box. If no area is specified when creating the combo box with gtk_combo_box_new_with_area() a horizontally oriented #GtkCellAreaBox will be used. 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 #GtkComboBox:wrap-width. The column in the combo box's model to associate with strings from the entry if the combo was created with #GtkComboBox:has-entry = %TRUE. Whether the combo box has an entry. The has-frame property controls whether a frame is drawn around the entry. The column in the combo box's model that provides string IDs for the values in the model, if != -1. The model from which the combo box takes the values shown in the list. Whether the popup's width should be a fixed width matching the allocated width of the combo box. 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. 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. A title that may be displayed by the window manager when the popup is torn-off. 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. 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 gtk_combo_box_set_active_iter(). It will also be emitted while typing into the entry of a combo box with an entry. For combo boxes that are created with an entry (See GtkComboBox: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 GtkComboBox::entry-text-column model column. Here's an example signal handler which fetches data from the model and displays it in the entry. |[<!-- language="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); } ]| a newly allocated string representing @path for the current GtkComboBox model. the GtkTreePath string from the combo box's current model to format text for The ::move-active signal is a [keybinding signal][GtkBindingSignal] which gets emitted to move the active selection. a #GtkScrollType The ::popdown signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popdown the combo box list. The default bindings for this signal are Alt+Up and Escape. The ::popup signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popup the combo box list. The default binding for this signal is Alt+Down. The parent class. A GtkComboBoxText is a simple variant of #GtkComboBox that hides the model-view complexity for simple text-only use cases. To create a GtkComboBoxText, use gtk_combo_box_text_new() or gtk_combo_box_text_new_with_entry(). You can add items to a GtkComboBoxText with gtk_combo_box_text_append_text(), gtk_combo_box_text_insert_text() or gtk_combo_box_text_prepend_text() and remove options with gtk_combo_box_text_remove(). If the GtkComboBoxText contains an entry (via the “has-entry” property), its contents can be retrieved using gtk_combo_box_text_get_active_text(). The entry itself can be accessed by calling gtk_bin_get_child() on the combo box. You should not call gtk_combo_box_set_model() or attempt to pack more cells into this combo box via its GtkCellLayout interface. # GtkComboBoxText as GtkBuildable The GtkComboBoxText implementation of the GtkBuildable 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 GtkComboBoxText items: |[ <object class="GtkComboBoxText"> <items> <item translatable="yes" id="factory">Factory</item> <item translatable="yes" id="home">Home</item> <item translatable="yes" id="subway">Subway</item> </items> </object> ]| # CSS nodes |[<!-- language="plain" --> combobox ╰── box.linked ├── entry.combo ├── button.combo ╰── window.popup ]| GtkComboBoxText 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. Creates a new #GtkComboBoxText, which is a #GtkComboBox just displaying strings. A new #GtkComboBoxText Creates a new #GtkComboBoxText, which is a #GtkComboBox just displaying strings. The combo box created by this function has an entry. a new #GtkComboBoxText Appends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling gtk_combo_box_text_insert() with a position of -1. A #GtkComboBoxText a string ID for this value, or %NULL A string Appends @text to the list of strings stored in @combo_box. This is the same as calling gtk_combo_box_text_insert_text() with a position of -1. A #GtkComboBoxText A string Returns the currently active string in @combo_box, or %NULL if none is selected. If @combo_box contains an entry, this function will return its contents (which will not necessarily be an item from the list). a newly allocated string containing the currently active text. Must be freed with g_free(). A #GtkComboBoxText Inserts @text at @position in the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. See #GtkComboBox:id-column. If @position is negative then @text is appended. A #GtkComboBoxText An index to insert @text a string ID for this value, or %NULL A string to display Inserts @text at @position in the list of strings stored in @combo_box. If @position is negative then @text is appended. This is the same as calling gtk_combo_box_text_insert() with a %NULL ID string. A #GtkComboBoxText An index to insert @text A string Prepends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling gtk_combo_box_text_insert() with a position of 0. A #GtkComboBox a string ID for this value, or %NULL a string Prepends @text to the list of strings stored in @combo_box. This is the same as calling gtk_combo_box_text_insert_text() with a position of 0. A #GtkComboBox A string Removes the string at @position from @combo_box. A #GtkComboBox Index of the item to remove Removes all the text entries from the combo box. A #GtkComboBoxText 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 #GtkWindow containing a #GtkFrame containing a #GtkLabel. If you wanted an image instead of a textual label inside the frame, you might replace the #GtkLabel widget with a #GtkImage widget. There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract GtkContainer base class. The first type of container widget has a single child widget and derives from #GtkBin. These containers are decorators, which add some kind of functionality to the child. For example, a #GtkButton makes its child into a clickable button; a #GtkFrame draws a frame around its child and a #GtkWindow 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 #GtkHBox arranges its children in a horizontal row, and a #GtkGrid arranges the widgets it contains in a two-dimensional grid. For implementations of #GtkContainer the virtual method #GtkContainerClass.forall() is always required, since it's used for drawing and other internal operations on the children. If the #GtkContainer implementation expect to have non internal children it's needed to implement both #GtkContainerClass.add() and #GtkContainerClass.remove(). If the GtkContainer implementation has internal children, they should be added with gtk_widget_set_parent() on init() and removed with gtk_widget_unparent() in the #GtkWidgetClass.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 #GtkSizeRequestMode that is %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. 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 gtk_widget_get_preferred_width() and then through gtk_widget_get_preferred_height_for_width(). When handling requests in the opposite #GtkSizeRequestMode it is important that every widget request at least enough space to display all of its content at all times. When gtk_widget_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: |[<!-- language="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 gtk_widget_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: |[<!-- language="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 gtk_widget_get_preferred_width() for each of its children. For each potential group of children that are lined up horizontally, the values returned by gtk_widget_get_preferred_width() should be collected in an array of #GtkRequestedSize 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 gtk_widget_get_preferred_height_for_width() and using the sizes stored in the #GtkRequestedSize 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 #GtkRequestedSize 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 #GtkRequestedSize 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 [GtkWidget’s geometry management section][geometry-management] to learn more about implementing height-for-width geometry management for widgets. # Child properties GtkContainer 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 #GtkBox. Use gtk_container_class_install_child_property() to install child properties for a container class and gtk_container_class_find_child_property() or gtk_container_class_list_child_properties() to get information about existing child properties. To set the value of a child property, use gtk_container_child_set_property(), gtk_container_child_set() or gtk_container_child_set_valist(). To obtain the value of a child property, use gtk_container_child_get_property(), gtk_container_child_get() or gtk_container_child_get_valist(). To emit notification about child property changes, use gtk_widget_child_notify(). # GtkContainer as GtkBuildable The GtkContainer implementation of the GtkBuildable 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: |[ <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> ]| Adds @widget to @container. Typically used for simple containers such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated layout containers such as #GtkBox or #GtkGrid, this function will pick default packing parameters that may not be correct. So consider functions such as gtk_box_pack_start() and gtk_grid_attach() as an alternative to gtk_container_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 #GtkScrolledWindow or #GtkListBox, may add intermediate children between the added widget and the container. a #GtkContainer a widget to be placed inside @container 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 #GtkPaned which already has two children. a #GType. a #GtkContainer Invokes @callback on each direct child of @container, 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 gtk_container_foreach(), rather than gtk_container_forall(). a #GtkContainer a callback callback user data Returns a newly created widget path representing all the widget hierarchy from the toplevel down to and including @child. A newly created #GtkWidgetPath a #GtkContainer a child of @container Removes @widget from @container. @widget must be inside @container. Note that @container 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 g_object_ref(). If you don’t want to use @widget again it’s usually more efficient to simply destroy it directly using gtk_widget_destroy() since this will remove it from the container and help break any circular reference count cycles. a #GtkContainer a current child of @container Sets, or unsets if @child is %NULL, the focused child of @container. This function emits the GtkContainer::set_focus_child signal of @container. Implementations of #GtkContainer 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 gtk_widget_grab_focus() to manually set the focus to a specific widget. a #GtkContainer a #GtkWidget, or %NULL Adds @widget to @container. Typically used for simple containers such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated layout containers such as #GtkBox or #GtkGrid, this function will pick default packing parameters that may not be correct. So consider functions such as gtk_box_pack_start() and gtk_grid_attach() as an alternative to gtk_container_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 #GtkScrolledWindow or #GtkListBox, may add intermediate children between the added widget and the container. a #GtkContainer a widget to be placed inside @container Adds @widget to @container, setting child properties at the same time. See gtk_container_add() and gtk_container_child_set() for more details. a #GtkContainer a widget to be placed inside @container the name of the first child property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Gets the values of one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets the value of a child property for @child and @container. a #GtkContainer a widget which is a child of @container the name of the property to get a location to return the value Gets the values of one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Emits a #GtkWidget::child-notify signal for the [child property][child-properties] @child_property on the child. This is an analogue of g_object_notify() for child properties. Also see gtk_widget_child_notify(). the #GtkContainer the child widget the name of a child property installed on the class of @container Emits a #GtkWidget::child-notify signal for the [child property][child-properties] specified by @pspec on the child. This is an analogue of g_object_notify_by_pspec() for child properties. the #GtkContainer the child widget the #GParamSpec of a child property instealled on the class of @container Sets one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Sets a child property for @child and @container. a #GtkContainer a widget which is a child of @container the name of the property to set the value to set the property to Sets one or more child properties for @child and @container. a #GtkContainer a widget which is a child of @container the name of the first property to set a %NULL-terminated list of property names and values, starting with @first_prop_name 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 #GtkPaned which already has two children. a #GType. a #GtkContainer Invokes @callback on each direct child of @container, 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 gtk_container_foreach(), rather than gtk_container_forall(). a #GtkContainer a callback callback user data Invokes @callback on each non-internal child of @container. See gtk_container_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 gtk_container_foreach(), rather than gtk_container_forall(). a #GtkContainer a callback callback user data Retrieves the border width of the container. See gtk_container_set_border_width(). the current border width a #GtkContainer Returns the container’s non-internal children. See gtk_container_forall() for details on what constitutes an "internal" child. a newly-allocated list of the container’s non-internal children. a #GtkContainer 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 %NULL in @focusable_widgets and returns %FALSE. For overriding focus behavior, use the GtkWidgetClass::focus signal. %TRUE if the focus chain of the container has been set explicitly. a #GtkContainer location to store the focus chain of the container, or %NULL. You should free this list using g_list_free() when you are done with it, however no additional reference count is added to the individual widgets in the focus chain. Returns the current focus child widget inside @container. This is not the currently focused widget. That can be obtained by calling gtk_window_get_focus(). The child widget which will receive the focus inside @container when the @container is focused, or %NULL if none is set. a #GtkContainer Retrieves the horizontal focus adjustment for the container. See gtk_container_set_focus_hadjustment (). the horizontal focus adjustment, or %NULL if none has been set. a #GtkContainer Retrieves the vertical focus adjustment for the container. See gtk_container_set_focus_vadjustment(). the vertical focus adjustment, or %NULL if none has been set. a #GtkContainer Returns a newly created widget path representing all the widget hierarchy from the toplevel down to and including @child. A newly created #GtkWidgetPath a #GtkContainer a child of @container Returns the resize mode for the container. See gtk_container_set_resize_mode (). Resize modes are deprecated. They aren’t necessary anymore since frame clocks and might introduce obscure bugs if used. the current resize mode a #GtkContainer When a container receives a call to the draw function, it must send synthetic #GtkWidget::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 #GtkWidget::draw function, calls gtk_container_propagate_draw() once for each child, passing in the @cr the container received. gtk_container_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 gtk_widget_draw() on the child directly. In most cases, a container can simply either inherit the #GtkWidget::draw implementation from #GtkContainer, or do some drawing and then chain to the ::draw implementation from #GtkContainer. a #GtkContainer a child of @container 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. Removes @widget from @container. @widget must be inside @container. Note that @container 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 g_object_ref(). If you don’t want to use @widget again it’s usually more efficient to simply destroy it directly using gtk_widget_destroy() since this will remove it from the container and help break any circular reference count cycles. a #GtkContainer a current child of @container a #GtkContainer 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 #GtkWindow; 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 #GtkWidget:margin property on the child widget, for example #GtkWidget:margin-top. a #GtkContainer amount of blank space to leave outside the container. Valid values are in the range 0-65535 pixels. 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. For overriding focus behavior, use the GtkWidgetClass::focus signal. a #GtkContainer the new focus chain Sets, or unsets if @child is %NULL, the focused child of @container. This function emits the GtkContainer::set_focus_child signal of @container. Implementations of #GtkContainer 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 gtk_widget_grab_focus() to manually set the focus to a specific widget. a #GtkContainer a #GtkWidget, or %NULL 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 gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment and gtk_container_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. a #GtkContainer an adjustment which should be adjusted when the focus is moved among the descendents of @container 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 gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment and gtk_container_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. a #GtkContainer an adjustment which should be adjusted when the focus is moved among the descendents of @container Sets the @reallocate_redraws flag of the container to the given value. Containers requesting reallocation redraws get automatically redrawn if any of their children changed allocation. Call gtk_widget_queue_draw() in your size_allocate handler. a #GtkContainer the new value for the container’s @reallocate_redraws flag Sets the resize mode for the container. The resize mode of a container determines whether a resize request will be passed to the container’s parent, queued for later execution or executed immediately. Resize modes are deprecated. They aren’t necessary anymore since frame clocks and might introduce obscure bugs if used. a #GtkContainer the new resize mode Removes a focus chain explicitly set with gtk_container_set_focus_chain(). For overriding focus behavior, use the GtkWidgetClass::focus signal. a #GtkContainer Get a list of children. the container Base class for containers. The parent class. a #GtkContainer a widget to be placed inside @container a #GtkContainer a current child of @container a #GtkContainer a callback callback user data a #GtkContainer a #GtkWidget, or %NULL a #GType. a #GtkContainer A newly created #GtkWidgetPath a #GtkContainer a child of @container Finds a child property of a container class by name. the #GParamSpec of the child property or %NULL if @class has no child property with that name. a #GtkContainerClass the name of the child property to find Modifies a subclass of #GtkContainerClass to automatically add and remove the border-width setting on GtkContainer. This allows the subclass to ignore the border width in its size request and allocate methods. The intent is for a subclass to invoke this in its class_init function. gtk_container_class_handle_border_width() is necessary because it would break API too badly to make this behavior the default. So subclasses must “opt in” to the parent class handling border_width for them. the class struct of a #GtkContainer subclass Installs child properties on a container class. a #GtkContainerClass the length of the #GParamSpec array the #GParamSpec array defining the new child properties Installs a child property on a container class. a #GtkContainerClass the id for the property the #GParamSpec for the property Returns all child properties of a container class. a newly allocated %NULL-terminated array of #GParamSpec*. The array must be freed with g_free(). a #GtkContainerClass location to return the number of child properties found Specifies which corner a child widget should be placed in when packed into a #GtkScrolledWindow. This is effectively the opposite of where the scroll bars are placed. Place the scrollbars on the right and bottom of the widget (default behaviour). Place the scrollbars on the top and right of the widget. Place the scrollbars on the left and bottom of the widget. Place the scrollbars on the top and left of the widget. GtkCssProvider is an object implementing the #GtkStyleProvider 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 gtk_css_provider_load_from_file() or gtk_css_provider_load_from_resource() and adding the provider with gtk_style_context_add_provider() or gtk_style_context_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 #GtkSettings: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 #GtkSettings:gtk-key-theme-name. Returns a newly created #GtkCssProvider. A new #GtkCssProvider Returns the provider containing the style settings used as a fallback for all widgets. Use gtk_css_provider_new() instead. The provider used for fallback styling. This memory is owned by GTK+, and you must not free it. Loads a theme from the usual theme paths a #GtkCssProvider with the theme loaded. This memory is owned by GTK+, and you must not free it. A theme name variant to load, for example, "dark", or %NULL for the default Loads @data into @css_provider, and by doing so clears any previously loaded information. %TRUE. The return value is deprecated and %FALSE will only be returned for backwards compatibility reasons if an @error is not %NULL and a loading error occurred. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider CSS data loaded in memory 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. Loads the data contained in @file into @css_provider, making it clear any previously loaded information. %TRUE. The return value is deprecated and %FALSE will only be returned for backwards compatibility reasons if an @error is not %NULL and a loading error occurred. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider #GFile pointing to a file to load Loads the data contained in @path into @css_provider, making it clear any previously loaded information. %TRUE. The return value is deprecated and %FALSE will only be returned for backwards compatibility reasons if an @error is not %NULL and a loading error occurred. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider the path of a filename to load, in the GLib filename encoding Loads the data contained in the resource at @resource_path into the #GtkCssProvider, clearing any previously loaded information. To track errors while loading CSS, connect to the #GtkCssProvider::parsing-error signal. a #GtkCssProvider a #GResource resource path Converts the @provider into a string representation in CSS format. Using gtk_css_provider_load_from_data() with the return value from this function on a new provider created with gtk_css_provider_new() will basically create a duplicate of this @provider. a new string representing the @provider. the provider to write to a string 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 the error happened in The parsing error Error codes for %GTK_CSS_PROVIDER_ERROR. Failed. Syntax error. Import error. Name error. Deprecation error. Unknown value. Defines a part of a CSS document. Because sections are nested into one another, you can use gtk_css_section_get_parent() to get the containing region. 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 @section is not yet parsed completely. This will for example happen in the GtkCssProvider::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. the line number the section Returns the offset in bytes from the start of the current line returned via gtk_css_section_get_end_line(). This value may change in future invocations of this function if @section is not yet parsed completely. This will for example happen in the GtkCssProvider::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. the offset in bytes from the start of the line. the section Gets the file that @section was parsed from. If no such file exists, for example because the CSS was loaded via @gtk_css_provider_load_from_data(), then %NULL is returned. the #GFile that @section was parsed from or %NULL if @section was parsed from other data the section Gets the parent section for the given @section. The parent section is the section that contains this @section. A special case are sections of type #GTK_CSS_SECTION_DOCUMENT. Their parent will either be %NULL if they are the original CSS document that was loaded by gtk_css_provider_load_from_file() or a section of type #GTK_CSS_SECTION_IMPORT if it was loaded with an import rule from a different file. the parent section or %NULL if none the section Gets the type of information that @section describes. the type of @section the section 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. the line number the section Returns the offset in bytes from the start of the current line returned via gtk_css_section_get_start_line(). the offset in bytes from the start of the line. the section Increments the reference count on @section. @section itself. a #GtkCssSection Decrements the reference count on @section, freeing the structure if the reference count reaches 0. a #GtkCssSection 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. The section describes a complete document. This section time is the only one where gtk_css_section_get_parent() might return %NULL. The section defines an import rule. The section defines a color. This is a GTK extension to CSS. The section defines a binding set. This is a GTK extension to CSS. The section defines a CSS ruleset. The section defines a CSS selector. The section defines the declaration of a CSS variable. The section defines the value of a CSS declaration. The section defines keyframes. See [CSS Animations](http://dev.w3.org/csswg/css3-animations/#keyframes) for details. Since 3.6 See also: #GtkEntry::delete-from-cursor. Delete characters. Delete only the portion of the word to the left/right of cursor if we’re in the middle of a word. Delete words. 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. Delete only the portion of the display-line to the left/right of cursor. Delete to the end of the paragraph. Like C-k in Emacs (or its reverse). Delete entire line. Like C-k in pico. Delete only whitespace. Like M-\ in Emacs. The #GtkDestDefaults enumeration specifies the various types of action that will be taken on behalf of the user for a drag destination site. 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. 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. 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 gtk_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(). If set, specifies that all default actions should be taken. 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 #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry 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. #GtkDialog boxes are created with a call to gtk_dialog_new() or gtk_dialog_new_with_buttons(). gtk_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 gtk_dialog_get_content_area() and gtk_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 gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal. If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_dialog_add_buttons(), or gtk_dialog_add_action_widget(), clicking the button will emit a signal called #GtkDialog::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 #GtkResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the #GtkDialog::response signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT. If you want to block waiting for a dialog to return before returning control flow to your code, you can call gtk_dialog_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 #GtkMessageDialog 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 GtkDialog usage: |[<!-- language="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); } ]| # GtkDialog as GtkBuildable The GtkDialog implementation of the #GtkBuildable interface exposes the @vbox and @action_area as internal children with the names “vbox” and “action_area”. GtkDialog 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. GtkDialog 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 #GtkDialog UI definition fragment: |[ <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> ]| Creates a new dialog box. Widgets should not be packed into this #GtkWindow directly, but into the @vbox and @action_area, as described above. the new dialog as a #GtkWidget Creates a new #GtkDialog with title @title (or %NULL for the default title; see gtk_window_set_title()) and transient parent @parent (or %NULL for none; see gtk_window_set_transient_for()). The @flags argument can be used to make the dialog modal (#GTK_DIALOG_MODAL) and/or to have it destroyed along with its transient parent (#GTK_DIALOG_DESTROY_WITH_PARENT). After @flags, button text/response ID pairs should be listed, with a %NULL 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 #GtkResponseType enumeration. If the user clicks one of these dialog buttons, #GtkDialog will emit the #GtkDialog::response signal with the corresponding response ID. If a #GtkDialog receives the #GtkWidget::delete-event signal, it will emit ::response with a response ID of #GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the #GTK_DIALOG_DESTROY_WITH_PARENT 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: |[<!-- language="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); ]| a new #GtkDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL from #GtkDialogFlags text to go in first button, or %NULL response ID for first button, then additional buttons, ending with %NULL Emits the #GtkDialog::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 gtk_dialog_run() will be monitoring the ::response signal and take appropriate action. a #GtkDialog response ID Adds an activatable widget to the action area of a #GtkDialog, connecting a signal handler that will emit the #GtkDialog::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 #GtkDialog struct. a #GtkDialog an activatable widget response ID for @child Adds a button with the given text and sets things up so that clicking the button will emit the #GtkDialog::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. the #GtkButton widget that was added a #GtkDialog text of button response ID for the button Adds more buttons, same as calling gtk_dialog_add_button() repeatedly. The variable argument list should be %NULL-terminated as with gtk_dialog_new_with_buttons(). Each button must have both text and response ID. a #GtkDialog button text response ID for first button, then more text-response_id pairs Returns the action area of @dialog. Direct access to the action area is discouraged; use gtk_dialog_add_button(), etc. the action area a #GtkDialog Returns the content area of @dialog. the content area #GtkBox. a #GtkDialog Returns the header bar of @dialog. Note that the headerbar is only used by the dialog if the #GtkDialog:use-header-bar property is %TRUE. the header bar a #GtkDialog Gets the response id of a widget in the action area of a dialog. the response id of @widget, or %GTK_RESPONSE_NONE if @widget doesn’t have a response id set. a #GtkDialog a widget in the action area of @dialog Gets the widget button that uses the given response ID in the action area of a dialog. the @widget button that uses the given @response_id, or %NULL. a #GtkDialog the response ID used by the @dialog widget Emits the #GtkDialog::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 gtk_dialog_run() will be monitoring the ::response signal and take appropriate action. a #GtkDialog response ID Blocks in a recursive main loop until the @dialog either emits the #GtkDialog::response signal, or is destroyed. If the dialog is destroyed during the call to gtk_dialog_run(), gtk_dialog_run() returns #GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the ::response signal emission. Before entering the recursive main loop, gtk_dialog_run() calls gtk_widget_show() on the dialog for you. Note that you still need to show any children of the dialog yourself. During gtk_dialog_run(), the default behavior of #GtkWidget::delete-event is disabled; if the dialog receives ::delete_event, it will not be destroyed as windows usually are, and gtk_dialog_run() will return #GTK_RESPONSE_DELETE_EVENT. Also, during gtk_dialog_run() the dialog will be modal. You can force gtk_dialog_run() to return at any time by calling gtk_dialog_response() to emit the ::response signal. Destroying the dialog during gtk_dialog_run() is a very bad idea, because your post-run code won’t know whether the dialog was destroyed or not. After gtk_dialog_run() returns, you are responsible for hiding or destroying the dialog if you wish to do so. Typical usage of this function might be: |[<!-- language="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 gtk_dialog_run() call. response ID a #GtkDialog Sets an alternative button order. If the #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, the dialog buttons are reordered according to the order of the response ids passed to this function. By default, GTK+ dialogs use the button order advocated by the [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/) with the affirmative button at the far right, and the cancel button left of it. But the builtin GTK+ dialogs and #GtkMessageDialogs do provide an alternative button order, which is more suitable on some platforms, e.g. Windows. Use this function after adding all the buttons to your dialog, as the following example shows: |[<!-- language="C" --> cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog), _("_Cancel"), GTK_RESPONSE_CANCEL); ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog), _("_OK"), GTK_RESPONSE_OK); gtk_widget_grab_default (ok_button); help_button = gtk_dialog_add_button (GTK_DIALOG (dialog), _("_Help"), GTK_RESPONSE_HELP); gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog), GTK_RESPONSE_OK, GTK_RESPONSE_CANCEL, GTK_RESPONSE_HELP, -1); ]| Deprecated a #GtkDialog a response id used by one @dialog’s buttons a list of more response ids of @dialog’s buttons, terminated by -1 Sets an alternative button order. If the #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, the dialog buttons are reordered according to the order of the response ids in @new_order. See gtk_dialog_set_alternative_button_order() for more information. This function is for use by language bindings. Deprecated a #GtkDialog the number of response ids in @new_order an array of response ids of @dialog’s buttons 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. a #GtkDialog a response ID 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. a #GtkDialog a response ID %TRUE for sensitive %TRUE if the dialog uses a #GtkHeaderBar 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. The ::close signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to close the dialog. The default binding for this signal is the Escape key. Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls gtk_dialog_response(). On a delete event, the response ID is #GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked. the response ID The parent class. a #GtkDialog response ID Flags used to influence dialog construction. Make the constructed dialog modal, see gtk_window_set_modal() Destroy the dialog when its parent is destroyed, see gtk_window_set_destroy_with_parent() Create dialog with actions in header bar instead of action area. Since 3.12. Focus movement types. Move forward. Move backward. Move up. Move down. Move left. Move right. Gives an indication why a drag operation failed. The value can by obtained by connecting to the #GtkWidget::drag-failed signal. The drag operation was successful. No suitable drag target. The user cancelled the drag operation. The drag operation timed out. The pointer or keyboard grab used for the drag operation was broken. The drag operation failed due to some unspecified error. The #GtkDrawingArea 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 gtk_widget_add_events() to enable events you wish to receive.) - The #GtkWidget::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 #GtkWidget::size-allocate signal to take any necessary actions when the widget changes size. - The #GtkWidget::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 GtkDrawingArea usage |[<!-- language="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; gtk_widget_queue_draw_area() and gdk_window_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 gtk_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 gtk_widget_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. Creates a new drawing area. a new #GtkDrawingArea The #GtkEditable interface is an interface which should be implemented by text editing widgets, such as #GtkEntry and #GtkSpinButton. 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 #GtkEditable::insert-text, an application can convert all entry into a widget into uppercase. ## Forcing entry to uppercase. |[<!-- language="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); } ]| 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. a #GtkEditable start position end position 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. a #GtkEditable start position end position 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. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at 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. a pointer to the contents of the widget as a string. This string is allocated by the #GtkEditable implementation and should be freed by the caller. a #GtkEditable start of text end of text 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. the cursor position a #GtkEditable 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. %TRUE if an area is selected, %FALSE otherwise a #GtkEditable location to store the starting position, or %NULL location to store the end position, or %NULL 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. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at 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. a #GtkEditable the position of the cursor 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. a #GtkEditable start of region end of region Copies the contents of the currently selected content in the editable and puts it on the clipboard. a #GtkEditable Removes the contents of the currently selected content in the editable and puts it on the clipboard. a #GtkEditable Deletes the currently selected text of the editable. This call doesn’t do anything if there is no selected text. a #GtkEditable 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. a #GtkEditable start position end position 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. a pointer to the contents of the widget as a string. This string is allocated by the #GtkEditable implementation and should be freed by the caller. a #GtkEditable start of text end of text Retrieves whether @editable is editable. See gtk_editable_set_editable(). %TRUE if @editable is editable. a #GtkEditable 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. the cursor position a #GtkEditable 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. %TRUE if an area is selected, %FALSE otherwise a #GtkEditable location to store the starting position, or %NULL location to store the end position, or %NULL 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. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at Pastes the content of the clipboard to the current position of the cursor in the editable. a #GtkEditable 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. a #GtkEditable start of region end of region Determines if the user can edit the text in the editable widget or not. a #GtkEditable %TRUE if the user is allowed to edit the text in the widget 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. a #GtkEditable the position of the cursor The ::changed signal is emitted at the end of a single user-visible operation on the contents of the #GtkEditable. 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). 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 gtk_editable_delete_text(). the starting position the end position 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. the new text to insert the length of the new text, in bytes, or -1 if new_text is nul-terminated 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. a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at a #GtkEditable start position end position a #GtkEditable the text to append the length of the text in bytes, or -1 location of the position text will be inserted at a #GtkEditable start position end position a pointer to the contents of the widget as a string. This string is allocated by the #GtkEditable implementation and should be freed by the caller. a #GtkEditable start of text end of text a #GtkEditable start of region end of region %TRUE if an area is selected, %FALSE otherwise a #GtkEditable location to store the starting position, or %NULL location to store the end position, or %NULL a #GtkEditable the position of the cursor the cursor position a #GtkEditable The #GtkEntry 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 gtk_entry_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 gtk_entry_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 #GtkEntry:caps-lock-warning property. Since 2.16, GtkEntry has the ability to display progress or activity information behind the text. To make an entry display such information, use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step(). Additionally, GtkEntry 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 gtk_entry_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 #GtkEntry::icon-press signal. To allow DND operations from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on an icon, use gtk_entry_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 |[<!-- language="plain" --> entry[.read-only][.flat][.warning][.error] ├── image.left ├── image.right ├── undershoot.left ├── undershoot.right ├── [selection] ├── [progress[.pulse]] ╰── [window.popup] ]| GtkEntry 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. Creates a new entry. a new #GtkEntry. Creates a new entry with the specified text buffer. a new #GtkEntry The buffer to use for the new #GtkEntry. Retrieves the value set by gtk_entry_set_activates_default(). %TRUE if the entry will activate the default widget a #GtkEntry Gets the value set by gtk_entry_set_alignment(). the alignment a #GtkEntry Gets the attribute list that was set on the entry using gtk_entry_set_attributes(), if any. the attribute list, or %NULL if none was set. a #GtkEntry Get the #GtkEntryBuffer object which holds the text for this widget. A #GtkEntryBuffer object. a #GtkEntry Returns the auxiliary completion object currently in use by @entry. The auxiliary completion object currently in use by @entry. A #GtkEntry 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 #GtkWidget::drag-data-get callback. index of the icon which is the source of the current DND operation, or -1. a #GtkEntry Retrieves the horizontal cursor adjustment for the entry. See gtk_entry_set_cursor_hadjustment(). the horizontal cursor adjustment, or %NULL if none has been set. a #GtkEntry Gets the value set by gtk_entry_set_has_frame(). whether the entry has a beveled frame a #GtkEntry Returns whether the icon is activatable. %TRUE if the icon is activatable. a #GtkEntry Icon position 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 @entry’s allocation. See also gtk_entry_get_text_area() A #GtkEntry Icon position Return location for the icon’s area Finds the icon at the given position and return its index. The position’s coordinates are relative to the @entry’s top left corner. If @x, @y doesn’t lie inside an icon, -1 is returned. This function is intended for use in a #GtkWidget::query-tooltip signal handler. the index of the icon at the given position, or -1 a #GtkEntry the x coordinate of the position to find the y coordinate of the position to find Retrieves the #GIcon used for the icon, or %NULL if there is no icon or if the icon was set by some other method (e.g., by stock, pixbuf, or icon name). A #GIcon, or %NULL if no icon is set or if the icon is not a #GIcon A #GtkEntry Icon position Retrieves the icon name used for the icon, or %NULL if there is no icon or if the icon was set by some other method (e.g., by pixbuf, stock or gicon). An icon name, or %NULL if no icon is set or if the icon wasn’t set from an icon name A #GtkEntry Icon position 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 #GdkPixbuf, a #GIcon, a stock item, or an icon name. A #GdkPixbuf, or %NULL if no icon is set for this position. A #GtkEntry Icon position Returns whether the icon appears sensitive or insensitive. %TRUE if the icon is sensitive. a #GtkEntry Icon position Retrieves the stock id used for the icon, or %NULL if there is no icon or if the icon was set by some other method (e.g., by pixbuf, icon name or gicon). Use gtk_entry_get_icon_name() instead. A stock id, or %NULL if no icon is set or if the icon wasn’t set from a stock id A #GtkEntry Icon position 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 %GTK_IMAGE_EMPTY. image representation being used a #GtkEntry Icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text, or %NULL. Free the returned string with g_free() when done. a #GtkEntry the icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text, or %NULL. Free the returned string with g_free() when done. a #GtkEntry the icon position This function returns the entry’s #GtkEntry:inner-border property. See gtk_entry_set_inner_border() for more information. Use the standard border and padding CSS properties (through objects like #GtkStyleContext and #GtkCssProvider); the value returned by this function is ignored by #GtkEntry. the entry’s #GtkBorder, or %NULL if none was set. a #GtkEntry Gets the value of the #GtkEntry:input-hints property. a #GtkEntry Gets the value of the #GtkEntry:input-purpose property. a #GtkEntry Retrieves the character displayed in place of the real characters for entries with visibility set to false. See gtk_entry_set_invisible_char(). the current invisible char, or 0, if the entry does not show invisible text at all. a #GtkEntry Gets the #PangoLayout used to display the entry. The layout is useful to e.g. convert text positions to pixel positions, in combination with gtk_entry_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 gtk_entry_layout_index_to_text_index() and gtk_entry_text_index_to_layout_index() are needed to convert byte indices in the layout to byte indices in the entry contents. the #PangoLayout for this entry a #GtkEntry Obtains the position of the #PangoLayout 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 #PangoLayout, 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 #PangoLayout 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 gtk_entry_layout_index_to_text_index() and gtk_entry_text_index_to_layout_index() are needed to convert byte indices in the layout to byte indices in the entry contents. a #GtkEntry location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Retrieves the maximum allowed length of the text in @entry. See gtk_entry_set_max_length(). This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_get_max_length() on it. the maximum allowed number of characters in #GtkEntry, or 0 if there is no maximum. a #GtkEntry Retrieves the desired maximum width of @entry, in characters. See gtk_entry_set_max_width_chars(). the maximum width of the entry, in characters a #GtkEntry Gets the value set by gtk_entry_set_overwrite_mode(). whether the text is overwritten when typing. a #GtkEntry Retrieves the text that will be displayed when @entry is empty and unfocused 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. a #GtkEntry Returns the current fraction of the task that’s been completed. See gtk_entry_set_progress_fraction(). a fraction from 0.0 to 1.0 a #GtkEntry Retrieves the pulse step set with gtk_entry_set_progress_pulse_step(). a fraction from 0.0 to 1.0 a #GtkEntry Gets the tabstops that were set on the entry using gtk_entry_set_tabs(), if any. the tabstops, or %NULL if none was set. a #GtkEntry Retrieves the contents of the entry widget. See also gtk_editable_get_chars(). This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_get_text() on it. 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. a #GtkEntry 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 gtk_entry_get_icon_area(). a #GtkEntry Return location for the text area. Retrieves the current length of the text in @entry. This is equivalent to getting @entry's #GtkEntryBuffer and calling gtk_entry_buffer_get_length() on it. the current number of characters in #GtkEntry, or 0 if there are none. a #GtkEntry Retrieves whether the text in @entry is visible. See gtk_entry_set_visibility(). %TRUE if the text is currently visible a #GtkEntry Gets the value set by gtk_entry_set_width_chars(). number of chars to request space for, or negative if unset a #GtkEntry Causes @entry to have keyboard focus. It behaves like gtk_widget_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. a #GtkEntry Allow the #GtkEntry 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 gtk_im_context_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 #GtkEntry. See gtk_text_view_reset_im_context() for an example of use. %TRUE if the input method handled the key event. a #GtkEntry the key event Converts from a position in the entry’s #PangoLayout (returned by gtk_entry_get_layout()) to a position in the entry contents (returned by gtk_entry_get_text()). byte index into the entry contents a #GtkEntry byte index into the entry layout text 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 gtk_entry_progress_pulse() causes the block to move by a little bit (the amount of movement per pulse is determined by gtk_entry_set_progress_pulse_step()). a #GtkEntry 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. a #GtkEntry If @setting is %TRUE, pressing Enter in the @entry 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 gtk_window_activate_default() on the window containing the entry, in the default handler for the #GtkEntry::activate signal.) a #GtkEntry %TRUE to activate window’s default widget on Enter keypress 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. a #GtkEntry The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts Sets a #PangoAttrList; the attributes in the list are applied to the entry text. a #GtkEntry a #PangoAttrList Set the #GtkEntryBuffer object which holds the text for this widget. a #GtkEntry a #GtkEntryBuffer Sets @completion to be the auxiliary completion object to use with @entry. All further configuration of the completion mechanism is done on @completion using the #GtkEntryCompletion API. Completion is disabled if @completion is set to %NULL. A #GtkEntry The #GtkEntryCompletion or %NULL 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 gtk_scrolled_window_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. a #GtkEntry an adjustment which should be adjusted when the cursor is moved, or %NULL Sets whether the entry has a beveled frame around it. a #GtkEntry new value Sets whether the icon is activatable. A #GtkEntry Icon position %TRUE if the icon should be activatable 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 #GtkWidget::drag-data-get (or possibly #GtkWidget::drag-data-delete) signal, and use gtk_entry_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 #GtkWidget::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. a #GtkEntry icon position the targets (data formats) in which the data can be provided a bitmask of the allowed drag actions 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 %NULL, no icon will be shown in the specified position. A #GtkEntry The position at which to set the icon The icon to set, or %NULL 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 %NULL, no icon will be shown in the specified position. A #GtkEntry The position at which to set the icon An icon name, or %NULL Sets the icon shown in the specified position using a pixbuf. If @pixbuf is %NULL, no icon will be shown in the specified position. a #GtkEntry Icon position A #GdkPixbuf, or %NULL Sets the icon shown in the entry at the specified position from a stock image. If @stock_id is %NULL, no icon will be shown in the specified position. Use gtk_entry_set_icon_from_icon_name() instead. A #GtkEntry Icon position The name of the stock item, or %NULL Sets the sensitivity for the specified icon. A #GtkEntry Icon position Specifies whether the icon should appear sensitive or insensitive 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 %NULL for @tooltip to remove an existing tooltip. See also gtk_widget_set_tooltip_markup() and gtk_entry_set_icon_tooltip_text(). a #GtkEntry the icon position the contents of the tooltip for the icon, or %NULL Sets @tooltip as the contents of the tooltip for the icon at the specified position. Use %NULL for @tooltip to remove an existing tooltip. See also gtk_widget_set_tooltip_text() and gtk_entry_set_icon_tooltip_markup(). If you unset the widget tooltip via gtk_widget_set_tooltip_text() or gtk_widget_set_tooltip_markup(), this sets GtkWidget:has-tooltip to %FALSE, which suppresses icon tooltips too. You can resolve this by then calling gtk_widget_set_has_tooltip() to set GtkWidget:has-tooltip back to %TRUE, or setting at least one non-empty tooltip on any icon achieves the same result. a #GtkEntry the icon position the contents of the tooltip for the icon, or %NULL Sets %entry’s inner-border property to @border, or clears it if %NULL is passed. The inner-border is the area around the entry’s text, but inside its frame. If set, this property overrides the inner-border style property. Overriding the style-provided border is useful when you want to do in-place editing of some text in a canvas or list widget, where pixel-exact positioning of the entry is important. Use the standard border and padding CSS properties (through objects like #GtkStyleContext and #GtkCssProvider); the value set with this function is ignored by #GtkEntry. a #GtkEntry a #GtkBorder, or %NULL Sets the #GtkEntry:input-hints property, which allows input methods to fine-tune their behaviour. a #GtkEntry the hints Sets the #GtkEntry:input-purpose property which can be used by on-screen keyboards and other input methods to adjust their behaviour. a #GtkEntry the purpose Sets the character to use in place of the actual text when gtk_entry_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. a #GtkEntry a Unicode character 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 @entry's #GtkEntryBuffer and calling gtk_entry_buffer_set_max_length() on it. ]| a #GtkEntry 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. Sets the desired maximum width in characters of @entry. a #GtkEntry the new desired maximum width, in characters Sets whether the text is overwritten when typing in the #GtkEntry. a #GtkEntry new value Sets text to be displayed in @entry when it is empty and unfocused. This can be used to give a visual hint of the expected contents of the #GtkEntry. 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. a #GtkEntry a string to be displayed when @entry is empty and unfocused, or %NULL 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. a #GtkEntry fraction of the task that’s been completed Sets the fraction of total entry width to move the progress bouncing block for each call to gtk_entry_progress_pulse(). a #GtkEntry fraction between 0.0 and 1.0 Sets a #PangoTabArray; the tabstops in the array are applied to the entry text. a #GtkEntry a #PangoTabArray Sets the text in the widget to the given value, replacing the current contents. See gtk_entry_buffer_set_text(). a #GtkEntry the new text 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 gtk_entry_set_invisible_char(). Note that you probably want to set #GtkEntry:input-purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to inform input methods about the purpose of this entry, in addition to setting visibility to %FALSE. a #GtkEntry %TRUE if the contents of the entry are displayed as plaintext 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. a #GtkEntry width in chars Converts from a position in the entry contents (returned by gtk_entry_get_text()) to a position in the entry’s #PangoLayout (returned by gtk_entry_get_layout(), with text retrieved via pango_layout_get_text()). byte index into the entry layout text a #GtkEntry byte index into the entry contents Unsets the invisible char previously set with gtk_entry_set_invisible_char(). So that the default invisible char is used again. a #GtkEntry 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 #PangoAttribute's @start_index and @end_index must refer to the #GtkEntryBuffer text, i.e. without the preedit string. 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. The auxiliary completion object to use with the entry. Which IM (input method) module should be used for this entry. See #GtkIMContext. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings #GtkSettings:gtk-im-module property. Sets the text area's border between the text and the frame. Use the standard border and padding CSS properties (through objects like #GtkStyleContext and #GtkCssProvider); the value of this style property is ignored. Additional hints (beyond #GtkEntry:input-purpose) that allow input methods to fine-tune their behaviour. 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 %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting #GtkEntry:visibility. The invisible character is used when masking entry contents (in \"password mode\")"). When it is not explicitly set with the #GtkEntry: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. Whether the invisible char has been set for the #GtkEntry. The desired maximum width of the entry, in characters. If this property is set to -1, the width will be calculated automatically. If text is overwritten when typing in the #GtkEntry. The text that will be displayed in the #GtkEntry when it is empty and unfocused. If :populate-all is %TRUE, the #GtkEntry::populate-popup signal is also emitted for touch popups. Whether the primary icon is activatable. GTK+ emits the #GtkEntry::icon-press and #GtkEntry::icon-release signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The #GIcon to use for the primary icon for the entry. The icon name to use for the primary icon for the entry. A pixbuf to use as the primary icon for the entry. Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK+ does not emit the #GtkEntry::icon-press and #GtkEntry::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. The stock id to use for the primary icon for the entry. Use #GtkEntry:primary-icon-name instead. The representation which is used for the primary icon of the entry. The contents of the tooltip on the primary icon, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_entry_set_icon_tooltip_markup(). The contents of the tooltip on the primary icon. Also see gtk_entry_set_icon_tooltip_text(). The current fraction of the task that's been completed. The fraction of total entry width to move the progress bouncing block for each call to gtk_entry_progress_pulse(). Whether the secondary icon is activatable. GTK+ emits the #GtkEntry::icon-press and #GtkEntry::icon-release signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The #GIcon to use for the secondary icon for the entry. The icon name to use for the secondary icon for the entry. An pixbuf to use as the secondary icon for the entry. Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK+ does not emit the #GtkEntry::icon-press and #GtkEntry::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. The stock id to use for the secondary icon for the entry. Use #GtkEntry:secondary-icon-name instead. The representation which is used for the secondary icon of the entry. The contents of the tooltip on the secondary icon, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_entry_set_icon_tooltip_markup(). The contents of the tooltip on the secondary icon. Also see gtk_entry_set_icon_tooltip_text(). Which kind of shadow to draw around the entry when #GtkEntry:has-frame is set to %TRUE. Use CSS to determine the style of the border; the value of this style property is ignored. The length of the text in the #GtkEntry. When %TRUE, pasted multi-line text is truncated to the first line. The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts. The ::activate signal is emitted when the user hits the Enter key. While this signal is used as a [keybinding signal][GtkBindingSignal], 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. The ::backspace signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. The default bindings for this signal are Backspace and Shift-Backspace. The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard. The default bindings for this signal are Ctrl-c and Ctrl-Insert. The ::cut-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cut the selection to the clipboard. The default bindings for this signal are Ctrl-x and Shift-Delete. The ::delete-from-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a text deletion. If the @type is %GTK_DELETE_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. the granularity of the deletion, as a #GtkDeleteType the number of @type units to delete The ::icon-press signal is emitted when an activatable icon is clicked. The position of the clicked icon the button press event The ::icon-release signal is emitted on the button release from a mouse click over an activatable icon. The position of the clicked icon the button release event The ::insert-at-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates the insertion of a fixed string at the cursor. This signal has no default bindings. the string to insert The ::insert-emoji signal is a [keybinding signal][GtkBindingSignal] which gets emitted to present the Emoji chooser for the @entry. The default bindings for this signal are Ctrl-. and Ctrl-; The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] 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 the granularity of the move, as a #GtkMovementStep the number of @step units to move %TRUE if the move should extend the selection The ::paste-clipboard signal is a [keybinding signal][GtkBindingSignal] 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. 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 #GtkMenu in this case. If #GtkEntry: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 #GtkToolbar. The signal handler should not make assumptions about the type of @widget. the container that is being populated 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. the current preedit string The ::toggle-overwrite signal is a [keybinding signal][GtkBindingSignal] which gets emitted to toggle the overwrite mode of the entry. The default bindings for this signal is Insert. The #GtkEntryBuffer class contains the actual text displayed in a #GtkEntry widget. A single #GtkEntryBuffer object can be shared by multiple #GtkEntry widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc. #GtkEntryBuffer 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. Create a new GtkEntryBuffer object. Optionally, specify initial text to set in the buffer. A new GtkEntryBuffer object. initial buffer text, or %NULL number of characters in @initial_chars, or -1 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. The number of characters deleted. a #GtkEntryBuffer position at which to delete text number of characters to delete Retrieves the length in characters of the buffer. The number of characters in the buffer. a #GtkEntryBuffer 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. The number of characters actually inserted. a #GtkEntryBuffer the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 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. The number of characters deleted. a #GtkEntryBuffer position at which to delete text number of characters to delete Used when subclassing #GtkEntryBuffer a #GtkEntryBuffer position at which text was deleted number of characters deleted Used when subclassing #GtkEntryBuffer a #GtkEntryBuffer position at which text was inserted text that was inserted number of characters inserted Retrieves the length in bytes of the buffer. See gtk_entry_buffer_get_length(). The byte length of the buffer. a #GtkEntryBuffer Retrieves the length in characters of the buffer. The number of characters in the buffer. a #GtkEntryBuffer Retrieves the maximum allowed length of the text in @buffer. See gtk_entry_buffer_set_max_length(). the maximum allowed number of characters in #GtkEntryBuffer, or 0 if there is no maximum. a #GtkEntryBuffer 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. 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. a #GtkEntryBuffer 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. The number of characters actually inserted. a #GtkEntryBuffer the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 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. a #GtkEntryBuffer 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. Sets the text in the buffer. This is roughly equivalent to calling gtk_entry_buffer_delete_text() and gtk_entry_buffer_insert_text(). Note that @n_chars is in characters, not in bytes. a #GtkEntryBuffer the new text the number of characters in @text, or -1 The length (in characters) of the text in buffer. The maximum length (in characters) of the text in the buffer. The contents of the buffer. This signal is emitted after text is deleted from the buffer. the position the text was deleted at. The number of characters that were deleted. This signal is emitted after text is inserted into the buffer. the position the text was inserted at. The text that was inserted. The number of characters that were inserted. The number of characters in the buffer. a #GtkEntryBuffer The number of characters actually inserted. a #GtkEntryBuffer the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 The number of characters deleted. a #GtkEntryBuffer position at which to delete text number of characters to delete Class structure for #GtkEntry. All virtual functions have a default implementation. Derived classes may set the virtual function pointers for the signal handlers to %NULL, but must keep @get_text_area_size and @get_frame_size non-%NULL; either use the default implementation, or provide a custom one. The parent class. #GtkEntryCompletion is an auxiliary object to be used in conjunction with #GtkEntry to provide the completion functionality. It implements the #GtkCellLayout interface, to allow the user to add extra cells to the #GtkTreeView with completion matches. “Completion functionality” means that when the user modifies the text in the entry, #GtkEntryCompletion 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 gtk_entry_completion_set_text_column()), but this can be overridden with a custom match function (see gtk_entry_completion_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 #GtkEntryCompletion::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 gtk_entry_set_completion(). In addition to regular completion matches, which will be inserted into the entry when they are selected, #GtkEntryCompletion 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 #GtkEntryCompletion::action-activated signal is emitted. GtkEntryCompletion uses a #GtkTreeModelFilter model to represent the subset of the entire model that is currently matching. While the GtkEntryCompletion signals #GtkEntryCompletion::match-selected and #GtkEntryCompletion::cursor-on-match take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as #GtkCellLayoutDataFuncs or #GtkCellArea::apply-attributes) will generally take the filter model as argument. As long as you are only calling gtk_tree_model_get(), this will make no difference to you. If for some reason, you need the original model, use gtk_tree_model_filter_get_model(). Don’t forget to use gtk_tree_model_filter_convert_iter_to_child_iter() to obtain a matching iter. Creates a new #GtkEntryCompletion object. A newly created #GtkEntryCompletion object Creates a new #GtkEntryCompletion object using the specified @area to layout cells in the underlying #GtkTreeViewColumn for the drop-down menu. A newly created #GtkEntryCompletion object the #GtkCellArea used to layout cells 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. a #GtkEntryCompletion Computes the common prefix that is shared by all rows in @completion that start with @key. If no row matches @key, %NULL will be returned. Note that a text column must have been set for this function to work, see gtk_entry_completion_set_text_column() for details. The common prefix all rows starting with @key or %NULL if no row matches @key. the entry completion The text to complete for Deletes the action at @index_ from @completion’s action list. Note that @index_ is a relative position and the position of an action may have changed since it was inserted. a #GtkEntryCompletion the index of the item to delete Get the original text entered by the user that triggered the completion or %NULL if there’s no completion ongoing. the prefix for the current completion a #GtkEntryCompletion Gets the entry @completion has been attached to. The entry @completion has been attached to a #GtkEntryCompletion Returns whether the common prefix of the possible completions should be automatically inserted in the entry. %TRUE if inline completion is turned on a #GtkEntryCompletion Returns %TRUE if inline-selection mode is turned on. %TRUE if inline-selection mode is on a #GtkEntryCompletion Returns the minimum key length as set for @completion. The currently used minimum key length a #GtkEntryCompletion Returns the model the #GtkEntryCompletion is using as data source. Returns %NULL if the model is unset. A #GtkTreeModel, or %NULL if none is currently being used a #GtkEntryCompletion Returns whether the completions should be presented in a popup window. %TRUE if popup completion is turned on a #GtkEntryCompletion Returns whether the completion popup window will be resized to the width of the entry. %TRUE if the popup window will be resized to the width of the entry a #GtkEntryCompletion Returns whether the completion popup window will appear even if there is only a single match. %TRUE if the popup window will appear regardless of the number of matches a #GtkEntryCompletion Returns the column in the model of @completion to get strings from. the column containing the strings a #GtkEntryCompletion Inserts an action in @completion’s action item list at position @index_ with markup @markup. a #GtkEntryCompletion the index of the item to insert markup of the item to insert Inserts an action in @completion’s action item list at position @index_ with text @text. If you want the action item to have markup, use gtk_entry_completion_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. a #GtkEntryCompletion the index of the item to insert text of the item to insert Requests a prefix insertion. a #GtkEntryCompletion Sets whether the common prefix of the possible completions should be automatically inserted in the entry. a #GtkEntryCompletion %TRUE to do inline completion Sets whether it is possible to cycle through the possible completions inside the entry. a #GtkEntryCompletion %TRUE to do inline selection Sets the match function for @completion to be @func. The match function is used to determine if a row should or should not be in the completion list. a #GtkEntryCompletion the #GtkEntryCompletionMatchFunc to use user data for @func destroy notify for @func_data. Requires the length of the search key for @completion 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). a #GtkEntryCompletion the minimum length of the key in order to start completing Sets the model for a #GtkEntryCompletion. If @completion already has a model set, it will remove it before setting the new model. If model is %NULL, then it will unset the model. a #GtkEntryCompletion the #GtkTreeModel Sets whether the completions should be presented in a popup window. a #GtkEntryCompletion %TRUE to do popup completion Sets whether the completion popup window will be resized to be the same width as the entry. a #GtkEntryCompletion %TRUE to make the width of the popup the same as the entry 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][GtkEntryCompletion--inline-completion]. a #GtkEntryCompletion %TRUE if the popup should appear even for a single match Convenience function for setting up the most used case of this code: a completion list with just strings. This function will set up @completion to have a list displaying all (and just) strings in the completion list, and to get those strings from @column in the model of @completion. This functions creates and adds a #GtkCellRendererText for the selected column. If you need to set the text column, but don't want the cell renderer, use g_object_set() to set the #GtkEntryCompletion:text-column property directly. a #GtkEntryCompletion the column in the model of @completion to get strings from The #GtkCellArea used to layout cell renderers in the treeview column. If no area is specified when creating the entry completion with gtk_entry_completion_new_with_area() a horizontally oriented #GtkCellAreaBox will be used. 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. Determines whether the possible completions on the popup will appear in the entry as you navigate through them. Determines whether the possible completions should be shown in a popup window. Determines whether the completions popup window will be resized to the width of the entry. 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][GtkEntryCompletion--inline-completion]. The column of the model containing the strings. Note that the strings must be UTF-8. Gets emitted when an action is activated. the index of the activated action 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 gtk_entry_completion_set_model(). %TRUE if the signal has been handled the #GtkTreeModel containing the matches a #GtkTreeIter positioned at the selected match 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 #GtkFileChooser inserts only the part of the prefix up to the next '/'. %TRUE if the signal has been handled the common prefix of all possible completions 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 gtk_entry_completion_set_model(). %TRUE if the signal has been handled the #GtkTreeModel containing the matches a #GtkTreeIter positioned at the selected match Gets emitted when the filter model has zero number of rows in completion_complete method. (In other words when GtkEntryCompletion is out of suggestions) A function which decides whether the row indicated by @iter matches a given @key, and should be displayed as a possible completion for @key. Note that @key is normalized and case-folded (see g_utf8_normalize() and g_utf8_casefold()). If this is not appropriate, match functions have access to the unmodified key via `gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry ()))`. %TRUE if @iter should be displayed as a possible completion for @key the #GtkEntryCompletion the string to match, normalized and case-folded a #GtkTreeIter indicating the row to match user data given to gtk_entry_completion_set_match_func() Specifies the side of the entry at which an icon is placed. At the beginning of the entry (depending on the text direction). At the end of the entry (depending on the text direction). The #GtkEventBox widget is a subclass of #GtkBin 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. Creates a new #GtkEventBox. a new #GtkEventBox Returns whether the event box window is above or below the windows of its child. See gtk_event_box_set_above_child() for details. %TRUE if the event box window is above the window of its child a #GtkEventBox Returns whether the event box has a visible window. See gtk_event_box_set_visible_window() for details. %TRUE if the event box window is visible a #GtkEventBox 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. a #GtkEventBox %TRUE if the event box window is above its child 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_INPUT_ONLY window, which means that it is invisible and only serves to receive events. A visible window event box creates a visible (%GDK_INPUT_OUTPUT) 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 gtk_event_box_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 gtk_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. a #GtkEventBox %TRUE to make the event box have a visible window The parent class. #GtkEventController 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. Gets the propagation phase at which @controller handles events. the propagation phase a #GtkEventController Returns the #GtkWidget this controller relates to. a #GtkWidget a #GtkEventController Feeds an events into @controller, so it can be interpreted and the controller actions triggered. %TRUE if the event was potentially useful to trigger the controller action a #GtkEventController a #GdkEvent Resets the @controller to a clean state. Every interaction the controller did through #GtkEventController::handle-event will be dropped at this point. a #GtkEventController Sets the propagation phase at which a controller handles events. If @phase is %GTK_PHASE_NONE, no automatic event handling will be performed, but other additional gesture maintenance will. In that phase, the events can be managed by calling gtk_event_controller_handle_event(). a #GtkEventController a propagation phase The propagation phase at which this controller will handle events. The widget receiving the #GdkEvents that the controller will handle. #GtkEventControllerKey is an event controller meant for situations where you need access to key events. This object was added in 3.24. Gets the IM context of a key controller. the IM context a #GtkEventControllerKey This signal is emitted whenever a key is pressed. %TRUE if the key press was handled, %FALSE otherwise. the pressed key. the raw code of the pressed key. the bitmask, representing the state of modifier keys and pointer buttons. See #GdkModifierType. This signal is emitted whenever a key is released. the released key. the raw code of the released key. the bitmask, representing the state of modifier keys and pointer buttons. See #GdkModifierType. #GtkEventControllerMotion is an event controller meant for situations where you need to track the position of the pointer. This object was added in 3.24. Creates a new event controller that will handle motion events for the given @widget. a new #GtkEventControllerMotion a #GtkWidget Signals that the pointer has entered the widget. the x coordinate the y coordinate Signals that pointer has left the widget. Emitted when the pointer moves inside the widget. the x coordinate the y coordinate #GtkEventControllerScroll 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 #GtkEventControllerScroll::scroll signal (deltas in the discrete case are multiples of 1). In the case of continuous scroll events, #GtkEventControllerScroll encloses all #GtkEventControllerScroll::scroll events between two #GtkEventControllerScroll::scroll-begin and #GtkEventControllerScroll::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 gtk_event_controller_scroll_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 #GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, #GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and #GTK_EVENT_CONTROLLER_SCROLL_BOTH. If any axis is disabled, the respective #GtkEventControllerScroll::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 #GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement discrete actions triggered through scroll events (e.g. switching across combobox options). The #GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the #GtkEventControllerScroll::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. Creates a new event controller that will handle scroll events for the given @widget. a new #GtkEventControllerScroll a #GtkWidget behavior flags Gets the flags conditioning the scroll controller behavior. the controller flags. Sets the flags conditioning scroll controller behavior. behavior flags The flags affecting event controller behavior Emitted after scroll is finished if the #GTK_EVENT_CONTROLLER_SCROLL_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. X velocity Y velocity Signals that the widget should scroll by the amount specified by @dx and @dy. X delta Y delta Signals that a new scrolling operation has begun. It will only be emitted on devices capable of it. Signals that a new scrolling operation has finished. It will only be emitted on devices capable of it. Describes the behavior of a #GtkEventControllerScroll. Don't emit scroll. Emit scroll with vertical deltas. Emit scroll with horizontal deltas. Only emit deltas that are multiples of 1. Emit #GtkEventControllerScroll::decelerate after continuous scroll finishes. Emit scroll on both axes. Describes the state of a #GdkEventSequence in a #GtkGesture. The sequence is handled, but not grabbed. The sequence is handled and grabbed. The sequence is denied. A #GtkExpander allows the user to hide or show its child by clicking on an expander triangle similar to the triangles used in a #GtkTreeView. Normally you use an expander as you would use any other descendant of #GtkBin; you create the child widget and use gtk_container_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 #GtkExpander but do not add a child to it. The expander widget has an #GtkExpander:expanded property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows: |[<!-- language="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); // ... } ]| # GtkExpander as GtkBuildable The GtkExpander implementation of the GtkBuildable 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 GtkExpander: |[ <object class="GtkExpander"> <child type="label"> <object class="GtkLabel" id="expander-label"/> </child> <child> <object class="GtkEntry" id="expander-content"/> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> expander ├── title │ ├── arrow │ ╰── <label widget> ╰── <child> ]| GtkExpander 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. Creates a new expander using @label as the text of the label. a new #GtkExpander widget. the text of the label 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. a new #GtkExpander widget. the text of the label with an underscore in front of the mnemonic character Queries a #GtkExpander and returns its current state. Returns %TRUE if the child widget is revealed. See gtk_expander_set_expanded(). the current state of the expander a #GtkExpander Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup, as set by gtk_expander_set_label(). If the label text has not been set the return value will be %NULL. This will be the case if you create an empty button with gtk_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. The text of the label widget. This string is owned by the widget and must not be modified or freed. a #GtkExpander Returns whether the label widget will fill all available horizontal space allocated to @expander. %TRUE if the label widget will fill all available horizontal space a #GtkExpander Retrieves the label widget for the frame. See gtk_expander_set_label_widget(). the label widget, or %NULL if there is none a #GtkExpander Returns whether the expander will resize the toplevel widget containing the expander upon resizing and collpasing. the “resize toplevel” setting. a #GtkExpander Gets the value set by gtk_expander_set_spacing(). Use margins on the child instead. spacing between the expander and child a #GtkExpander Returns whether the label’s text is interpreted as marked up with the [Pango text markup language][PangoMarkupFormat]. See gtk_expander_set_use_markup(). %TRUE if the label’s text will be parsed for markup a #GtkExpander Returns whether an embedded underline in the expander label indicates a mnemonic. See gtk_expander_set_use_underline(). %TRUE if an embedded underline in the expander label indicates the mnemonic accelerator keys a #GtkExpander 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. a #GtkExpander whether the child widget is revealed Sets the text of the label of the expander to @label. This will also clear any previously set labels. a #GtkExpander a string Sets whether the label widget should fill all available horizontal space allocated to @expander. a #GtkExpander %TRUE if the label should should fill all available horizontal space Set the label widget for the expander. This is the widget that will appear embedded alongside the expander arrow. a #GtkExpander the new label widget Sets whether the expander will resize the toplevel widget containing the expander upon resizing and collpasing. a #GtkExpander whether to resize the toplevel Sets the spacing field of @expander, which is the number of pixels to place between expander and the child. Use margins on the child instead. a #GtkExpander distance between the expander and child in pixels Sets whether the text of the label contains markup in [Pango’s text markup language][PangoMarkupFormat]. See gtk_label_set_markup(). a #GtkExpander %TRUE if the label’s text should be parsed for markup If true, an underline in the text of the expander label indicates the next character should be used for the mnemonic accelerator key. a #GtkExpander %TRUE if underlines in the text indicate mnemonics When this property is %TRUE, the expander will resize the toplevel widget containing the expander upon expanding and collapsing. Space to put between the label and the child when the expander is expanded. This property is deprecated and ignored. Use margins on the child instead. The parent class. Used to specify the style of the expanders drawn by a #GtkTreeView. The style used for a collapsed subtree. Intermediate style used during animation. Intermediate style used during animation. The style used for an expanded subtree. #GtkFileChooser is an interface that can be implemented by file selection widgets. In GTK+, the main objects that implement this interface are #GtkFileChooserWidget, #GtkFileChooserDialog, and #GtkFileChooserButton. You do not need to write an object that implements the #GtkFileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface. #GtkFileChooser 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 #GtkFileChooser, 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 gtk_file_chooser_get_filename() to open() or fopen(), you may not be able to directly set it as the text of a #GtkLabel 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 gtk_file_chooser_set_preview_widget(). Then, connect to the #GtkFileChooser::update-preview signal to get notified when you need to update the contents of the preview. Your callback should use gtk_file_chooser_get_preview_filename() to see what needs previewing. Once you have generated the preview for the corresponding file, you must call gtk_file_chooser_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} |[<!-- language="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 gtk_file_chooser_set_extra_widget() to insert additional widgets in a file chooser. An example for adding extra widgets: |[<!-- language="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 #GtkBox or a #GtkGrid and include your widgets in it. Then, set the container as the whole extra widget. 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 gtk_file_chooser_set_choice() before the dialog is shown, and you can obtain the user-selected value in the ::response signal handler using gtk_file_chooser_get_choice(). Compare gtk_file_chooser_set_extra_widget(). a #GtkFileChooser id for the added choice user-visible label for the added choice ids for the options of the choice, or %NULL for a boolean choice user-visible labels for the options, must be the same length as @options 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 @chooser takes ownership of the filter, so you have to ref and sink it if you want to keep a reference. a #GtkFileChooser a #GtkFileFilter 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. %TRUE if the folder could be added successfully, %FALSE otherwise. In the latter case, the @error will be set as appropriate. a #GtkFileChooser filename of the folder to add 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. %TRUE if the folder could be added successfully, %FALSE otherwise. In the latter case, the @error will be set as appropriate. a #GtkFileChooser URI of the folder to add Gets the type of operation that the file chooser is performing; see gtk_file_chooser_set_action(). the action that the file selector is performing a #GtkFileChooser Gets the currently selected option in the 'choice' with the given ID. the ID of the currenly selected option a #GtkFileChooser the ID of the choice to get Gets whether file choser will offer to create new folders. See gtk_file_chooser_set_create_folders(). %TRUE if the Create Folder button should be displayed. a #GtkFileChooser Gets the current folder of @chooser as a local filename. See gtk_file_chooser_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 %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode (e.g. "/home/username/Documents/selected-folder/". To get the currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the usual way to get the selection. the full path of the current folder, or %NULL if the current path cannot be represented as a local filename. Free with g_free(). This function will also return %NULL if the file chooser was unable to load the last folder that was requested from it; for example, as would be for calling gtk_file_chooser_set_current_folder() on a nonexistent folder. a #GtkFileChooser Gets the current folder of @chooser as #GFile. See gtk_file_chooser_get_current_folder_uri(). the #GFile for the current folder. a #GtkFileChooser Gets the current folder of @chooser as an URI. See gtk_file_chooser_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 %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode (e.g. "file:///home/username/Documents/selected-folder/". To get the currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the usual way to get the selection. the URI for the current folder. Free with g_free(). This function will also return %NULL if the file chooser was unable to load the last folder that was requested from it; for example, as would be for calling gtk_file_chooser_set_current_folder_uri() on a nonexistent folder. a #GtkFileChooser 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”. 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. a #GtkFileChooser Queries whether a file chooser is set to confirm for overwriting when the user types a file name that already exists. %TRUE if the file chooser will present a confirmation dialog; %FALSE otherwise. a #GtkFileChooser Gets the current extra widget; see gtk_file_chooser_set_extra_widget(). the current extra widget, or %NULL a #GtkFileChooser Gets the #GFile 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. a selected #GFile. You own the returned file; use g_object_unref() to release it. a #GtkFileChooser 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. The currently selected filename, or %NULL if no file is selected, or the selected file can't be represented with a local filename. Free with g_free(). a #GtkFileChooser Lists all the selected files and subfolders in the current folder of @chooser. The returned names are full absolute paths. If files in the current folder cannot be represented as local filenames they will be ignored. (See gtk_file_chooser_get_uris()) a #GSList containing the filenames of all selected files and subfolders in the current folder. Free the returned list with g_slist_free(), and the filenames with g_free(). a #GtkFileChooser Lists all the selected files and subfolders in the current folder of @chooser as #GFile. An internal function, see gtk_file_chooser_get_uris(). a #GSList containing a #GFile for each selected file and subfolder in the current folder. Free the returned list with g_slist_free(), and the files with g_object_unref(). a #GtkFileChooser Gets the current filter; see gtk_file_chooser_set_filter(). the current filter, or %NULL a #GtkFileChooser Gets whether only local files can be selected in the file selector. See gtk_file_chooser_set_local_only() %TRUE if only local files can be selected. a #GtkFileChooser Gets the #GFile that should be previewed in a custom preview Internal function, see gtk_file_chooser_get_preview_uri(). the #GFile for the file to preview, or %NULL if no file is selected. Free with g_object_unref(). a #GtkFileChooser Gets the filename that should be previewed in a custom preview widget. See gtk_file_chooser_set_preview_widget(). the filename to preview, or %NULL if no file is selected, or if the selected file cannot be represented as a local filename. Free with g_free() a #GtkFileChooser Gets the URI that should be previewed in a custom preview widget. See gtk_file_chooser_set_preview_widget(). the URI for the file to preview, or %NULL if no file is selected. Free with g_free(). a #GtkFileChooser Gets the current preview widget; see gtk_file_chooser_set_preview_widget(). the current preview widget, or %NULL a #GtkFileChooser Gets whether the preview widget set by gtk_file_chooser_set_preview_widget() should be shown for the current filename. See gtk_file_chooser_set_preview_widget_active(). %TRUE if the preview widget is active for the current filename. a #GtkFileChooser Gets whether multiple files can be selected in the file selector. See gtk_file_chooser_set_select_multiple(). %TRUE if multiple files can be selected. a #GtkFileChooser Gets whether hidden files and folders are displayed in the file selector. See gtk_file_chooser_set_show_hidden(). %TRUE if hidden files and folders are displayed. a #GtkFileChooser 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. The currently selected URI, or %NULL if no file is selected. If gtk_file_chooser_set_local_only() is set to %TRUE (the default) a local URI will be returned for any FUSE locations. Free with g_free() a #GtkFileChooser Lists all the selected files and subfolders in the current folder of @chooser. The returned names are full absolute URIs. a #GSList containing the URIs of all selected files and subfolders in the current folder. Free the returned list with g_slist_free(), and the filenames with g_free(). a #GtkFileChooser Gets whether a stock label should be drawn with the name of the previewed file. See gtk_file_chooser_set_use_preview_label(). %TRUE if the file chooser is set to display a label with the name of the previewed file, %FALSE otherwise. a #GtkFileChooser Lists the current set of user-selectable filters; see gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter(). a #GSList 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 g_slist_free() when you are done with it. a #GtkFileChooser Queries the list of shortcut folders in the file chooser, as set by gtk_file_chooser_add_shortcut_folder_uri(). A list of folder URIs, or %NULL if there are no shortcut folders. Free the returned list with g_slist_free(), and the URIs with g_free(). a #GtkFileChooser Queries the list of shortcut folders in the file chooser, as set by gtk_file_chooser_add_shortcut_folder(). A list of folder filenames, or %NULL if there are no shortcut folders. Free the returned list with g_slist_free(), and the filenames with g_free(). a #GtkFileChooser Removes a 'choice' that has been added with gtk_file_chooser_add_choice(). a #GtkFileChooser the ID of the choice to remove Removes @filter from the list of filters that the user can select between. a #GtkFileChooser a #GtkFileFilter Removes a folder from a file chooser’s list of shortcut folders. %TRUE if the operation succeeds, %FALSE otherwise. In the latter case, the @error will be set as appropriate. See also: gtk_file_chooser_add_shortcut_folder() a #GtkFileChooser filename of the folder to remove Removes a folder URI from a file chooser’s list of shortcut folders. %TRUE if the operation succeeds, %FALSE otherwise. In the latter case, the @error will be set as appropriate. See also: gtk_file_chooser_add_shortcut_folder_uri() a #GtkFileChooser URI of the folder to remove Selects all the files in the current folder of a file chooser. a #GtkFileChooser Selects the file referred to by @file. An internal function. See _gtk_file_chooser_select_uri(). Not useful. a #GtkFileChooser the file to select Selects a filename. If the file name isn’t in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @filename. Not useful. See also: gtk_file_chooser_set_filename() a #GtkFileChooser the filename to select Selects the file to by @uri. If the URI doesn’t refer to a file in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @filename. Not useful. a #GtkFileChooser the URI to select 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 %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is %GTK_FILE_CHOOSER_ACTION_OPEN. a #GtkFileChooser the action that the file selector is performing Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice(). For a boolean choice, the possible options are "true" and "false". a #GtkFileChooser the ID of the choice to set the ID of the option to select Sets whether file choser will offer to create new folders. This is only relevant if the action is not set to be %GTK_FILE_CHOOSER_ACTION_OPEN. a #GtkFileChooser %TRUE if the Create Folder button should be displayed Sets the current folder for @chooser 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. Not useful. a #GtkFileChooser the full path of the new current folder Sets the current folder for @chooser from a #GFile. Internal function, see gtk_file_chooser_set_current_folder_uri(). %TRUE if the folder could be changed successfully, %FALSE otherwise. a #GtkFileChooser the #GFile for the new folder Sets the current folder for @chooser 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. %TRUE if the folder could be changed successfully, %FALSE otherwise. a #GtkFileChooser the URI for the new current folder 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 gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead. Please see the documentation for those functions for an example of using gtk_file_chooser_set_current_name() as well. a #GtkFileChooser the filename to use, as a UTF-8 string Sets whether a file chooser in %GTK_FILE_CHOOSER_ACTION_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 @chooser will emit the #GtkFileChooser::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 #GtkFileChooser::confirm-overwrite signal; please refer to its documentation for the details. a #GtkFileChooser whether to confirm overwriting in save mode Sets an application-supplied widget to provide extra options to the user. a #GtkFileChooser widget for extra options 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 @chooser is in %GTK_FILE_CHOOSER_ACTION_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 @chooser, then the current folder of @chooser will be changed to the folder containing @filename. This is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by gtk_file_chooser_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: |[<!-- language="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); } ]| Not useful. a #GtkFileChooser the #GFile to set as current 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 @chooser is in %GTK_FILE_CHOOSER_ACTION_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: |[<!-- language="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. Not useful. a #GtkFileChooser the filename to set as current 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. a #GtkFileChooser a #GtkFileFilter 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 #GtkFileChooser, like gtk_file_chooser_get_filename(), rather than the URI functions like gtk_file_chooser_get_uri(), On some systems non-native files may still be available using the native filesystem via a userspace filesystem (FUSE). a #GtkFileChooser %TRUE if only local files can be selected 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 #GtkFileChooser::update-preview signal, and call gtk_file_chooser_get_preview_filename() or gtk_file_chooser_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 gtk_file_chooser_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. a #GtkFileChooser widget for displaying preview. Sets whether the preview widget set by gtk_file_chooser_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 gtk_file_chooser_set_preview_widget() for more details. a #GtkFileChooser whether to display the user-specified preview widget Sets whether multiple files can be selected in the file selector. This is only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. a #GtkFileChooser %TRUE if multiple files can be selected. Sets whether hidden files and folders are displayed in the file selector. a #GtkFileChooser %TRUE if hidden files and folders should be displayed. 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 @chooser is %GTK_FILE_CHOOSER_ACTION_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: |[<!-- language="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. Not useful. a #GtkFileChooser the URI to set as current 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: gtk_file_chooser_set_preview_widget() a #GtkFileChooser whether to display a stock label with the name of the previewed file Unselects all the files in the current folder of a file chooser. a #GtkFileChooser 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. a #GtkFileChooser a #GFile 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. a #GtkFileChooser the filename to unselect 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. a #GtkFileChooser the URI to unselect Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode will offer the user to create new folders. Whether a file chooser in %GTK_FILE_CHOOSER_ACTION_SAVE mode will present an overwrite confirmation dialog if the user selects a file name that already exists. 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 %GTK_FILE_CHOOSER_ACTION_SAVE mode. Most applications just need to turn on the #GtkFileChooser:do-overwrite-confirmation property (or call the gtk_file_chooser_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 #GtkFileChooser::confirm-overwrite signal. A signal handler for this signal must return a #GtkFileChooserConfirmation value, which indicates the action to take. If the handler determines that the user wants to select a different filename, it should return %GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines that the user is satisfied with his choice of file name, it should return %GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME. On the other hand, if it determines that the stock confirmation dialog should be used, it should return %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example illustrates this. ## Custom confirmation ## {#gtkfilechooser-confirmation} |[<!-- language="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); ]| a #GtkFileChooserConfirmation value that indicates which action to take after emitting the signal. This signal is emitted when the current folder in a #GtkFileChooser 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: gtk_file_chooser_set_current_folder(), gtk_file_chooser_get_current_folder(), gtk_file_chooser_set_current_folder_uri(), gtk_file_chooser_get_current_folder_uri(). 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 #GtkFileChooserDialog to know when to activate the default button in the dialog. See also: gtk_file_chooser_get_filename(), gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(), gtk_file_chooser_get_uris(). This signal is emitted when there is a change in the set of selected files in a #GtkFileChooser. 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: gtk_file_chooser_select_filename(), gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(), gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(), gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(), gtk_file_chooser_get_uris(). 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 gtk_file_chooser_set_preview_widget(), you should update it when this signal is emitted. You can use the functions gtk_file_chooser_get_preview_filename() or gtk_file_chooser_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 gtk_file_chooser_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: gtk_file_chooser_set_preview_widget(), gtk_file_chooser_set_preview_widget_active(), gtk_file_chooser_set_use_preview_label(), gtk_file_chooser_get_preview_filename(), gtk_file_chooser_get_preview_uri(). Describes whether a #GtkFileChooser is being used to open existing files or to save to a possibly new file. Indicates open mode. The file chooser will only let the user pick an existing file. Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename. Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder. Indicates a mode for creating a new folder. The file chooser will let the user name an existing or new folder. The #GtkFileChooserButton is a widget that lets the user select a file. It implements the #GtkFileChooser interface. Visually, it is a file name with a button to bring up a #GtkFileChooserDialog. The user can then use that dialog to change the file associated with that button. This widget does not support setting the #GtkFileChooser:select-multiple property to %TRUE. ## Create a button to let the user select a file in /etc |[<!-- language="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 #GtkFileChooserButton supports the #GtkFileChooserActions %GTK_FILE_CHOOSER_ACTION_OPEN and %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. > The #GtkFileChooserButton will ellipsize the label, and will thus > request little horizontal space. To give the button more space, > you should call gtk_widget_get_preferred_size(), > gtk_file_chooser_button_set_width_chars(), or pack the button in > such a way that other interface elements give space to the > widget. # CSS nodes GtkFileChooserButton has a CSS node with name “filechooserbutton”, containing a subnode for the internal button with name “button” and style class “.file”. Creates a new file-selecting button widget. a new button widget. the title of the browse dialog. the open mode for the widget. Creates a #GtkFileChooserButton widget which uses @dialog as its file-picking window. Note that @dialog must be a #GtkDialog (or subclass) which implements the #GtkFileChooser interface and must not have %GTK_DIALOG_DESTROY_WITH_PARENT set. Also note that the dialog needs to have its confirmative button added with response %GTK_RESPONSE_ACCEPT or %GTK_RESPONSE_OK in order for the button to take over the file selected in the dialog. a new button widget. the widget to use as dialog Returns whether the button grabs focus when it is clicked with the mouse. See gtk_file_chooser_button_set_focus_on_click(). Use gtk_widget_get_focus_on_click() instead %TRUE if the button grabs focus when it is clicked with the mouse. a #GtkFileChooserButton Retrieves the title of the browse dialog used by @button. The returned value should not be modified or freed. a pointer to the browse dialog’s title. the button widget to examine. Retrieves the width in characters of the @button widget’s entry and/or label. an integer width (in characters) that the button will use to size itself. the button widget to examine. 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. Use gtk_widget_set_focus_on_click() instead a #GtkFileChooserButton whether the button grabs focus when clicked with the mouse Modifies the @title of the browse dialog used by @button. the button widget to modify. the new browse dialog title. Sets the width (in characters) that @button will use to @n_chars. the button widget to examine. the new width, in characters. Instance of the #GtkFileChooserDialog associated with the button. Title to put on the #GtkFileChooserDialog associated with the button. The width of the entry and label inside the button, in characters. 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. The parent class. Used as a return value of handlers for the #GtkFileChooser::confirm-overwrite signal of a #GtkFileChooser. 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. The file chooser will present its stock dialog to confirm about overwriting an existing file. The file chooser will terminate and accept the user’s choice of a file name. The file chooser will continue running, so as to let the user select another file name. #GtkFileChooserDialog is a dialog box suitable for use with “File/Open” or “File/Save as” commands. This widget works by putting a #GtkFileChooserWidget inside a #GtkDialog. It exposes the #GtkFileChooser interface, so you can use all of the #GtkFileChooser functions on the file chooser dialog as well as those for #GtkDialog. Note that #GtkFileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a #GtkFileChooser. If you want to integrate well with the platform you should use the #GtkFileChooserNative API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise. ## Typical usage ## {#gtkfilechooser-typical-usage} In the simplest of cases, you can the following code to use #GtkFileChooserDialog to select a file for opening: |[ 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: |[ 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 #GtkFileChooserDialog: - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN. - To save a file for the first time. Use #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with gtk_file_chooser_set_current_name(). - To save a file under a different name. Use #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename with gtk_file_chooser_set_filename(). - To choose a folder instead of a file. Use #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. Note that old versions of the file chooser’s documentation suggested using gtk_file_chooser_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 gtk_file_chooser_set_filename(), i.e. when you are doing a Save As command and you already have a file saved somewhere. ## Response Codes ## {#gtkfilechooserdialog-responses} #GtkFileChooserDialog inherits from #GtkDialog, so buttons that go in its action area have response codes such as #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL. For example, you could call gtk_file_chooser_dialog_new() as follows: |[ 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 #GtkResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in #GtkResponseType, but #GtkFileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes: - #GTK_RESPONSE_ACCEPT - #GTK_RESPONSE_OK - #GTK_RESPONSE_YES - #GTK_RESPONSE_APPLY This is because #GtkFileChooserDialog 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 #GtkFileChooserDialog to ensure proper operation. Creates a new #GtkFileChooserDialog. This function is analogous to gtk_dialog_new_with_buttons(). a new #GtkFileChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL Open or save mode for the dialog stock ID or text to go in the first button, or %NULL response ID for the first button, then additional (button, id) pairs, ending with %NULL These identify the various errors that can occur while calling #GtkFileChooser functions. Indicates that a file does not exist. Indicates a malformed filename. Indicates a duplicate path (e.g. when adding a bookmark). Indicates an incomplete hostname (e.g. "http://foo" without a slash after that). Registers an error quark for #GtkFileChooser if necessary. The error quark used for #GtkFileChooser errors. #GtkFileChooserNative is an abstraction of a dialog box suitable for use with “File/Open” or “File/Save as” commands. By default, this just uses a #GtkFileChooserDialog 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), #GtkFileChooserNative may call the proper APIs (portals) to let the user choose a file and make it available to the application. While the API of #GtkFileChooserNative closely mirrors #GtkFileChooserDialog, the main difference is that there is no access to any #GtkWindow or #GtkWidget 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 #GtkNativeDialog functions. ## Typical usage ## {#gtkfilechoosernative-typical-usage} In the simplest of cases, you can the following code to use #GtkFileChooserDialog to select a file for opening: |[ 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: |[ 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 #GtkFileChooserDialog. ## Response Codes ## {#gtkfilechooserdialognative-responses} #GtkFileChooserNative inherits from #GtkNativeDialog, which means it will return #GTK_RESPONSE_ACCEPT if the user accepted, and #GTK_RESPONSE_CANCEL if he pressed cancel. It can also return #GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed. ## Differences from #GtkFileChooserDialog ## {#gtkfilechooserdialognative-differences} There are a few things in the GtkFileChooser API that are not possible to use with #GtkFileChooserNative, 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: * #GtkFileChooser::current-folder-changed * #GtkFileChooser::selection-changed * #GtkFileChooser::file-activated * #GtkFileChooser::confirm-overwrite You can also not use the methods that directly control user navigation: * gtk_file_chooser_unselect_filename() * gtk_file_chooser_select_all() * gtk_file_chooser_unselect_all() If you need any of the above you will have to use #GtkFileChooserDialog 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 #GtkFileChooserDialog does, but there are some things it does not handle: * Extra widgets added with gtk_file_chooser_set_extra_widget(). * Use of custom previews by connecting to #GtkFileChooser::update-preview. * Any #GtkFileFilter added using a mimetype or custom filter. If any of these features are used the regular #GtkFileChooserDialog 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 gtk_file_chooser_set_extra_widget(). * Use of custom previews by connecting to #GtkFileChooser::update-preview. * Any #GtkFileFilter 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 #GtkFileChooserDialog are not supported: * Extra widgets added with gtk_file_chooser_set_extra_widget(), unless the widget is an instance of GtkLabel, in which case the label text will be used to set the NSSavePanel message instance property. * Use of custom previews by connecting to #GtkFileChooser::update-preview. * Any #GtkFileFilter added with a custom filter. * Shortcut folders. Creates a new #GtkFileChooserNative. a new #GtkFileChooserNative Title of the native, or %NULL Transient parent of the native, or %NULL Open or save mode for the dialog text to go in the accept button, or %NULL for the default text to go in the cancel button, or %NULL for the default Retrieves the custom label text for the accept button. The custom label, or %NULL for the default. This string is owned by GTK+ and should not be modified or freed a #GtFileChooserNative Retrieves the custom label text for the cancel button. The custom label, or %NULL for the default. This string is owned by GTK+ and should not be modified or freed a #GtFileChooserNative 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. a #GtFileChooserNative custom label or %NULL for the default 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. a #GtFileChooserNative custom label or %NULL for the default The text used for the label on the accept button in the dialog, or %NULL to use the default text. The text used for the label on the cancel button in the dialog, or %NULL to use the default text. #GtkFileChooserWidget is a widget for choosing files. It exposes the #GtkFileChooser interface, and you should use the methods of this interface to interact with the widget. # CSS nodes GtkFileChooserWidget has a single CSS node with name filechooser. Creates a new #GtkFileChooserWidget. This is a file chooser widget that can be embedded in custom windows, and it is the same widget that is used by #GtkFileChooserDialog. a new #GtkFileChooserWidget Open or save mode for the widget The ::desktop-folder signal is a [keybinding signal][GtkBindingSignal] 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`. The ::down-folder signal is a [keybinding signal][GtkBindingSignal] 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`. The ::home-folder signal is a [keybinding signal][GtkBindingSignal] 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`. The ::location-popup signal is a [keybinding signal][GtkBindingSignal] 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. a string that gets put in the text entry for the file name The ::location-popup-on-paste signal is a [keybinding signal][GtkBindingSignal] 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 #GtkFileChooserWidget. The default binding for this signal is `Control + V`. The ::location-toggle-popup signal is a [keybinding signal][GtkBindingSignal] 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`. The ::places-shortcut signal is a [keybinding signal][GtkBindingSignal] 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`. The ::quick-bookmark signal is a [keybinding signal][GtkBindingSignal] 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. the number of the bookmark to switch to The ::recent-shortcut signal is a [keybinding signal][GtkBindingSignal] 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`. The ::search-shortcut signal is a [keybinding signal][GtkBindingSignal] 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`. The ::show-hidden signal is a [keybinding signal][GtkBindingSignal] 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`. The ::up-folder signal is a [keybinding signal][GtkBindingSignal] 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`. The parent class. A GtkFileFilter can be used to restrict the files being shown in a #GtkFileChooser. Files can be filtered based on their name (with gtk_file_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), or by a custom filter function (with gtk_file_filter_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 #GtkFileFilter 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 #GtkFileChooser, see gtk_file_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_file_filter_filter(). # GtkFileFilter as GtkBuildable The GtkFileFilter implementation of the GtkBuildable 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 gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern(). An example of a UI definition fragment specifying GtkFileFilter rules: |[ <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> ]| Creates a new #GtkFileFilter with no rules added to it. Such a filter doesn’t accept any files, so is not particularly useful until you add rules with gtk_file_filter_add_mime_type(), gtk_file_filter_add_pattern(), or gtk_file_filter_add_custom(). To create a filter that accepts any file, use: |[<!-- language="C" --> GtkFileFilter *filter = gtk_file_filter_new (); gtk_file_filter_add_pattern (filter, "*"); ]| a new #GtkFileFilter Deserialize a file filter from an a{sv} variant in the format produced by gtk_file_filter_to_gvariant(). a new #GtkFileFilter object an a{sv} #GVariant 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. a #GtkFileFilter bitfield of flags indicating the information that the custom filter function needs. callback function; if the function returns %TRUE, then the file will be displayed. data to pass to @func function to call to free @data when it is no longer needed. Adds a rule allowing a given mime type to @filter. A #GtkFileFilter name of a MIME type Adds a rule allowing a shell style glob to a filter. a #GtkFileFilter a shell style glob Adds a rule allowing image files in the formats supported by GdkPixbuf. a #GtkFileFilter Tests whether a file should be displayed according to @filter. The #GtkFileFilterInfo @filter_info should include the fields returned from gtk_file_filter_get_needed(). This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkFileChooser. %TRUE if the file should be displayed a #GtkFileFilter a #GtkFileFilterInfo containing information about a file. Gets the human-readable name for the filter. See gtk_file_filter_set_name(). The human-readable name of the filter, or %NULL. This value is owned by GTK+ and must not be modified or freed. a #GtkFileFilter Gets the fields that need to be filled in for the #GtkFileFilterInfo passed to gtk_file_filter_filter() This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkFileChooser. bitfield of flags indicating needed fields when calling gtk_file_filter_filter() a #GtkFileFilter 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. a #GtkFileFilter the human-readable-name for the filter, or %NULL to remove any existing name. Serialize a file filter to an a{sv} variant. a new, floating, #GVariant a #GtkFileFilter These flags indicate what parts of a #GtkFileFilterInfo struct are filled or need to be filled. the filename of the file being tested the URI for the file being tested the string that will be used to display the file in the file chooser the mime type of the file The type of function that is used with custom filters, see gtk_file_filter_add_custom(). %TRUE if the file should be displayed a #GtkFileFilterInfo that is filled according to the @needed flags passed to gtk_file_filter_add_custom() user data passed to gtk_file_filter_add_custom() A #GtkFileFilterInfo-struct is used to pass information about the tested file to gtk_file_filter_filter(). Flags indicating which of the following fields need are filled the filename of the file being tested the URI for the file being tested the string that will be used to display the file in the file chooser the mime type of the file The #GtkFixed widget is a container which can place child widgets at fixed positions and with fixed sizes, given in pixels. #GtkFixed 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 #GtkFixed, 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, #GtkFixed 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 #GtkFixed. 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 #GtkFixed, by all means use the widget. But you should be aware of the tradeoffs. See also #GtkLayout, which shares the ability to perform fixed positioning of child widgets and additionally adds custom drawing and scrollability. Creates a new #GtkFixed. a new #GtkFixed. Moves a child of a #GtkFixed container to the given position. a #GtkFixed. the child widget. the horizontal position to move the widget to. the vertical position to move the widget to. Adds a widget to a #GtkFixed container at the given position. a #GtkFixed. the widget to add. the horizontal position to place the widget at. the vertical position to place the widget at. A GtkFlowBox 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 GtkFlowBox 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 #GtkScrolledWindow to enable that. The children of a GtkFlowBox can be dynamically sorted and filtered. Although a GtkFlowBox must have only #GtkFlowBoxChild children, you can add any kind of widget to it via gtk_container_add(), and a GtkFlowBoxChild widget will automatically be inserted between the box and the widget. Also see #GtkListBox. GtkFlowBox was added in GTK+ 3.12. # CSS nodes |[<!-- language="plain" --> flowbox ├── flowboxchild │ ╰── <child> ├── flowboxchild │ ╰── <child> ┊ ╰── [rubberband] ]| GtkFlowBox uses a single CSS node with name flowbox. GtkFlowBoxChild uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used. Creates a GtkFlowBox. a new #GtkFlowBox container Select all children of @box, if the selection mode allows it. a #GtkFlowBox Unselect all children of @box, if the selection mode allows it. a #GtkFlowBox Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with gtk_flow_box_insert() or gtk_container_add()) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in GtkFlowBox. When using a model, filtering and sorting should be implemented by the model. a #GtkFlowBox the #GListModel to be bound to @box a function that creates widgets for items user data passed to @create_widget_func function for freeing @user_data Returns whether children activate on single clicks. %TRUE if children are activated on single click, %FALSE otherwise a #GtkFlowBox Gets the nth child in the @box. the child widget, which will always be a #GtkFlowBoxChild or %NULL in case no child widget with the given index exists. a #GtkFlowBox the position of the child Gets the child in the (@x, @y) position. the child widget, which will always be a #GtkFlowBoxChild or %NULL in case no child widget exists for the given x and y coordinates. a #GtkFlowBox the x coordinate of the child the y coordinate of the child Gets the horizontal spacing. the horizontal spacing a #GtkFlowBox Returns whether the box is homogeneous (all children are the same size). See gtk_box_set_homogeneous(). %TRUE if the box is homogeneous. a #GtkFlowBox Gets the maximum number of children per line. the maximum number of children per line a #GtkFlowBox Gets the minimum number of children per line. the minimum number of children per line a #GtkFlowBox Gets the vertical spacing. the vertical spacing a #GtkFlowBox Creates a list of all selected children. A #GList containing the #GtkWidget for each selected child. Free with g_list_free() when done. a #GtkFlowBox Gets the selection mode of @box. the #GtkSelectionMode a #GtkFlowBox Inserts the @widget into @box 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 gtk_container_add(). If @position is -1, or larger than the total number of children in the @box, then the @widget will be appended to the end. a #GtkFlowBox the #GtkWidget to add the position to insert @child in Updates the filtering for all children. Call this function when the result of the filter function on the @box 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. a #GtkFlowBox Updates the sorting for all children. Call this when the result of the sort function on @box is changed due to an external factor. a #GtkFlowBox Select all children of @box, if the selection mode allows it. a #GtkFlowBox Selects a single child of @box, if the selection mode allows it. a #GtkFlowBox a child of @box Calls a function for each selected child. Note that the selection cannot be modified from within this function. a #GtkFlowBox the function to call for each selected child user data to pass to the function If @single is %TRUE, children will be activated when you click on them, otherwise you need to double-click. a #GtkFlowBox %TRUE to emit child-activated on a single click Sets the horizontal space to add between children. See the #GtkFlowBox:column-spacing property. a #GtkFlowBox the spacing to use By setting a filter function on the @box 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 gtk_flow_box_child_changed()) or when gtk_flow_box_invalidate_filter() is called. Note that using a filter function is incompatible with using a model (see gtk_flow_box_bind_model()). a #GtkFlowBox callback that lets you filter which children to show user data passed to @filter_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment, and gtk_flow_box_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. a #GtkFlowBox an adjustment which should be adjusted when the focus is moved among the descendents of @container Sets the #GtkFlowBox:homogeneous property of @box, controlling whether or not all children of @box are given equal space in the box. a #GtkFlowBox %TRUE to create equal allotments, %FALSE for variable allotments Sets the maximum number of children to request and allocate space for in @box’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. a #GtkFlowBox the maximum number of children per line Sets the minimum number of children to line up in @box’s orientation before flowing. a #GtkFlowBox the minimum number of children per line Sets the vertical space to add between children. See the #GtkFlowBox:row-spacing property. a #GtkFlowBox the spacing to use Sets how selection works in @box. See #GtkSelectionMode for details. a #GtkFlowBox the new selection mode By setting a sort function on the @box, 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 gtk_flow_box_child_changed()) and when gtk_flow_box_invalidate_sort() is called. Note that using a sort function is incompatible with using a model (see gtk_flow_box_bind_model()). a #GtkFlowBox the sort function user data passed to @sort_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment, and gtk_flow_box_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. a #GtkFlowBox an adjustment which should be adjusted when the focus is moved among the descendents of @container Unselect all children of @box, if the selection mode allows it. a #GtkFlowBox Unselects a single child of @box, if the selection mode allows it. a #GtkFlowBox a child of @box Determines whether children can be activated with a single click, or require a double-click. The amount of horizontal space between two children. Determines whether all children should be allocated the same size. The maximum amount of children to request space for consecutively in the given orientation. 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. The amount of vertical space between two children. The selection mode used by the flow box. The ::activate-cursor-child signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the @box. The ::child-activated signal is emitted when a child has been activated by the user. the child that is activated The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] 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 %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the granularity fo the move, as a #GtkMovementStep the number of @step units to move The ::select-all signal is a [keybinding signal][GtkBindingSignal] 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. The ::selected-children-changed signal is emitted when the set of selected children changes. Use gtk_flow_box_selected_foreach() or gtk_flow_box_get_selected_children() to obtain the selected children. The ::toggle-cursor-child signal is a [keybinding signal][GtkBindingSignal] which toggles the selection of the child that has the focus. The default binding for this signal is Ctrl-Space. The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] 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. Creates a new #GtkFlowBoxChild, to be used as a child of a #GtkFlowBox. a new #GtkFlowBoxChild Marks @child 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 gtk_flow_box_child_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 gtk_flow_box_invalidate_sort() on any model change, but that is more expensive. a #GtkFlowBoxChild Gets the current index of the @child in its #GtkFlowBox container. the index of the @child, or -1 if the @child is not in a flow box. a #GtkFlowBoxChild Returns whether the @child is currently selected in its #GtkFlowBox container. %TRUE if @child is selected a #GtkFlowBoxChild The ::activate signal is emitted when the user activates a child widget in a #GtkFlowBox, either by clicking or double-clicking, or by using the Space or Enter key. While this signal is used as a [keybinding signal][GtkBindingSignal], it can be used by applications for their own purposes. a #GtkFlowBox a #GtkFlowBox Called for flow boxes that are bound to a #GListModel with gtk_flow_box_bind_model() for each item that gets added to the model. a #GtkWidget that represents @item the item from the model for which to create a widget for user data from gtk_flow_box_bind_model() A function that will be called whenrever a child changes or is added. It lets you control if the child should be visible or not. %TRUE if the row should be visible, %FALSE otherwise a #GtkFlowBoxChild that may be filtered user data A function used by gtk_flow_box_selected_foreach(). It will be called on every selected child of the @box. a #GtkFlowBox a #GtkFlowBoxChild user data A function to compare two children to determine which should come first. < 0 if @child1 should be before @child2, 0 if the are equal, and > 0 otherwise the first child the second child user data The #GtkFontButton 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 GtkFontButton has a single CSS node with name button and style class .font. Creates a new font picker widget. a new font picker widget. Creates a new font picker widget. a new font picker widget. Name of font to display in font chooser dialog 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_font_description_from_string() . If you’re interested in peeking certain values (family name, style, size, weight) just query these properties from the #PangoFontDescription object. Use gtk_font_chooser_get_font() instead an internal copy of the font name which must not be freed. a #GtkFontButton Returns whether the font size will be shown in the label. whether the font size will be shown in the label. a #GtkFontButton Returns whether the name of the font style will be shown in the label. whether the font style will be shown in the label. a #GtkFontButton Retrieves the title of the font chooser dialog. an internal copy of the title string which must not be freed. a #GtkFontButton Returns whether the selected font is used in the label. whether the selected font is used in the label. a #GtkFontButton Returns whether the selected size is used in the label. whether the selected size is used in the label. a #GtkFontButton Sets or updates the currently-displayed font in font picker dialog. Use gtk_font_chooser_set_font() instead %TRUE a #GtkFontButton Name of font to display in font chooser dialog If @show_size is %TRUE, the font size will be displayed along with the name of the selected font. a #GtkFontButton %TRUE if font size should be displayed in dialog. If @show_style is %TRUE, the font style will be displayed along with name of the selected font. a #GtkFontButton %TRUE if font style should be displayed in label. Sets the title for the font chooser dialog. a #GtkFontButton a string containing the font chooser dialog title If @use_font is %TRUE, the font name will be written using the selected font. a #GtkFontButton If %TRUE, font name will be written using font chosen. If @use_size is %TRUE, the font name will be written using the selected size. a #GtkFontButton If %TRUE, font name will be written using the selected size. The name of the currently selected font. Use the #GtkFontChooser::font property instead 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. 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. The title of the font chooser dialog. If this property is set to %TRUE, the label will be drawn in the selected font. If this property is set to %TRUE, the label will be drawn with the selected font size. The ::font-set signal is emitted when the user selects a font. When handling this signal, use gtk_font_chooser_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. #GtkFontChooser is an interface that can be implemented by widgets displaying the list of fonts. In GTK+, the main objects that implement this interface are #GtkFontChooserWidget, #GtkFontChooserDialog and #GtkFontButton. The GtkFontChooser interface has been introducted in GTK+ 3.2. Gets the #PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. A #PangoFontFace representing the selected font group details, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the #PangoFontFamily representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. A #PangoFontFamily representing the selected font family, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the custom font map of this font chooser widget, or %NULL if it does not have one. a #PangoFontMap, or %NULL a #GtkFontChooser The selected font size. A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontChooser Adds a filter function that decides which fonts to display in the font chooser. a #GtkFontChooser a #GtkFontFilterFunc, or %NULL data to pass to @filter function to call to free @data when it is no longer needed 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. |[<!-- language="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: |[ context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ]| a #GtkFontChooser a #PangoFontMap Gets the currently-selected font name. Note that this can be a different string than what you set with gtk_font_chooser_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_font_description_equal() if you want to compare two font descriptions. A string with the name of the current font, or %NULL if no font is selected. You must free this string with g_free(). a #GtkFontChooser Gets the currently-selected font. Note that this can be a different string than what you set with gtk_font_chooser_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_font_description_equal() if you want to compare two font descriptions. A #PangoFontDescription for the current font, or %NULL if no font is selected. a #GtkFontChooser Gets the #PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. A #PangoFontFace representing the selected font group details, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the #PangoFontFamily representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. A #PangoFontFamily representing the selected font family, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser Gets the currently-selected font features. the currently selected font features a #GtkFontChooser Gets the custom font map of this font chooser widget, or %NULL if it does not have one. a #PangoFontMap, or %NULL a #GtkFontChooser The selected font size. A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontChooser Gets the language that is used for font features. the currently selected language a #GtkFontChooser Returns the current level of granularity for selecting fonts. the current granularity level a #GtkFontChooser Gets the text displayed in the preview area. the text displayed in the preview area a #GtkFontChooser Returns whether the preview entry is shown or not. %TRUE if the preview entry is shown or %FALSE if it is hidden. a #GtkFontChooser Adds a filter function that decides which fonts to display in the font chooser. a #GtkFontChooser a #GtkFontFilterFunc, or %NULL data to pass to @filter function to call to free @data when it is no longer needed Sets the currently-selected font. a #GtkFontChooser a font name like “Helvetica 12” or “Times Bold 18” Sets the currently-selected font from @font_desc. a #GtkFontChooser a #PangoFontDescription 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. |[<!-- language="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: |[ context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ]| a #GtkFontChooser a #PangoFontMap Sets the language to use for font features. a #GtkFontChooser a language Sets the desired level of granularity for selecting fonts. a #GtkFontChooser the desired level of granularity Sets the text displayed in the preview area. The @text is used to show how the selected font looks. a #GtkFontChooser the text to display in the preview area Shows or hides the editable preview entry. a #GtkFontChooser whether to show the editable preview entry or not The font description as a string, e.g. "Sans Italic 12". The font description as a #PangoFontDescription. The selected font features, in a format that is compatible with CSS and with Pango attributes. The language for which the #GtkFontChooser:font-features were selected, in a format that is compatible with CSS and with Pango attributes. The level of granularity to offer for selecting fonts. The string with which to preview the font. Whether to show an entry to change the preview text. 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. the font name The #GtkFontChooserDialog widget is a dialog for selecting a font. It implements the #GtkFontChooser interface. # GtkFontChooserDialog as GtkBuildable The GtkFontChooserDialog implementation of the #GtkBuildable interface exposes the buttons with the names “select_button” and “cancel_button”. Creates a new #GtkFontChooserDialog. a new #GtkFontChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL The parent class. A #PangoFontFamily representing the selected font family, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser A #PangoFontFace representing the selected font group details, or %NULL. The returned object is owned by @fontchooser and must not be modified or freed. a #GtkFontChooser A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontChooser a #GtkFontChooser a #GtkFontFilterFunc, or %NULL data to pass to @filter function to call to free @data when it is no longer needed a #GtkFontChooser a #PangoFontMap a #PangoFontMap, or %NULL a #GtkFontChooser 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. Allow selecting a font family Allow selecting a specific font face Allow selecting a specific font size Allow selecting specific OpenType font features The #GtkFontChooserWidget widget lists the available fonts, styles and sizes, allowing the user to select a font. It is used in the #GtkFontChooserDialog widget to provide a dialog box for selecting fonts. To set the font which is initially selected, use gtk_font_chooser_set_font() or gtk_font_chooser_set_font_desc(). To get the selected font use gtk_font_chooser_get_font() or gtk_font_chooser_get_font_desc(). To change the text which is shown in the preview area, use gtk_font_chooser_set_preview_text(). # CSS nodes GtkFontChooserWidget has a single CSS node with name fontchooser. Creates a new #GtkFontChooserWidget. a new #GtkFontChooserWidget 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. The parent class. The type of function that is used for deciding what fonts get shown in a #GtkFontChooser. See gtk_font_chooser_set_filter_func(). %TRUE if the font should be displayed a #PangoFontFamily a #PangoFontFace belonging to @family user data passed to gtk_font_chooser_set_filter_func() Creates a new #GtkFontSelection. Use #GtkFontChooserWidget instead a new #GtkFontSelection Gets the #PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc). Use #GtkFontChooser A #PangoFontFace representing the selected font group details. The returned object is owned by @fontsel and must not be modified or freed. a #GtkFontSelection This returns the #GtkTreeView which lists all styles available for the selected font. For example, “Regular”, “Bold”, etc. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Gets the #PangoFontFamily representing the selected font family. Use #GtkFontChooser A #PangoFontFamily representing the selected font family. Font families are a collection of font faces. The returned object is owned by @fontsel and must not be modified or freed. a #GtkFontSelection This returns the #GtkTreeView that lists font families, for example, “Sans”, “Serif”, etc. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Gets the currently-selected font name. Note that this can be a different string than what you set with gtk_font_selection_set_font_name(), as the font selection 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_font_description_equal() if you want to compare two font descriptions. Use #GtkFontChooser A string with the name of the current font, or %NULL if no font is selected. You must free this string with g_free(). a #GtkFontSelection This returns the #GtkEntry used to display the font as a preview. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Gets the text displayed in the preview area. Use #GtkFontChooser the text displayed in the preview area. This string is owned by the widget and should not be modified or freed a #GtkFontSelection The selected font size. Use #GtkFontChooser A n integer representing the selected font size, or -1 if no font size is selected. a #GtkFontSelection This returns the #GtkEntry used to allow the user to edit the font number manually instead of selecting it from the list of font sizes. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection This returns the #GtkTreeView used to list font sizes. Use #GtkFontChooser A #GtkWidget that is part of @fontsel a #GtkFontSelection Sets the currently-selected font. Note that the @fontsel needs to know the screen in which it will appear for this to work; this can be guaranteed by simply making sure that the @fontsel is inserted in a toplevel window before you call this function. Use #GtkFontChooser %TRUE if the font could be set successfully; %FALSE if no such font exists or if the @fontsel doesn’t belong to a particular screen yet. a #GtkFontSelection a font name like “Helvetica 12” or “Times Bold 18” Sets the text displayed in the preview area. The @text is used to show how the selected font looks. Use #GtkFontChooser a #GtkFontSelection the text to display in the preview area Creates a new #GtkFontSelectionDialog. Use #GtkFontChooserDialog a new #GtkFontSelectionDialog the title of the dialog window Gets the “Cancel” button. Use #GtkFontChooserDialog the #GtkWidget used in the dialog for the “Cancel” button. a #GtkFontSelectionDialog Gets the currently-selected font name. Note that this can be a different string than what you set with gtk_font_selection_dialog_set_font_name(), as the font selection 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_font_description_equal() if you want to compare two font descriptions. Use #GtkFontChooserDialog A string with the name of the current font, or %NULL if no font is selected. You must free this string with g_free(). a #GtkFontSelectionDialog Retrieves the #GtkFontSelection widget embedded in the dialog. Use #GtkFontChooserDialog the embedded #GtkFontSelection a #GtkFontSelectionDialog Gets the “OK” button. Use #GtkFontChooserDialog the #GtkWidget used in the dialog for the “OK” button. a #GtkFontSelectionDialog Gets the text displayed in the preview area. Use #GtkFontChooserDialog the text displayed in the preview area. This string is owned by the widget and should not be modified or freed a #GtkFontSelectionDialog Sets the currently selected font. Use #GtkFontChooserDialog %TRUE if the font selected in @fsd is now the @fontname specified, %FALSE otherwise. a #GtkFontSelectionDialog a font name like “Helvetica 12” or “Times Bold 18” Sets the text displayed in the preview area. Use #GtkFontChooserDialog a #GtkFontSelectionDialog the text to display in the preview area 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 gtk_frame_set_label_align(). # GtkFrame as GtkBuildable The GtkFrame implementation of the GtkBuildable 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 GtkFrame: |[ <object class="GtkFrame"> <child type="label"> <object class="GtkLabel" id="frame-label"/> </child> <child> <object class="GtkEntry" id="frame-content"/> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> frame ├── border[.flat] ├── <label widget> ╰── <child> ]| GtkFrame 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 gtk_frame_set_shadow_type() with %GTK_SHADOW_NONE to add the “.flat” class or any other shadow type to remove it. Creates a new #GtkFrame, with optional label @label. If @label is %NULL, the label is omitted. a new #GtkFrame widget the text to use as the label of the frame If the frame’s label widget is a #GtkLabel, returns the text in the label widget. (The frame will have a #GtkLabel for the label widget if a non-%NULL argument was passed to gtk_frame_new().) the text in the label, or %NULL if there was no label widget or the lable widget was not a #GtkLabel. This string is owned by GTK+ and must not be modified or freed. a #GtkFrame Retrieves the X and Y alignment of the frame’s label. See gtk_frame_set_label_align(). a #GtkFrame location to store X alignment of frame’s label, or %NULL location to store X alignment of frame’s label, or %NULL Retrieves the label widget for the frame. See gtk_frame_set_label_widget(). the label widget, or %NULL if there is none. a #GtkFrame Retrieves the shadow type of the frame. See gtk_frame_set_shadow_type(). the current shadow type of the frame. a #GtkFrame Removes the current #GtkFrame:label-widget. If @label is not %NULL, creates a new #GtkLabel with that text and adds it as the #GtkFrame:label-widget. a #GtkFrame the text to use as the label of the frame Sets the alignment of the frame widget’s label. The default values for a newly created frame are 0.0 and 0.5. a #GtkFrame 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. 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. Sets the #GtkFrame:label-widget for the frame. This is the widget that will appear embedded in the top edge of the frame as a title. a #GtkFrame the new label widget Sets the #GtkFrame:shadow-type for @frame, i.e. whether it is drawn without (%GTK_SHADOW_NONE) or with (other values) a visible border. Values other than %GTK_SHADOW_NONE are treated identically by GtkFrame. The chosen type is applied by removing or adding the .flat class to the CSS node named border. a #GtkFrame the new #GtkShadowType The parent class. #GtkGLArea is a widget that allows drawing with OpenGL. #GtkGLArea sets up its own #GdkGLContext 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 #GtkGLArea::render signal, or subclass #GtkGLArea and override the @GtkGLAreaClass.render() virtual function. The #GtkGLArea widget ensures that the #GdkGLContext 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 GtkGLArea ## The simplest way to draw using OpenGL commands in a #GtkGLArea is to create a widget instance and connect to the #GtkGLArea::render signal: |[<!-- language="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 #GtkGLArea is ready for you to draw its content: |[<!-- language="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 #GtkWidget::realize signal; you can use the #GtkWidget::unrealize signal to clean up. Since the #GdkGLContext creation and initialization may fail, you will need to check for errors, using gtk_gl_area_get_error(). An example of how to safely initialize the GL state is: |[<!-- language="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 #GdkGLContext you should use the #GtkGLArea::create-context signal. Creates a new #GtkGLArea widget. a new #GtkGLArea Ensures that the @area framebuffer object is made the current draw and read target, and that all the required buffers for the @area are created and bound to the frambuffer. This function is automatically called before emitting the #GtkGLArea::render signal, and doesn't normally need to be called by application code. a #GtkGLArea Returns whether the area is in auto render mode or not. %TRUE if the @area is auto rendering, %FALSE otherwise a #GtkGLArea Retrieves the #GdkGLContext used by @area. the #GdkGLContext a #GtkGLArea Gets the current error set on the @area. the #GError or %NULL a #GtkGLArea Returns whether the area has an alpha component. %TRUE if the @area has an alpha component, %FALSE otherwise a #GtkGLArea Returns whether the area has a depth buffer. %TRUE if the @area has a depth buffer, %FALSE otherwise a #GtkGLArea Returns whether the area has a stencil buffer. %TRUE if the @area has a stencil buffer, %FALSE otherwise a #GtkGLArea Retrieves the required version of OpenGL set using gtk_gl_area_set_required_version(). a #GtkGLArea return location for the required major version return location for the required minor version Retrieves the value set by gtk_gl_area_set_use_es(). %TRUE if the #GtkGLArea should create an OpenGL ES context and %FALSE otherwise a #GtkGLArea Ensures that the #GdkGLContext used by @area is associated with the #GtkGLArea. This function is automatically called before emitting the #GtkGLArea::render signal, and doesn't normally need to be called by application code. a #GtkGLArea Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget, ensuring that the #GtkGLArea::render signal is emitted during the draw. This is only needed when the gtk_gl_area_set_auto_render() has been called with a %FALSE value. The default behaviour is to emit #GtkGLArea::render on each draw. a #GtkGLArea If @auto_render is %TRUE the #GtkGLArea::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 gtk_gl_area_queue_render() must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw. a #GtkGLArea a boolean Sets an error on the area which will be shown instead of the GL rendering. This is useful in the #GtkGLArea::create-context signal if GL context creation fails. a #GtkGLArea a new #GError, or %NULL to unset the error 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. a #GtkGLArea %TRUE to add an alpha component If @has_depth_buffer is %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none. a #GtkGLArea %TRUE to add a depth 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. a #GtkGLArea %TRUE to add a stencil buffer 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. a #GtkGLArea the major version the minor version Sets whether the @area should create an OpenGL or an OpenGL ES context. You should check the capabilities of the #GdkGLContext before drawing with either API. a #GtkGLArea whether to use OpenGL or OpenGL ES If set to %TRUE the #GtkGLArea::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 gtk_gl_area_queue_render() must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw. The #GdkGLContext used by the #GtkGLArea widget. The #GtkGLArea widget is responsible for creating the #GdkGLContext instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers. 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. If set to %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. If set to %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. If set to %TRUE the widget will try to create a #GdkGLContext using OpenGL ES instead of OpenGL. See also: gdk_gl_context_set_use_es() 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 gtk_gl_area_set_error() to register a more detailed error of how the construction failed. a newly created #GdkGLContext; the #GtkGLArea widget will take ownership of the returned value. The ::render signal is emitted every time the contents of the #GtkGLArea 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. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkGLContext used by @area 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. the width of the viewport the height of the viewport The `GtkGLAreaClass` structure contains only private data. #GtkGesture 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 %NULL #GdkEventSequence value for these). The number of touches that a #GtkGesture need to be recognized is controlled by the #GtkGesture: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 #GtkGesture::check signal regularly on input events until the gesture is recognized, the criteria to consider a gesture as "recognized" is left to #GtkGesture subclasses. A recognized gesture will then emit the following signals: - #GtkGesture::begin when the gesture is recognized. - A number of #GtkGesture::update, whenever an input event is processed. - #GtkGesture::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 gtk_event_controller_set_propagation_phase(), or feed those manually through gtk_event_controller_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 #GtkWidget::button-press-event, #GtkWidget::button-release-event, #GtkWidget::touch-event, etc signals. Gestures with the %GTK_PHASE_TARGET phase are fed events from the default #GtkWidget::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 gtk_gesture_group(), grouped gestures synchronize the state of sequences, so calling gtk_gesture_set_sequence_state() on one will effectively propagate the state throughout the group. By default, all sequences start out in the #GTK_EVENT_SEQUENCE_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 #GTK_EVENT_SEQUENCE_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 #GTK_EVENT_SEQUENCE_CLAIMED state, the gesture group will grab all interaction on the sequence, by: - Setting the same sequence to #GTK_EVENT_SEQUENCE_DENIED on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain. - calling #GtkGesture::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 #GTK_EVENT_SEQUENCE_CLAIMED on #GDK_TOUCH_BEGIN/#GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies #GTK_PHASE_CAPTURE), one similar event will emulated if the sequence changes to #GTK_EVENT_SEQUENCE_DENIED. This way event coherence is preserved before event propagation is unstopped again. Sequence states can't be changed freely, see gtk_gesture_set_sequence_state() to know about the possible lifetimes of a #GdkEventSequence. ## Touchpad gestures On the platforms that support it, #GtkGesture will handle transparently touchpad gesture events. The only precautions users of #GtkGesture should do to enable this support are: - Enabling %GDK_TOUCHPAD_GESTURE_MASK on their #GdkWindows - If the gesture has %GTK_PHASE_NONE, ensuring events of type %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the #GtkGesture If there are touch sequences being currently handled by @gesture, 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. %TRUE if there are active touches, %FALSE otherwise a #GtkGesture bounding box containing all active touches. If there are touch sequences being currently handled by @gesture, 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. %FALSE if no active touches are present, %TRUE otherwise a #GtkGesture X coordinate for the bounding box center Y coordinate for the bounding box center Returns the master #GdkDevice that is currently operating on @gesture, or %NULL if the gesture is not being interacted. a #GdkDevice, or %NULL a #GtkGesture Returns all gestures in the group of @gesture The list of #GtkGestures, free with g_list_free() a #GtkGesture 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 @gesture. If in doubt, you should make a copy of the event. The last event from @sequence a #GtkGesture a #GdkEventSequence Returns the #GdkEventSequence that was last updated on @gesture. The last updated sequence a #GtkGesture If @sequence is currently being interpreted by @gesture, 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. %TRUE if @sequence is currently interpreted a #GtkGesture a #GdkEventSequence, or %NULL for pointer events return location for X axis of the sequence coordinates return location for Y axis of the sequence coordinates Returns the @sequence state, as seen by @gesture. The sequence state in @gesture a #GtkGesture a #GdkEventSequence Returns the list of #GdkEventSequences currently being interpreted by @gesture. 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 g_list_free() a #GtkGesture Returns the user-defined window that receives the events handled by @gesture. See gtk_gesture_set_window() for more information. the user defined window, or %NULL if none a #GtkGesture Adds @gesture to the same group than @group_gesture. 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 gtk_gesture_set_sequence_state(), on one will transfer the same value to the others. Groups also perform an "implicit grabbing" of sequences, if a #GdkEventSequence state is set to #GTK_EVENT_SEQUENCE_CLAIMED on one group, every other gesture group attached to the same #GtkWidget will switch the state for that sequence to #GTK_EVENT_SEQUENCE_DENIED. #GtkGesture to group @gesture with a #GtkGesture Returns %TRUE if @gesture is currently handling events corresponding to @sequence. %TRUE if @gesture is handling @sequence, %FALSE otherwise a #GtkGesture a #GdkEventSequence or %NULL Returns %TRUE if the gesture is currently active. A gesture is active meanwhile there are touch sequences interacting with it. %TRUE if gesture is active a #GtkGesture Returns %TRUE if both gestures pertain to the same group. whether the gestures are grouped a #GtkGesture another #GtkGesture Returns %TRUE if the gesture is currently recognized. A gesture is recognized if there are as many interacting touch sequences as required by @gesture, and #GtkGesture::check returned %TRUE for the sequences being currently interpreted. %TRUE if gesture is recognized a #GtkGesture Sets the state of @sequence in @gesture. Sequences start in state #GTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in state #GTK_EVENT_SEQUENCE_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 #GtkGesture::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: |[ 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. %TRUE if @sequence is handled by @gesture, and the state is changed successfully a #GtkGesture a #GdkEventSequence the sequence state Sets the state of all sequences that @gesture is currently interacting with. See gtk_gesture_set_sequence_state() for more details on sequence states. %TRUE if the state of at least one sequence was changed successfully a #GtkGesture the sequence state Sets a specific window to receive events about, so @gesture will effectively handle only events targeting @window, or a child of it. @window must pertain to gtk_event_controller_get_widget(). a #GtkGesture a #GdkWindow, or %NULL Separates @gesture into an isolated group. a #GtkGesture The number of touch points that trigger recognition on this gesture, If non-%NULL, the gesture will only listen for events that happen on this #GdkWindow, or a child of it. This signal is emitted when the gesture is recognized. This means the number of touch sequences matches #GtkGesture:n-points, and the #GtkGesture::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. the #GdkEventSequence that made the gesture to be recognized This signal is emitted whenever a sequence is cancelled. This usually happens on active touches when gtk_event_controller_reset() is called on @gesture (manually, due to grabs...), or the individual @sequence was claimed by parent widgets' controllers (see gtk_gesture_set_sequence_state()). @gesture must forget everything about @sequence as a reaction to this signal. the #GdkEventSequence that was cancelled This signal is emitted when @gesture either stopped recognizing the event sequences as something to be handled (the #GtkGesture::check handler returned %FALSE), or the number of touch sequences became higher or lower than #GtkGesture: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 #GtkGesture:n-points). This situation may be detected by checking through gtk_gesture_handles_sequence(). the #GdkEventSequence that made gesture recognition to finish This signal is emitted whenever a sequence state changes. See gtk_gesture_set_sequence_state() to know more about the expectable sequence lifetimes. the #GdkEventSequence that was cancelled the new sequence state 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. the #GdkEventSequence that was updated #GtkGestureDrag is a #GtkGesture implementation that recognizes drag operations. The drag operation itself can be tracked throught the #GtkGestureDrag::drag-begin, #GtkGestureDrag::drag-update and #GtkGestureDrag::drag-end signals, or the relevant coordinates be extracted through gtk_gesture_drag_get_offset() and gtk_gesture_drag_get_start_point(). Returns a newly created #GtkGesture that recognizes drags. a newly created #GtkGestureDrag a #GtkWidget If the @gesture 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. %TRUE if the gesture is active a #GtkGesture X offset for the current point Y offset for the current point If the @gesture is active, this function returns %TRUE and fills in @x and @y with the drag start coordinates, in window-relative coordinates. %TRUE if the gesture is active a #GtkGesture X coordinate for the drag start point Y coordinate for the drag start point This signal is emitted whenever dragging starts. X coordinate, relative to the widget allocation Y coordinate, relative to the widget allocation This signal is emitted whenever the dragging is finished. X offset, relative to the start point Y offset, relative to the start point This signal is emitted whenever the dragging point moves. X offset, relative to the start point Y offset, relative to the start point #GtkGestureLongPress is a #GtkGesture implementation able to recognize long presses, triggering the #GtkGestureLongPress::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 #GtkGestureLongPress::cancelled signal will be emitted. Returns a newly created #GtkGesture that recognizes long presses. a newly created #GtkGestureLongPress a #GtkWidget This signal is emitted whenever a press moved too far, or was released before #GtkGestureLongPress::pressed happened. This signal is emitted whenever a press goes unmoved/unreleased longer than what the GTK+ defaults tell. the X coordinate where the press happened, relative to the widget allocation the Y coordinate where the press happened, relative to the widget allocation #GtkGestureMultiPress is a #GtkGesture implementation able to recognize multiple clicks on a nearby zone, which can be listened for through the #GtkGestureMultiPress::pressed signal. Whenever time or distance between clicks exceed the GTK+ defaults, #GtkGestureMultiPress::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 gtk_gesture_multi_press_set_area(), so any click happening outside that area is considered to be a first click of its own. Returns a newly created #GtkGesture that recognizes single and multiple presses. a newly created #GtkGestureMultiPress a #GtkWidget If an area was set through gtk_gesture_multi_press_set_area(), this function will return %TRUE and fill in @rect with the press area. See gtk_gesture_multi_press_set_area() for more details on what the press area represents. %TRUE if @rect was filled with the press area a #GtkGestureMultiPress return location for the press area If @rect is non-%NULL, 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 %NULL, 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. a #GtkGestureMultiPress rectangle to receive coordinates on This signal is emitted whenever a button or touch press happens. how many touch/button presses happened with this one The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates 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 #GtkGestureMultiPress::stopped may have been emitted between the press and its release, @n_press will only start over at the next press. number of press that is paired with this release The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates This signal is emitted whenever any time/distance threshold has been exceeded. #GtkGesturePan is a #GtkGesture implementation able to recognize pan gestures, those are drags that are locked to happen along one axis. The axis that a #GtkGesturePan handles is defined at construct time, and can be changed through gtk_gesture_pan_set_orientation(). When the gesture starts to be recognized, #GtkGesturePan 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 #GtkGesturePan::pan signal will be emitted as input events are received, containing the offset in the given axis. Returns a newly created #GtkGesture that recognizes pan gestures. a newly created #GtkGesturePan a #GtkWidget expected orientation Returns the orientation of the pan gestures that this @gesture expects. the expected orientation for pan gestures A #GtkGesturePan Sets the orientation to be expected on pan gestures. A #GtkGesturePan expected orientation The expected orientation of pan gestures. This signal is emitted once a panning gesture along the expected axis is detected. current direction of the pan gesture Offset along the gesture orientation #GtkGestureRotate is a #GtkGesture implementation able to recognize 2-finger rotations, whenever the angle between both handled sequences changes, the #GtkGestureRotate::angle-changed signal is emitted. Returns a newly created #GtkGesture that recognizes 2-touch rotation gestures. a newly created #GtkGestureRotate a #GtkWidget If @gesture is active, this function returns the angle difference in radians since the gesture was first recognized. If @gesture is not active, 0 is returned. the angle delta in radians a #GtkGestureRotate This signal is emitted when the angle between both tracked points changes. Current angle in radians Difference with the starting angle, in radians #GtkGestureSingle is a subclass of #GtkGesture, 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 gtk_gesture_single_get_current_sequence() while the gesture is being interacted with. By default gestures react to both %GDK_BUTTON_PRIMARY and touch events, gtk_gesture_single_set_touch_only() can be used to change the touch behavior. Callers may also specify a different mouse button number to interact with through gtk_gesture_single_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 gtk_gesture_single_get_current_button(). Returns the button number @gesture listens for, or 0 if @gesture reacts to any button press. The button number, or 0 for any button a #GtkGestureSingle Returns the button number currently interacting with @gesture, or 0 if there is none. The current button number a #GtkGestureSingle Returns the event sequence currently interacting with @gesture. This is only meaningful if gtk_gesture_is_active() returns %TRUE. the current sequence a #GtkGestureSingle Gets whether a gesture is exclusive. For more information, see gtk_gesture_single_set_exclusive(). Whether the gesture is exclusive a #GtkGestureSingle Returns %TRUE if the gesture is only triggered by touch events. %TRUE if the gesture only handles touch events a #GtkGestureSingle Sets the button number @gesture listens to. If non-0, every button press from a different button number will be ignored. Touch events implicitly match with button 1. a #GtkGestureSingle button number to listen to, or 0 for any button Sets whether @gesture 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. a #GtkGestureSingle %TRUE to make @gesture exclusive If @touch_only is %TRUE, @gesture will only handle events of type #GDK_TOUCH_BEGIN, #GDK_TOUCH_UPDATE or #GDK_TOUCH_END. If %FALSE, mouse events will be handled too. a #GtkGestureSingle whether @gesture handles only touch events Mouse button number to listen to, or 0 to listen for any button. Whether the gesture is exclusive. Exclusive gestures only listen to pointer and pointer emulated events. Whether the gesture handles only touch events. #GtkGestureStylus is a #GtkGesture implementation specific to stylus input. The provided signals just provide the basic information Creates a new #GtkGestureStylus. a newly created stylus gesture a #GtkWidget Returns the current values for the requested @axes. This function must be called from either the #GtkGestureStylus:down, #GtkGestureStylus:motion, #GtkGestureStylus:up or #GtkGestureStylus:proximity signals. #TRUE if there is a current value for the axes a GtkGestureStylus array of requested axes, terminated with #GDK_AXIS_IGNORE return location for the axis values Returns the current value for the requested @axis. This function must be called from either the #GtkGestureStylus:down, #GtkGestureStylus:motion, #GtkGestureStylus:up or #GtkGestureStylus:proximity signals. #TRUE if there is a current value for the axis a #GtkGestureStylus requested device axis return location for the axis value Returns the #GdkDeviceTool currently driving input through this gesture. This function must be called from either the #GtkGestureStylus::down, #GtkGestureStylus::motion, #GtkGestureStylus::up or #GtkGestureStylus::proximity signal handlers. The current stylus tool a #GtkGestureStylus #GtkGestureSwipe is a #GtkGesture implementation able to recognize swipes, after a press/move/.../move/release sequence happens, the #GtkGestureSwipe::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, gtk_gesture_swipe_get_velocity() can be called on eg. a #GtkGesture::update handler. All velocities are reported in pixels/sec units. Returns a newly created #GtkGesture that recognizes swipes. a newly created #GtkGestureSwipe a #GtkWidget 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. whether velocity could be calculated a #GtkGestureSwipe return value for the velocity in the X axis, in pixels/sec return value for the velocity in the Y axis, in pixels/sec This signal is emitted when the recognized gesture is finished, velocity and direction are a product of previously recorded events. velocity in the X axis, in pixels/sec velocity in the Y axis, in pixels/sec #GtkGestureZoom is a #GtkGesture implementation able to recognize pinch/zoom gestures, whenever the distance between both tracked sequences changes, the #GtkGestureZoom::scale-changed signal is emitted to report the scale factor. Returns a newly created #GtkGesture that recognizes zoom in/out gestures (usually known as pinch/zoom). a newly created #GtkGestureZoom a #GtkWidget If @gesture is active, this function returns the zooming difference since the gesture was recognized (hence the starting point is considered 1:1). If @gesture is not active, 1 is returned. the scale delta a #GtkGestureZoom This signal is emitted whenever the distance between both tracked sequences changes. Scale delta, taking the initial state as 1:1 GtkGradient is a boxed type that represents a gradient. It is the result of parsing a [gradient expression][gtkcssprovider-gradients]. To obtain the gradient represented by a GtkGradient, it has to be resolved with gtk_gradient_resolve(), which replaces all symbolic color references by the colors they refer to (in a given context) and constructs a #cairo_pattern_t value. It is not normally necessary to deal directly with #GtkGradients, since they are mostly used behind the scenes by #GtkStyleContext and #GtkCssProvider. #GtkGradient is deprecated. It was used internally by GTK’s CSS engine to represent gradients. As its handling is not conforming to modern web standards, it is not used anymore. If you want to use gradients in your own code, please use Cairo directly. Creates a new linear gradient along the line defined by (x0, y0) and (x1, y1). Before using the gradient a number of stop colors must be added through gtk_gradient_add_color_stop(). #GtkGradient is deprecated. A newly created #GtkGradient X coordinate of the starting point Y coordinate of the starting point X coordinate of the end point Y coordinate of the end point Creates a new radial gradient along the two circles defined by (x0, y0, radius0) and (x1, y1, radius1). Before using the gradient a number of stop colors must be added through gtk_gradient_add_color_stop(). #GtkGradient is deprecated. A newly created #GtkGradient X coordinate of the start circle Y coordinate of the start circle radius of the start circle X coordinate of the end circle Y coordinate of the end circle radius of the end circle Adds a stop color to @gradient. #GtkGradient is deprecated. a #GtkGradient offset for the color stop color to use Increases the reference count of @gradient. #GtkGradient is deprecated. The same @gradient a #GtkGradient If @gradient is resolvable, @resolved_gradient will be filled in with the resolved gradient as a cairo_pattern_t, and %TRUE will be returned. Generally, if @gradient can’t be resolved, it is due to it being defined on top of a named color that doesn't exist in @props. #GtkGradient is deprecated. %TRUE if the gradient has been resolved a #GtkGradient #GtkStyleProperties to use when resolving named colors return location for the resolved pattern Creates a string representation for @gradient that is suitable for using in GTK CSS files. #GtkGradient is deprecated. A string representation for @gradient the gradient to print Decreases the reference count of @gradient, freeing its memory if the reference count reaches 0. #GtkGradient is deprecated. a #GtkGradient GtkGrid is a container which arranges its child widgets in rows and columns, with arbitrary positions and horizontal/vertical spans. Children are added using gtk_grid_attach(). They can span multiple rows or columns. It is also possible to add a child next to an existing child, using gtk_grid_attach_next_to(). The behaviour of GtkGrid when several children occupy the same grid cell is undefined. GtkGrid can be used like a #GtkBox by just using gtk_container_add(), which will place children next to each other in the direction determined by the #GtkOrientable:orientation property. However, if all you want is a single row or column, then #GtkBox is the preferred widget. # CSS nodes GtkGrid uses a single CSS node with name grid. Creates a new grid widget. the new #GtkGrid 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. a #GtkGrid the widget to add the column number to attach the left side of @child to the row number to attach the top side of @child to the number of columns that @child will span the number of rows that @child will span Adds a widget to the grid. The widget is placed next to @sibling, on the side determined by @side. When @sibling is %NULL, 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 == %NULL and @side == %GTK_POS_LEFT yields a layout of [3][2][1]. a #GtkGrid the widget to add the child of @grid that @child will be placed next to, or %NULL to place @child at the beginning or end the side of @sibling that @child is positioned next to the number of columns that @child will span the number of rows that @child will span Returns which row defines the global baseline of @grid. the row index defining the global baseline a #GtkGrid Gets the child of @grid whose area covers the grid cell whose upper left corner is at @left, @top. the child at the given position, or %NULL a #GtkGrid the left edge of the cell the top edge of the cell Returns whether all columns of @grid have the same width. whether all columns of @grid have the same width. a #GtkGrid Returns the amount of space between the columns of @grid. the column spacing of @grid a #GtkGrid Returns the baseline position of @row as set by gtk_grid_set_row_baseline_position() or the default value %GTK_BASELINE_POSITION_CENTER. the baseline position of @row a #GtkGrid a row index Returns whether all rows of @grid have the same height. whether all rows of @grid have the same height. a #GtkGrid Returns the amount of space between the rows of @grid. the row spacing of @grid a #GtkGrid 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. a #GtkGrid the position to insert the column at 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 %GTK_POS_TOP or %GTK_POS_BOTTOM, a row is inserted. If @side is %GTK_POS_LEFT of %GTK_POS_RIGHT, a column is inserted. a #GtkGrid the child of @grid that the new row or column will be placed next to the side of @sibling that @child is positioned next to 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. a #GtkGrid the position to insert the row at 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. a #GtkGrid the position of the column to remove 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. a #GtkGrid the position of the row to remove 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 @grid. a #GtkGrid the row index Sets whether all columns of @grid will have the same width. a #GtkGrid %TRUE to make columns homogeneous Sets the amount of space between columns of @grid. a #GtkGrid the amount of space to insert between columns Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. a #GtkGrid a row index a #GtkBaselinePosition Sets whether all rows of @grid will have the same height. a #GtkGrid %TRUE to make rows homogeneous Sets the amount of space between rows of @grid. a #GtkGrid the amount of space to insert between rows The parent class. #GtkHBox is a container that organizes child widgets into a single row. Use the #GtkBox packing interface to determine the arrangement, spacing, width, and alignment of #GtkHBox children. All children are allocated the same height. GtkHBox has been deprecated. You can use #GtkBox instead, which is a very quick and easy change. If you have derived your own classes from GtkHBox, you can simply change the inheritance to derive directly from #GtkBox. No further changes are needed, since the default value of the #GtkOrientable:orientation property is %GTK_ORIENTATION_HORIZONTAL. If you have a grid-like layout composed of nested boxes, and you don’t need first-child or last-child styling, the recommendation is to switch to #GtkGrid. For more information about migrating to #GtkGrid, see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. Creates a new #GtkHBox. You can use gtk_box_new() with %GTK_ORIENTATION_HORIZONTAL instead, which is a quick and easy change. But the recommendation is to switch to #GtkGrid, since #GtkBox is going to go away eventually. See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. a new #GtkHBox. %TRUE if all children are to be given equal space allotments. the number of pixels to place by default between children. Creates a new horizontal button box. Use gtk_button_box_new() with %GTK_ORIENTATION_HORIZONTAL instead a new button box #GtkWidget. The HPaned widget is a container widget with two children arranged horizontally. The division between the two panes is adjustable by the user by dragging a handle. See #GtkPaned for details. GtkHPaned has been deprecated, use #GtkPaned instead. Create a new #GtkHPaned Use gtk_paned_new() with %GTK_ORIENTATION_HORIZONTAL instead the new #GtkHPaned #GtkHSV is the “color wheel” part of a complete color selector widget. It allows to select a color by determining its HSV components in an intuitive way. Moving the selection around the outer ring changes the hue, and moving the selection point inside the inner triangle changes value and saturation. #GtkHSV has been deprecated together with #GtkColorSelection, where it was used. Creates a new HSV color selector. A newly-created HSV color selector. Converts a color from HSV space to RGB. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Hue Saturation Value Return value for the red component Return value for the green component Return value for the blue component Queries the current color in an HSV color selector. Returned values will be in the [0.0, 1.0] range. An HSV color selector Return value for the hue Return value for the saturation Return value for the value Queries the size and ring width of an HSV color selector. An HSV color selector Return value for the diameter of the hue ring Return value for the width of the hue ring An HSV color selector can be said to be adjusting if multiple rapid changes are being made to its value, for example, when the user is adjusting the value with the mouse. This function queries whether the HSV color selector is being adjusted or not. %TRUE if clients can ignore changes to the color value, since they may be transitory, or %FALSE if they should consider the color value status to be final. A #GtkHSV Sets the current color in an HSV color selector. Color component values must be in the [0.0, 1.0] range. An HSV color selector Hue Saturation Value Sets the size and ring width of an HSV color selector. An HSV color selector Diameter for the hue ring Width of the hue ring The #GtkHScale widget is used to allow the user to select a value using a horizontal slider. To create one, use gtk_hscale_new_with_range(). The position to show the current value, and the number of decimal places shown can be set using the parent #GtkScale class’s functions. GtkHScale has been deprecated, use #GtkScale instead. Creates a new #GtkHScale. Use gtk_scale_new() with %GTK_ORIENTATION_HORIZONTAL instead a new #GtkHScale. the #GtkAdjustment which sets the range of the scale. Creates a new horizontal scale widget 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 gtk_scale_set_digits() to correct it. Use gtk_scale_new_with_range() with %GTK_ORIENTATION_HORIZONTAL instead a new #GtkHScale minimum value maximum value step increment (tick size) used with keyboard shortcuts The #GtkHScrollbar widget is a widget arranged horizontally creating a scrollbar. See #GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to handle the adjustment of the scrollbar or it may be left %NULL in which case one will be created for you. See #GtkScrollbar for a description of what the fields in an adjustment represent for a scrollbar. GtkHScrollbar has been deprecated, use #GtkScrollbar instead. Creates a new horizontal scrollbar. Use gtk_scrollbar_new() with %GTK_ORIENTATION_HORIZONTAL instead the new #GtkHScrollbar the #GtkAdjustment to use, or %NULL to create a new adjustment The #GtkHSeparator widget is a horizontal separator, used to group the widgets within a window. It displays a horizontal line with a shadow to make it appear sunken into the interface. > The #GtkHSeparator widget is not used as a separator within menus. > To create a separator in a menu create an empty #GtkSeparatorMenuItem > widget using gtk_separator_menu_item_new() and add it to the menu with > gtk_menu_shell_append(). GtkHSeparator has been deprecated, use #GtkSeparator instead. Creates a new #GtkHSeparator. Use gtk_separator_new() with %GTK_ORIENTATION_HORIZONTAL instead a new #GtkHSeparator. The #GtkHandleBox widget allows a portion of a window to be "torn off". It is a bin widget which displays its child and a handle that the user can drag to tear off a separate window (the “float window”) containing the child widget. A thin “ghost” is drawn in the original location of the handlebox. By dragging the separate window back to its original location, it can be reattached. When reattaching, the ghost and float window, must be aligned along one of the edges, the “snap edge”. This either can be specified by the application programmer explicitly, or GTK+ will pick a reasonable default based on the handle position. To make detaching and reattaching the handlebox as minimally confusing as possible to the user, it is important to set the snap edge so that the snap edge does not move when the handlebox is deattached. For instance, if the handlebox is packed at the bottom of a VBox, then when the handlebox is detached, the bottom edge of the handlebox's allocation will remain fixed as the height of the handlebox shrinks, so the snap edge should be set to %GTK_POS_BOTTOM. > #GtkHandleBox has been deprecated. It is very specialized, lacks features > to make it useful and most importantly does not fit well into modern > application design. Do not use it. There is no replacement. Create a new handle box. #GtkHandleBox has been deprecated. a new #GtkHandleBox. Whether the handlebox’s child is currently detached. #GtkHandleBox has been deprecated. %TRUE if the child is currently detached, otherwise %FALSE a #GtkHandleBox Gets the handle position of the handle box. See gtk_handle_box_set_handle_position(). #GtkHandleBox has been deprecated. the current handle position. a #GtkHandleBox Gets the type of shadow drawn around the handle box. See gtk_handle_box_set_shadow_type(). #GtkHandleBox has been deprecated. the type of shadow currently drawn around the handle box. a #GtkHandleBox Gets the edge used for determining reattachment of the handle box. See gtk_handle_box_set_snap_edge(). #GtkHandleBox has been deprecated. the edge used for determining reattachment, or (GtkPositionType)-1 if this is determined (as per default) from the handle position. a #GtkHandleBox Sets the side of the handlebox where the handle is drawn. #GtkHandleBox has been deprecated. a #GtkHandleBox the side of the handlebox where the handle should be drawn. Sets the type of shadow to be drawn around the border of the handle box. #GtkHandleBox has been deprecated. a #GtkHandleBox the shadow type. Sets the snap edge of a handlebox. The snap edge is the edge of the detached child that must be aligned with the corresponding edge of the “ghost” left behind when the child was detached to reattach the torn-off window. Usually, the snap edge should be chosen so that it stays in the same place on the screen when the handlebox is torn off. If the snap edge is not set, then an appropriate value will be guessed from the handle position. If the handle position is %GTK_POS_RIGHT or %GTK_POS_LEFT, then the snap edge will be %GTK_POS_TOP, otherwise it will be %GTK_POS_LEFT. #GtkHandleBox has been deprecated. a #GtkHandleBox the snap edge, or -1 to unset the value; in which case GTK+ will try to guess an appropriate value in the future. This signal is emitted when the contents of the handlebox are reattached to the main window. #GtkHandleBox has been deprecated. the child widget of the handlebox. (this argument provides no extra information and is here only for backwards-compatibility) This signal is emitted when the contents of the handlebox are detached from the main window. #GtkHandleBox has been deprecated. the child widget of the handlebox. (this argument provides no extra information and is here only for backwards-compatibility) The parent class. GtkHeaderBar is similar to a horizontal #GtkBox. 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 gtk_header_bar_set_has_subtitle(). GtkHeaderBar can add typical window frame controls, such as minimize, maximize and close buttons, or the window icon. For these reasons, GtkHeaderBar is the natural choice for use as the custom titlebar widget of a #GtkWindow (see gtk_window_set_titlebar()), as it gives features typical of titlebars while allowing the addition of child widgets. Creates a new #GtkHeaderBar widget. a new #GtkHeaderBar Retrieves the custom title widget of the header. See gtk_header_bar_set_custom_title(). the custom title widget of the header, or %NULL if none has been set explicitly. a #GtkHeaderBar Gets the decoration layout set with gtk_header_bar_set_decoration_layout(). the decoration layout a #GtkHeaderBar Retrieves whether the header bar reserves space for a subtitle, regardless if one is currently set or not. %TRUE if the header bar reserves space for a subtitle a #GtkHeaderBar Returns whether this header bar shows the standard window decorations. %TRUE if the decorations are shown a #GtkHeaderBar Retrieves the subtitle of the header. See gtk_header_bar_set_subtitle(). the subtitle of the header, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkHeaderBar Retrieves the title of the header. See gtk_header_bar_set_title(). the title of the header, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkHeaderBar Adds @child to @bar, packed with reference to the end of the @bar. A #GtkHeaderBar the #GtkWidget to be added to @bar Adds @child to @bar, packed with reference to the start of the @bar. A #GtkHeaderBar the #GtkWidget to be added to @bar Sets a custom title for the #GtkHeaderBar. The title should help a user identify the current view. This supersedes any title set by gtk_header_bar_set_title() or gtk_header_bar_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 %NULL, for the header title label to be visible again. a #GtkHeaderBar a custom widget to use for a title Sets the decoration layout for this header bar, overriding the #GtkSettings: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. a #GtkHeaderBar a decoration layout, or %NULL to unset the layout Sets whether the header bar should reserve space for a subtitle, even if none is currently set. a #GtkHeaderBar %TRUE to reserve space for a subtitle Sets whether this header bar shows the standard window decorations, including close, maximize, and minimize. a #GtkHeaderBar %TRUE to show standard window decorations Sets the subtitle of the #GtkHeaderBar. The title should give a user an additional detail to help him identify the current view. Note that GtkHeaderBar by default reserves room for the subtitle, even if none is currently set. If this is not desired, set the #GtkHeaderBar:has-subtitle property to %FALSE. a #GtkHeaderBar a subtitle, or %NULL Sets the title of the #GtkHeaderBar. The title should help a user identify the current view. A good title should not include the application name. a #GtkHeaderBar a title, or %NULL The decoration layout for buttons. If this property is not set, the #GtkSettings:gtk-decoration-layout setting is used. See gtk_header_bar_set_decoration_layout() for information about the format of this string. Set to %TRUE if #GtkHeaderBar:decoration-layout is set. If %TRUE, reserve space for a subtitle, even if none is currently set. Whether to show window decorations. Which buttons are actually shown and where is determined by the #GtkHeaderBar: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). #GtkIMContext defines the interface for GTK+ input methods. An input method is used by GTK+ text input widgets like #GtkEntry to map from key events to Unicode character strings. The default input method can be set programmatically via the #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set the GTK_IM_MODULE environment variable as documented in [Running GTK+ Applications][gtk-running]. The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView: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 #GtkIMContext or #GtkIMContextSimple and exports these four functions: |[<!-- language="C" --> void im_module_init(GTypeModule *module); ]| This function should register the #GType of the #GtkIMContext subclass which implements the input method by means of g_type_module_register_type(). Note that g_type_register_static() cannot be used as the type needs to be registered dynamically. |[<!-- language="C" --> void im_module_exit(void); ]| Here goes any cleanup code your input method might require on module unload. |[<!-- language="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 #GtkIMContextInfo items for each provided input method. |[<!-- language="C" --> GtkIMContext * im_module_create(const gchar *context_id); ]| This function should return a pointer to a newly created instance of the #GtkIMContext subclass identified by @context_id. The context ID is the same as specified in the #GtkIMContextInfo 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. Asks the widget that the input context is attached to to delete characters around the cursor position by emitting the GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in #GtkIMContext. In order to use this function, you should first call gtk_im_context_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. %TRUE if the signal was handled. a #GtkIMContext offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. 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. %TRUE if the input method handled the key event. a #GtkIMContext the key event 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. a #GtkIMContext 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. a #GtkIMContext 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. a #GtkIMContext location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with pango_attr_list_unref(). location to store position of cursor (in characters) within the preedit string. 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 GtkIMContext::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 gtk_im_context_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. %TRUE if surrounding text was provided; in this case you must free the result stored in *text. a #GtkIMContext 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(). location to store byte index of the insertion cursor within @text. 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. a #GtkIMContext Set the client window for the input context; this is the #GdkWindow 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. a #GtkIMContext the client window. This may be %NULL to indicate that the previous client window no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client window. a #GtkIMContext new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the GtkIMContext::retrieve_surrounding signal, and will likely have no effect if called at other times. a #GtkIMContext text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text. the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. 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. a #GtkIMContext whether the IM context should use the preedit string. Asks the widget that the input context is attached to to delete characters around the cursor position by emitting the GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in #GtkIMContext. In order to use this function, you should first call gtk_im_context_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. %TRUE if the signal was handled. a #GtkIMContext offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. 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. %TRUE if the input method handled the key event. a #GtkIMContext the key event 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. a #GtkIMContext 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. a #GtkIMContext 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. a #GtkIMContext location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with pango_attr_list_unref(). location to store position of cursor (in characters) within the preedit string. 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 GtkIMContext::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 gtk_im_context_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. %TRUE if surrounding text was provided; in this case you must free the result stored in *text. a #GtkIMContext 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(). location to store byte index of the insertion cursor within @text. 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. a #GtkIMContext Set the client window for the input context; this is the #GdkWindow 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. a #GtkIMContext the client window. This may be %NULL to indicate that the previous client window no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client window. a #GtkIMContext new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the GtkIMContext::retrieve_surrounding signal, and will likely have no effect if called at other times. a #GtkIMContext text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text. the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. 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. a #GtkIMContext whether the IM context should use the preedit string. 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. the completed character(s) entered by the user The ::delete-surrounding signal is emitted when the input method needs to delete all or part of the context surrounding the cursor. %TRUE if the signal was handled. the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor. the number of characters to be deleted 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 gtk_im_context_get_preedit_string() returns the empty string. The ::preedit-end signal is emitted when a preediting sequence has been completed or canceled. The ::preedit-start signal is emitted when a new preediting sequence starts. 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 gtk_im_context_set_surrounding() method. %TRUE if the signal was handled. %TRUE if the signal was handled. a #GtkIMContext offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. a #GtkIMContext the client window. This may be %NULL to indicate that the previous client window no longer exists. a #GtkIMContext location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with pango_attr_list_unref(). location to store position of cursor (in characters) within the preedit string. %TRUE if the input method handled the key event. a #GtkIMContext the key event a #GtkIMContext a #GtkIMContext a #GtkIMContext a #GtkIMContext new location a #GtkIMContext whether the IM context should use the preedit string. a #GtkIMContext text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text. the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. %TRUE if surrounding text was provided; in this case you must free the result stored in *text. a #GtkIMContext 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(). location to store byte index of the insertion cursor within @text. Bookkeeping information about a loadable input method. The unique identification string of the input method. The human-readable name of the input method. Translation domain to be used with dgettext() Name of locale directory for use with bindtextdomain() A colon-separated list of locales where this input method should be the default. The asterisk “*” sets the default for all locales. GtkIMContextSimple 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. GtkIMContextSimple 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. GtkIMContextSimple 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. ģ. Creates a new #GtkIMContextSimple. a new #GtkIMContextSimple. 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.) A #GtkIMContextSimple the table Maximum length of a sequence in the table (cannot be greater than #GTK_MAX_COMPOSE_LEN) number of sequences in the table Creates a new #GtkIMMulticontext. a new #GtkIMMulticontext. Add menuitems for various available input methods to a menu; the menuitems, when selected, will switch the input method for the context and the global default input method. It is better to use the system-wide input method framework for changing input methods. Modern desktop shells offer on-screen displays for this that can triggered with a keyboard shortcut, e.g. Super-Space. a #GtkIMMulticontext a #GtkMenuShell Gets the id of the currently active slave of the @context. the id of the currently active slave a #GtkIMMulticontext Sets the context id for @context. This causes the currently active slave of @context to be replaced by the slave corresponding to the new context id. a #GtkIMMulticontext the id to use Style for input method preedit. See also #GtkSettings:gtk-im-preedit-style Deprecated Deprecated Deprecated Style for input method status. See also #GtkSettings:gtk-im-status-style Deprecated Deprecated Deprecated Constant to return from a signal handler for the #GtkSpinButton::input signal in case of conversion failure. Like gtk_get_interface_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a set of variants of a particular icon (i.e. a #GtkIconSet contains variants for different sizes and widget states). Icons in an icon factory are named by a stock ID, which is a simple string identifying the icon. Each #GtkStyle has a list of #GtkIconFactory derived from the current theme; those icon factories are consulted first when searching for an icon. If the theme doesn’t set a particular icon, GTK+ looks for the icon in a list of default icon factories, maintained by gtk_icon_factory_add_default() and gtk_icon_factory_remove_default(). Applications with icons should add a default icon factory with their icons, which will allow themes to override the icons for the application. To display an icon, always use gtk_style_lookup_icon_set() on the widget that will display the icon, or the convenience function gtk_widget_render_icon(). These functions take the theme into account when looking up the icon to use for a given stock ID. # GtkIconFactory as GtkBuildable # {#GtkIconFactory-BUILDER-UI} GtkIconFactory supports a custom <sources> element, which can contain multiple <source> elements. The following attributes are allowed: - stock-id The stock id of the source, a string. This attribute is mandatory - filename The filename of the source, a string. This attribute is optional - icon-name The icon name for the source, a string. This attribute is optional. - size Size of the icon, a #GtkIconSize enum value. This attribute is optional. - direction Direction of the source, a #GtkTextDirection enum value. This attribute is optional. - state State of the source, a #GtkStateType enum value. This attribute is optional. ## A #GtkIconFactory UI definition fragment. ## |[ <object class="GtkIconFactory" id="iconfactory1"> <sources> <source stock-id="apple-red" filename="apple-red.png"/> </sources> </object> <object class="GtkWindow" id="window1"> <child> <object class="GtkButton" id="apple_button"> <property name="label">apple-red</property> <property name="use-stock">True</property> </object> </child> </object> ]| Creates a new #GtkIconFactory. An icon factory manages a collection of #GtkIconSets; a #GtkIconSet manages a set of variants of a particular icon (i.e. a #GtkIconSet contains variants for different sizes and widget states). Icons in an icon factory are named by a stock ID, which is a simple string identifying the icon. Each #GtkStyle has a list of #GtkIconFactorys derived from the current theme; those icon factories are consulted first when searching for an icon. If the theme doesn’t set a particular icon, GTK+ looks for the icon in a list of default icon factories, maintained by gtk_icon_factory_add_default() and gtk_icon_factory_remove_default(). Applications with icons should add a default icon factory with their icons, which will allow themes to override the icons for the application. Use #GtkIconTheme instead. a new #GtkIconFactory Looks for an icon in the list of default icon factories. For display to the user, you should use gtk_style_lookup_icon_set() on the #GtkStyle for the widget that will display the icon, instead of using this function directly, so that themes are taken into account. Use #GtkIconTheme instead. a #GtkIconSet, or %NULL an icon name Adds the given @icon_set to the icon factory, under the name @stock_id. @stock_id should be namespaced for your application, e.g. “myapp-whatever-icon”. Normally applications create a #GtkIconFactory, then add it to the list of default factories with gtk_icon_factory_add_default(). Then they pass the @stock_id to widgets such as #GtkImage to display the icon. Themes can provide an icon with the same name (such as "myapp-whatever-icon") to override your application’s default icons. If an icon already existed in @factory for @stock_id, it is unreferenced and replaced with the new @icon_set. Use #GtkIconTheme instead. a #GtkIconFactory icon name icon set Adds an icon factory to the list of icon factories searched by gtk_style_lookup_icon_set(). This means that, for example, gtk_image_new_from_stock() will be able to find icons in @factory. There will normally be an icon factory added for each library or application that comes with icons. The default icon factories can be overridden by themes. Use #GtkIconTheme instead. a #GtkIconFactory Looks up @stock_id in the icon factory, returning an icon set if found, otherwise %NULL. For display to the user, you should use gtk_style_lookup_icon_set() on the #GtkStyle for the widget that will display the icon, instead of using this function directly, so that themes are taken into account. Use #GtkIconTheme instead. icon set of @stock_id. a #GtkIconFactory an icon name Removes an icon factory from the list of default icon factories. Not normally used; you might use it for a library that can be unloaded or shut down. Use #GtkIconTheme instead. a #GtkIconFactory previously added with gtk_icon_factory_add_default() The parent class. Contains information found when looking up an icon in an icon theme. Creates a #GtkIconInfo for a #GdkPixbuf. a #GtkIconInfo a #GtkIconTheme the pixbuf to wrap in a #GtkIconInfo Make a copy of a #GtkIconInfo. Use g_object_ref() the new GtkIconInfo a #GtkIconInfo Free a #GtkIconInfo and associated information Use g_object_unref() a #GtkIconInfo This function is deprecated and always returns %FALSE. Attachment points are deprecated %FALSE a #GtkIconInfo location to store pointer to an array of points, or %NULL free the array of points with g_free(). location to store the number of points in @points, or %NULL 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. the base scale a #GtkIconInfo 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. the base size, or 0, if no base size is known for the icon. a #GtkIconInfo Gets the built-in image for this icon, if any. To allow GTK+ to use built in icon images, you must pass the %GTK_ICON_LOOKUP_USE_BUILTIN to gtk_icon_theme_lookup_icon(). This function is deprecated, use gtk_icon_theme_add_resource_path() instead of builtin icons. the built-in image pixbuf, or %NULL. No extra reference is added to the returned pixbuf, so if you want to keep it around, you must use g_object_ref(). The returned image must not be modified. a #GtkIconInfo This function is deprecated and always returns %NULL. Display names are deprecated %NULL a #GtkIconInfo This function is deprecated and always returns %FALSE. Embedded rectangles are deprecated %FALSE a #GtkIconInfo #GdkRectangle in which to store embedded rectangle coordinates; coordinates are only stored when this function returns %TRUE. Gets the filename for the icon. If the %GTK_ICON_LOOKUP_USE_BUILTIN flag was passed to gtk_icon_theme_lookup_icon(), there may be no filename if a builtin icon is returned; in this case, you should use gtk_icon_info_get_builtin_pixbuf(). the filename for the icon, or %NULL if gtk_icon_info_get_builtin_pixbuf() should be used instead. The return value is owned by GTK+ and should not be modified or freed. a #GtkIconInfo 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. %TRUE if the icon is symbolic, %FALSE otherwise a #GtkIconInfo Renders an icon previously looked up in an icon theme using gtk_icon_theme_lookup_icon(); the size will be based on the size passed to gtk_icon_theme_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 %GTK_ICON_LOOKUP_FORCE_SIZE flag when obtaining the #GtkIconInfo. If this flag has been specified, the pixbuf returned by this function will be scaled to the exact size. 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 g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() Asynchronously load, render and scale an icon previously looked up from the icon theme using gtk_icon_theme_lookup_icon(). For more details, see gtk_icon_info_load_icon() which is the synchronous version of this call. a #GtkIconInfo from gtk_icon_theme_lookup_icon() optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async icon load, see gtk_icon_info_load_icon_async(). 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 g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GAsyncResult Renders an icon previously looked up in an icon theme using gtk_icon_theme_lookup_icon(); the size will be based on the size passed to gtk_icon_theme_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 %GTK_ICON_LOOKUP_FORCE_SIZE flag when obtaining the #GtkIconInfo. If this flag has been specified, the pixbuf returned by this function will be scaled to the exact size. 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. a #GtkIconInfo from gtk_icon_theme_lookup_icon() #GdkWindow to optimize drawing for, or %NULL 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 gtk_icon_info_load_icon(). This allows loading symbolic icons that will match the system theme. Unless you are implementing a widget, you will want to use g_themed_icon_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. a #GdkPixbuf representing the loaded icon a #GtkIconInfo a #GdkRGBA representing the foreground color of the icon a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the error color of the icon or %NULL to use the default color (allow-none) a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Asynchronously load, render and scale a symbolic icon previously looked up from the icon theme using gtk_icon_theme_lookup_icon(). For more details, see gtk_icon_info_load_symbolic() which is the synchronous version of this call. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GdkRGBA representing the foreground color of the icon a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the warning color of the icon or %NULL to use the default color a #GdkRGBA representing the error color of the icon or %NULL to use the default color (allow-none) optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async icon load, see gtk_icon_info_load_symbolic_async(). 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 g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GAsyncResult a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. 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 gtk_icon_info_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 gtk_icon_info_load_symbolic() for more details. a #GdkPixbuf representing the loaded icon a #GtkIconInfo a #GtkStyleContext a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Asynchronously load, render and scale a symbolic icon previously looked up from the icon theme using gtk_icon_theme_lookup_icon(). For more details, see gtk_icon_info_load_symbolic_for_context() which is the synchronous version of this call. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GtkStyleContext optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async icon load, see gtk_icon_info_load_symbolic_for_context_async(). 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 g_object_unref() to release your reference to the icon. a #GtkIconInfo from gtk_icon_theme_lookup_icon() a #GAsyncResult a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. 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 gtk_icon_info_load_icon(). This allows loading symbolic icons that will match the system theme. See gtk_icon_info_load_symbolic() for more details. Use gtk_icon_info_load_symbolic_for_context() instead a #GdkPixbuf representing the loaded icon a #GtkIconInfo a #GtkStyle to take the colors from the widget state to use for colors a #gboolean, returns whether the loaded icon was a symbolic one and whether the @fg color was applied to it. Sets whether the coordinates returned by gtk_icon_info_get_embedded_rect() and gtk_icon_info_get_attach_points() should be returned in their original form as specified in the icon theme, instead of scaled appropriately for the pixbuf returned by gtk_icon_info_load_icon(). Raw coordinates are somewhat strange; they are specified to be with respect to the unscaled pixmap for PNG and XPM icons, but for SVG icons, they are in a 1000x1000 coordinate space that is scaled to the final size of the icon. You can determine if the icon is an SVG icon by using gtk_icon_info_get_filename(), and seeing if it is non-%NULL and ends in “.svg”. This function is provided primarily to allow compatibility wrappers for older API's, and is not expected to be useful for applications. Embedded rectangles and attachment points are deprecated a #GtkIconInfo whether the coordinates of embedded rectangles and attached points should be returned in their original (unscaled) form. Used to specify options for gtk_icon_theme_lookup_icon() Never get SVG icons, even if gdk-pixbuf supports them. Cannot be used together with %GTK_ICON_LOOKUP_FORCE_SVG. Get SVG icons, even if gdk-pixbuf doesn’t support them. Cannot be used together with %GTK_ICON_LOOKUP_NO_SVG. When passed to gtk_icon_theme_lookup_icon() includes builtin icons as well as files. For a builtin icon, gtk_icon_info_get_filename() is %NULL and you need to call gtk_icon_info_get_builtin_pixbuf(). 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 gtk_icon_theme_choose_icon(). Since 2.12. Always get the icon scaled to the requested size. Since 2.14. Try to always load regular icons, even when symbolic icon names are given. Since 3.14. Try to always load symbolic icons, even when regular icon names are given. Since 3.14. Try to load a variant of the icon for left-to-right text direction. Since 3.14. Try to load a variant of the icon for right-to-left text direction. Since 3.14. Creates a new #GtkIconSet. A #GtkIconSet represents a single icon in various sizes and widget states. It can provide a #GdkPixbuf for a given size and state on request, and automatically caches some of the rendered #GdkPixbuf objects. Normally you would use gtk_widget_render_icon_pixbuf() instead of using #GtkIconSet directly. The one case where you’d use #GtkIconSet is to create application-specific icon sets to place in a #GtkIconFactory. Use #GtkIconTheme instead. a new #GtkIconSet Creates a new #GtkIconSet with @pixbuf as the default/fallback source image. If you don’t add any additional #GtkIconSource to the icon set, all variants of the icon will be created from @pixbuf, using scaling, pixelation, etc. as required to adjust the icon size or make the icon look insensitive/prelighted. Use #GtkIconTheme instead. a new #GtkIconSet a #GdkPixbuf Icon sets have a list of #GtkIconSource, which they use as base icons for rendering icons in different states and sizes. Icons are scaled, made to look insensitive, etc. in gtk_icon_set_render_icon(), but #GtkIconSet needs base images to work with. The base images and when to use them are described by a #GtkIconSource. This function copies @source, so you can reuse the same source immediately without affecting the icon set. An example of when you’d use this function: a web browser’s "Back to Previous Page" icon might point in a different direction in Hebrew and in English; it might look different when insensitive; and it might change size depending on toolbar mode (small/large icons). So a single icon set would contain all those variants of the icon, and you might add a separate source for each one. You should nearly always add a “default” icon source with all fields wildcarded, which will be used as a fallback if no more specific source matches. #GtkIconSet always prefers more specific icon sources to more generic icon sources. The order in which you add the sources to the icon set does not matter. gtk_icon_set_new_from_pixbuf() creates a new icon set with a default icon source based on the given pixbuf. Use #GtkIconTheme instead. a #GtkIconSet a #GtkIconSource Copies @icon_set by value. Use #GtkIconTheme instead. a new #GtkIconSet identical to the first. a #GtkIconSet Obtains a list of icon sizes this icon set can render. The returned array must be freed with g_free(). Use #GtkIconTheme instead. a #GtkIconSet return location for array of sizes (#GtkIconSize) location to store number of elements in returned array Increments the reference count on @icon_set. Use #GtkIconTheme instead. @icon_set. a #GtkIconSet. Renders an icon using gtk_style_render_icon(). In most cases, gtk_widget_render_icon() is better, since it automatically provides most of the arguments from the current widget settings. This function never returns %NULL; if the icon can’t be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. Use gtk_icon_set_render_icon_pixbuf() instead a #GdkPixbuf to be displayed a #GtkIconSet a #GtkStyle associated with @widget, or %NULL text direction widget state icon size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. widget that will display the icon, or %NULL. The only use that is typically made of this is to determine the appropriate #GdkScreen. detail to pass to the theme engine, or %NULL. Note that passing a detail of anything but %NULL will disable caching. Renders an icon using gtk_render_icon_pixbuf(). In most cases, gtk_widget_render_icon_pixbuf() is better, since it automatically provides most of the arguments from the current widget settings. This function never returns %NULL; if the icon can’t be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. Use #GtkIconTheme instead. a #GdkPixbuf to be displayed a #GtkIconSet a #GtkStyleContext icon size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. Renders an icon using gtk_render_icon_pixbuf() and converts it to a cairo surface. This function never returns %NULL; if the icon can’t be rendered (perhaps because an image file fails to load), a default "missing image" icon will be returned instead. Use #GtkIconTheme instead. a #cairo_surface_t to be displayed a #GtkIconSet a #GtkStyleContext icon size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the window scale to render for #GdkWindow to optimize drawing for, or %NULL Decrements the reference count on @icon_set, and frees memory if the reference count reaches 0. Use #GtkIconTheme instead. a #GtkIconSet Built-in stock icon sizes. Invalid size. Size appropriate for menus (16px). Size appropriate for small toolbars (16px). Size appropriate for large toolbars (24px) Size appropriate for buttons (16px) Size appropriate for drag and drop (32px) Size appropriate for dialogs (48px) Looks up the icon size associated with @name. Use #GtkIconTheme instead. the icon size (#GtkIconSize) the name to look up. Gets the canonical name of the given icon size. The returned string is statically allocated and should not be freed. Use #GtkIconTheme instead. the name of the given icon size. a #GtkIconSize. Obtains the pixel size of a semantic icon size @size: #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_icon_theme_load_icon() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. %TRUE if @size was a valid size an icon size (#GtkIconSize) location to store icon width location to store icon height Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular #GtkSettings. Normally @size would be #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_widget_render_icon_pixbuf() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. Use gtk_icon_size_lookup() instead. %TRUE if @size was a valid size a #GtkSettings object, used to determine which set of user preferences to used. an icon size (#GtkIconSize) location to store icon width location to store icon height Registers a new icon size, along the same lines as #GTK_ICON_SIZE_MENU, etc. Returns the integer value for the size. Use #GtkIconTheme instead. integer value representing the size (#GtkIconSize) name of the icon size the icon width the icon height Registers @alias as another name for @target. So calling gtk_icon_size_from_name() with @alias as argument will return @target. Use #GtkIconTheme instead. an alias for @target an existing icon size (#GtkIconSize) Creates a new #GtkIconSource. A #GtkIconSource contains a #GdkPixbuf (or image filename) that serves as the base image for one or more of the icons in a #GtkIconSet, along with a specification for which icons in the icon set will be based on that pixbuf or image file. An icon set contains a set of icons that represent “the same” logical concept in different states, different global text directions, and different sizes. So for example a web browser’s “Back to Previous Page” icon might point in a different direction in Hebrew and in English; it might look different when insensitive; and it might change size depending on toolbar mode (small/large icons). So a single icon set would contain all those variants of the icon. #GtkIconSet contains a list of #GtkIconSource from which it can derive specific icon variants in the set. In the simplest case, #GtkIconSet contains one source pixbuf from which it derives all variants. The convenience function gtk_icon_set_new_from_pixbuf() handles this case; if you only have one source pixbuf, just use that function. If you want to use a different base pixbuf for different icon variants, you create multiple icon sources, mark which variants they’ll be used to create, and add them to the icon set with gtk_icon_set_add_source(). By default, the icon source has all parameters wildcarded. That is, the icon source will be used as the base icon for any desired text direction, widget state, or icon size. Use #GtkIconTheme instead. a new #GtkIconSource Creates a copy of @source; mostly useful for language bindings. Use #GtkIconTheme instead. a new #GtkIconSource a #GtkIconSource Frees a dynamically-allocated icon source, along with its filename, size, and pixbuf fields if those are not %NULL. Use #GtkIconTheme instead. a #GtkIconSource Obtains the text direction this icon source applies to. The return value is only useful/meaningful if the text direction is not wildcarded. Use #GtkIconTheme instead. text direction this source matches a #GtkIconSource Gets the value set by gtk_icon_source_set_direction_wildcarded(). Use #GtkIconTheme instead. %TRUE if this icon source is a base for any text direction variant a #GtkIconSource Retrieves the source filename, or %NULL if none is set. The filename is not a copy, and should not be modified or expected to persist beyond the lifetime of the icon source. Use #GtkIconTheme instead. image filename. This string must not be modified or freed. a #GtkIconSource Retrieves the source icon name, or %NULL if none is set. The icon_name is not a copy, and should not be modified or expected to persist beyond the lifetime of the icon source. Use #GtkIconTheme instead. icon name. This string must not be modified or freed. a #GtkIconSource Retrieves the source pixbuf, or %NULL if none is set. In addition, if a filename source is in use, this function in some cases will return the pixbuf from loaded from the filename. This is, for example, true for the GtkIconSource passed to the #GtkStyle render_icon() virtual function. The reference count on the pixbuf is not incremented. Use #GtkIconTheme instead. source pixbuf a #GtkIconSource Obtains the icon size this source applies to. The return value is only useful/meaningful if the icon size is not wildcarded. Use #GtkIconTheme instead. icon size (#GtkIconSize) this source matches. a #GtkIconSource Gets the value set by gtk_icon_source_set_size_wildcarded(). Use #GtkIconTheme instead. %TRUE if this icon source is a base for any icon size variant a #GtkIconSource Obtains the widget state this icon source applies to. The return value is only useful/meaningful if the widget state is not wildcarded. Use #GtkIconTheme instead. widget state this source matches a #GtkIconSource Gets the value set by gtk_icon_source_set_state_wildcarded(). Use #GtkIconTheme instead. %TRUE if this icon source is a base for any widget state variant a #GtkIconSource Sets the text direction this icon source is intended to be used with. Setting the text direction on an icon source makes no difference if the text direction is wildcarded. Therefore, you should usually call gtk_icon_source_set_direction_wildcarded() to un-wildcard it in addition to calling this function. Use #GtkIconTheme instead. a #GtkIconSource text direction this source applies to If the text direction is wildcarded, this source can be used as the base image for an icon in any #GtkTextDirection. If the text direction is not wildcarded, then the text direction the icon source applies to should be set with gtk_icon_source_set_direction(), and the icon source will only be used with that text direction. #GtkIconSet prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when possible. Use #GtkIconTheme instead. a #GtkIconSource %TRUE to wildcard the text direction Sets the name of an image file to use as a base image when creating icon variants for #GtkIconSet. The filename must be absolute. Use #GtkIconTheme instead. a #GtkIconSource image file to use Sets the name of an icon to look up in the current icon theme to use as a base image when creating icon variants for #GtkIconSet. Use #GtkIconTheme instead. a #GtkIconSource name of icon to use Sets a pixbuf to use as a base image when creating icon variants for #GtkIconSet. Use #GtkIconTheme instead. a #GtkIconSource pixbuf to use as a source Sets the icon size this icon source is intended to be used with. Setting the icon size on an icon source makes no difference if the size is wildcarded. Therefore, you should usually call gtk_icon_source_set_size_wildcarded() to un-wildcard it in addition to calling this function. Use #GtkIconTheme instead. a #GtkIconSource icon size (#GtkIconSize) this source applies to If the icon size is wildcarded, this source can be used as the base image for an icon of any size. If the size is not wildcarded, then the size the source applies to should be set with gtk_icon_source_set_size() and the icon source will only be used with that specific size. #GtkIconSet prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when possible. #GtkIconSet will normally scale wildcarded source images to produce an appropriate icon at a given size, but will not change the size of source images that match exactly. Use #GtkIconTheme instead. a #GtkIconSource %TRUE to wildcard the widget state Sets the widget state this icon source is intended to be used with. Setting the widget state on an icon source makes no difference if the state is wildcarded. Therefore, you should usually call gtk_icon_source_set_state_wildcarded() to un-wildcard it in addition to calling this function. Use #GtkIconTheme instead. a #GtkIconSource widget state this source applies to If the widget state is wildcarded, this source can be used as the base image for an icon in any #GtkStateType. If the widget state is not wildcarded, then the state the source applies to should be set with gtk_icon_source_set_state() and the icon source will only be used with that specific state. #GtkIconSet prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when possible. #GtkIconSet will normally transform wildcarded source images to produce an appropriate icon for a given state, for example lightening an image on prelight, but will not modify source images that match exactly. Use #GtkIconTheme instead. a #GtkIconSource %TRUE to wildcard the widget state #GtkIconTheme 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 #GtkIconSize enumeration, or by custom sizes defined by gtk_icon_size_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 #GtkImage or stock items, rather than directly, but looking up icons directly is also simple. The #GtkIconTheme object acts as a database of all the icons in the current theme. You can create new #GtkIconTheme objects, but it’s much more efficient to use the standard icon theme for the #GdkScreen so that the icon information is shared with other people looking up icons. |[<!-- language="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); } ]| 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 gtk_icon_theme_get_default() or gtk_icon_theme_get_for_screen() rather than creating a new icon theme object for scratch. the newly created #GtkIconTheme object. Registers a built-in icon for icon theme lookups. The idea of built-in icons is to allow an application or library that uses themed icons to function requiring files to be present in the file system. For instance, the default images for all of GTK+’s stock icons are registered as built-icons. In general, if you use gtk_icon_theme_add_builtin_icon() you should also install the icon in the icon theme, so that the icon is generally available. This function will generally be used with pixbufs loaded via gdk_pixbuf_new_from_inline(). Use gtk_icon_theme_add_resource_path() to add application-specific icons to the icon theme. the name of the icon to register the size in pixels at which to register the icon (different images can be registered for the same icon name at different sizes.) #GdkPixbuf that contains the image to use for @icon_name Gets the icon theme for the default screen. See gtk_icon_theme_get_for_screen(). A unique #GtkIconTheme 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. 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 gtk_icon_theme_new() and setting the screen yourself; by using this function a single icon theme object will be shared between users. A unique #GtkIconTheme 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. a #GdkScreen 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. a #GtkIconTheme a resource path Appends a directory to the search path. See gtk_icon_theme_set_search_path(). a #GtkIconTheme directory name to append to the icon path Looks up a named icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_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. a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme %NULL-terminated array of icon names to lookup desired icon size flags modifying the behavior of the icon lookup Looks up a named icon for a particular window scale and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_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. a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme %NULL-terminated array of icon names to lookup desired icon size desired scale flags modifying the behavior of the icon lookup 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.) the name of an example icon or %NULL. Free with g_free(). a #GtkIconTheme 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. 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. a #GtkIconTheme the name of an icon Gets the current search path. See gtk_icon_theme_set_search_path(). a #GtkIconTheme location to store a list of icon theme path directories or %NULL. The stored value should be freed with g_strfreev(). location to store number of elements in @path, or %NULL Checks whether an icon theme includes an icon for a particular name. %TRUE if @icon_theme includes an icon for @icon_name. a #GtkIconTheme the name of an icon Gets the list of contexts available within the current hierarchy of icon themes. See gtk_icon_theme_list_icons() for details about contexts. a #GList 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 g_list_free(). a #GtkIconTheme 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 gtk_icon_theme_list_contexts(). a #GList 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 g_list_free(). a #GtkIconTheme a string identifying a particular type of icon, or %NULL to list all icons. 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 gtk_icon_theme_lookup_icon() followed by gtk_icon_info_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 GtkWidget::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_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. 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 g_object_unref() to release your reference to the icon. %NULL if the icon isn’t found. a #GtkIconTheme the name of the icon to lookup the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon(). flags modifying the behavior of the icon lookup 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 gtk_icon_theme_lookup_icon() followed by gtk_icon_info_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 GtkWidget::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_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. 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 g_object_unref() to release your reference to the icon. %NULL if the icon isn’t found. a #GtkIconTheme the name of the icon to lookup the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon(). desired scale flags modifying the behavior of the icon lookup 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 gtk_icon_theme_lookup_icon() followed by gtk_icon_info_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 GtkWidget::style-set signal. 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. %NULL if the icon isn’t found. a #GtkIconTheme the name of the icon to lookup the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_load_icon(). desired scale #GdkWindow to optimize drawing for, or %NULL flags modifying the behavior of the icon lookup Looks up an icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_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_window_get_scale_factor(). Instead, you should use gtk_icon_theme_lookup_by_gicon_for_scale(), as the assets loaded for a given scaling factor may be different. a #GtkIconInfo containing information about the icon, or %NULL if the icon wasn’t found. Unref with g_object_unref() a #GtkIconTheme the #GIcon to look up desired icon size flags modifying the behavior of the icon lookup Looks up an icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). a #GtkIconInfo containing information about the icon, or %NULL if the icon wasn’t found. Unref with g_object_unref() a #GtkIconTheme the #GIcon to look up desired icon size the desired scale flags modifying the behavior of the icon lookup Looks up a named icon and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_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_window_get_scale_factor(). Instead, you should use gtk_icon_theme_lookup_icon_for_scale(), as the assets loaded for a given scaling factor may be different. a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme the name of the icon to lookup desired icon size flags modifying the behavior of the icon lookup Looks up a named icon for a particular window scale and returns a #GtkIconInfo containing information such as the filename of the icon. The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines these two steps if all you need is the pixbuf.) a #GtkIconInfo object containing information about the icon, or %NULL if the icon wasn’t found. a #GtkIconTheme the name of the icon to lookup desired icon size the desired scale flags modifying the behavior of the icon lookup Prepends a directory to the search path. See gtk_icon_theme_set_search_path(). a #GtkIconTheme directory name to prepend to the icon path Checks to see if the icon theme has changed; if it has, any currently cached information is discarded and will be reloaded next time @icon_theme is accessed. %TRUE if the icon theme has changed and needed to be reloaded. a #GtkIconTheme Sets the name of the icon theme that the #GtkIconTheme object uses overriding system configuration. This function cannot be called on the icon theme objects returned from gtk_icon_theme_get_default() and gtk_icon_theme_get_for_screen(). a #GtkIconTheme name of icon theme to use instead of configured theme, or %NULL to unset a previously set custom theme 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. a #GtkIconTheme a #GdkScreen 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.) a #GtkIconTheme array of directories that are searched for icon themes number of elements in @path. Emitted when the current icon theme is switched or GTK+ detects that a change has occurred in the contents of the current icon theme. The parent class. Error codes for GtkIconTheme operations. The icon specified does not exist in the theme An unspecified error occurred. #GtkIconView provides an alternative view on a #GtkTreeModel. It displays the model as a grid of icons with labels. Like #GtkTreeView, it allows to select one or multiple items (depending on the selection mode, see gtk_icon_view_set_selection_mode()). In addition to selection with the arrow keys, #GtkIconView 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), #GtkIconView will only display the first level of the tree and ignore the tree’s branches. # CSS nodes |[<!-- language="plain" --> iconview.view ╰── [rubberband] ]| GtkIconView has a single CSS node with name iconview and style class .view. For rubberband selection, a subnode with name rubberband is used. Creates a new #GtkIconView widget A newly created #GtkIconView widget Creates a new #GtkIconView widget using the specified @area to layout cells inside the icons. A newly created #GtkIconView widget the #GtkCellArea to use to layout cells Creates a new #GtkIconView widget with the model @model. A newly created #GtkIconView widget. The model. Activates the item determined by @path. A #GtkIconView The #GtkTreePath to be activated Selects all the icons. @icon_view must has its selection mode set to #GTK_SELECTION_MULTIPLE. A #GtkIconView. Unselects all the icons. A #GtkIconView. Converts widget coordinates to coordinates for the bin_window, as expected by e.g. gtk_icon_view_get_path_at_pos(). a #GtkIconView X coordinate relative to the widget Y coordinate relative to the widget return location for bin_window X coordinate return location for bin_window Y coordinate Creates a #cairo_surface_t representation of the item at @path. This image is used for a drag icon. a newly-allocated surface of the drag icon. a #GtkIconView a #GtkTreePath in @icon_view Turns @icon_view into a drop destination for automatic DND. Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag to this widget Turns @icon_view into a drag source for automatic DND. Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView Mask of allowed buttons to start drag the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag from this widget Gets the setting set by gtk_icon_view_set_activate_on_single_click(). %TRUE if item-activated will be emitted on a single click a #GtkIconView Fills the bounding rectangle in widget coordinates for the cell specified by @path and @cell. If @cell is %NULL the main cell area is used. This function is only valid if @icon_view is realized. %FALSE if there is no such item, %TRUE otherwise a #GtkIconView a #GtkTreePath a #GtkCellRenderer or %NULL rectangle to fill with cell rect Returns the value of the ::column-spacing property. the space between columns a #GtkIconView Returns the value of the ::columns property. the number of columns, or -1 a #GtkIconView Fills in @path and @cell with the current cursor path and cell. If the cursor isn’t currently set, then *@path will be %NULL. If no cell currently has focus, then *@cell will be %NULL. The returned #GtkTreePath must be freed with gtk_tree_path_free(). %TRUE if the cursor is set. A #GtkIconView Return location for the current cursor path, or %NULL Return location the current focus cell, or %NULL Determines the destination item for a given position. whether there is an item at the given position. a #GtkIconView the position to determine the destination item for the position to determine the destination item for Return location for the path of the item, or %NULL. Return location for the drop position, or %NULL Gets information about the item that is highlighted for feedback. a #GtkIconView Return location for the path of the highlighted item, or %NULL. Return location for the drop position, or %NULL Finds the path at the point (@x, @y), relative to bin_window coordinates. In contrast to gtk_icon_view_get_path_at_pos(), this function also obtains the cell at the specified position. The returned path should be freed with gtk_tree_path_free(). See gtk_icon_view_convert_widget_to_bin_window_coords() for converting widget coordinates to bin_window coordinates. %TRUE if an item exists at the specified position A #GtkIconView. The x position to be identified The y position to be identified Return location for the path, or %NULL Return location for the renderer responsible for the cell at (@x, @y), or %NULL Gets the column in which the item @path is currently displayed. Column numbers start at 0. The column in which the item is displayed a #GtkIconView the #GtkTreePath of the item Returns the value of the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. the relative position of texts and icons a #GtkIconView Returns the value of the ::item-padding property. the padding around items a #GtkIconView Gets the row in which the item @path is currently displayed. Row numbers start at 0. The row in which the item is displayed a #GtkIconView the #GtkTreePath of the item Returns the value of the ::item-width property. the width of a single item, or -1 a #GtkIconView Returns the value of the ::margin property. the space at the borders a #GtkIconView Returns the column with markup text for @icon_view. the markup column, or -1 if it’s unset. A #GtkIconView. Returns the model the #GtkIconView is based on. Returns %NULL if the model is unset. A #GtkTreeModel, or %NULL if none is currently being used. a #GtkIconView Finds the path at the point (@x, @y), relative to bin_window coordinates. See gtk_icon_view_get_item_at_pos(), if you are also interested in the cell at the specified position. See gtk_icon_view_convert_widget_to_bin_window_coords() for converting widget coordinates to bin_window coordinates. The #GtkTreePath corresponding to the icon or %NULL if no icon exists at that position. A #GtkIconView. The x position to be identified The y position to be identified Returns the column with pixbufs for @icon_view. the pixbuf column, or -1 if it’s unset. A #GtkIconView. Retrieves whether the user can reorder the list via drag-and-drop. See gtk_icon_view_set_reorderable(). %TRUE if the list can be reordered. a #GtkIconView Returns the value of the ::row-spacing property. the space between rows a #GtkIconView 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 gtk_tree_row_reference_new(). To free the return value, use: |[<!-- language="C" --> g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ]| A #GList containing a #GtkTreePath for each selected row. A #GtkIconView. Gets the selection mode of the @icon_view. the current selection mode A #GtkIconView. Returns the value of the ::spacing property. the space between cells a #GtkIconView Returns the column with text for @icon_view. the text column, or -1 if it’s unset. A #GtkIconView. Returns the column of @icon_view’s model which is being used for displaying tooltips on @icon_view’s rows. the index of the tooltip column that is currently being used, or -1 if this is disabled. a #GtkIconView This function is supposed to be used in a #GtkWidget::query-tooltip signal handler for #GtkIconView. 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 @icon_view’s bin_window if @keyboard_tooltip is %FALSE. whether or not the given tooltip context points to a item an #GtkIconView the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a #GtkTreeModel or %NULL a pointer to receive a #GtkTreePath or %NULL a pointer to receive a #GtkTreeIter or %NULL 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 gtk_tree_path_free() after use. %TRUE, if valid paths were placed in @start_path and @end_path A #GtkIconView Return location for start of region, or %NULL Return location for end of region, or %NULL Activates the item determined by @path. A #GtkIconView The #GtkTreePath to be activated Returns %TRUE if the icon pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned. %TRUE if @path is selected. A #GtkIconView. A #GtkTreePath to check selection on. Moves the alignments of @icon_view 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 @icon_view is realized, the centered path will be modified to reflect this change. A #GtkIconView. The path of the item to move to. whether to use alignment arguments, or %FALSE. The vertical alignment of the item specified by @path. The horizontal alignment of the item specified by @path. Selects all the icons. @icon_view must has its selection mode set to #GTK_SELECTION_MULTIPLE. A #GtkIconView. Selects the row at @path. A #GtkIconView. The #GtkTreePath to be selected. Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function. A #GtkIconView. The function to call for each selected icon. User data to pass to the function. Causes the #GtkIconView::item-activated signal to be emitted on a single click instead of a double click. a #GtkIconView %TRUE to emit item-activated on a single click Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view. a #GtkIconView the column spacing 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. a #GtkIconView the number of columns 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 %NULL, 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. A #GtkIconView A #GtkTreePath One of the cell renderers of @icon_view, or %NULL %TRUE if the specified cell should start being edited. Sets the item that is highlighted for feedback. a #GtkIconView The path of the item to highlight, or %NULL. Specifies where to drop, relative to the item Sets the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. a #GtkIconView the relative position of texts and icons Sets the #GtkIconView:item-padding property which specifies the padding around each of the icon view’s items. a #GtkIconView the item padding 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. a #GtkIconView the width for each item Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view. a #GtkIconView the margin Sets the column with markup information for @icon_view 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 gtk_icon_view_set_text_column(). A #GtkIconView. A column in the currently used model, or -1 to display no text Sets the model for a #GtkIconView. If the @icon_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. A #GtkIconView. The model. Sets the column with pixbufs for @icon_view to be @column. The pixbuf column must be of type #GDK_TYPE_PIXBUF A #GtkIconView. A column in the currently used model, or -1 to disable This function is a convenience function to allow you to reorder models that support the #GtkTreeDragSourceIface and the #GtkTreeDragDestIface. Both #GtkTreeStore and #GtkListStore 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. A #GtkIconView. %TRUE, if the list of items can be reordered. Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view. a #GtkIconView the row spacing Sets the selection mode of the @icon_view. A #GtkIconView. The selection mode Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. a #GtkIconView the spacing Sets the column with text for @icon_view to be @column. The text column must be of type #G_TYPE_STRING. A #GtkIconView. A column in the currently used model, or -1 to display no text Sets the tip area of @tooltip to the area which @cell occupies in the item pointed to by @path. See also gtk_tooltip_set_tip_area(). See also gtk_icon_view_set_tooltip_column() for a simpler alternative. a #GtkIconView a #GtkTooltip a #GtkTreePath a #GtkCellRenderer or %NULL If you only plan to have simple (text-only) tooltips on full items, you can use this function to have #GtkIconView handle these automatically for you. @column should be set to the column in @icon_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, #GtkWidget:has-tooltip will be set to %TRUE and @icon_view will connect a #GtkWidget::query-tooltip signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. a #GtkIconView an integer, which is a valid column number for @icon_view’s model Sets the tip area of @tooltip to be the area covered by the item at @path. See also gtk_icon_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). a #GtkIconView a #GtkTooltip a #GtkTreePath Unselects all the icons. A #GtkIconView. Unselects the row at @path. A #GtkIconView. The #GtkTreePath to be unselected. Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this method sets #GtkIconView:reorderable to %FALSE. a #GtkIconView The activate-on-single-click property specifies whether the "item-activated" signal will be emitted after a single click. The #GtkCellArea used to layout cell renderers for this view. If no area is specified when creating the icon view with gtk_icon_view_new_with_area() a #GtkCellAreaBox will be used. The column-spacing property specifies the space which is inserted between the columns of the icon view. 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. The item-orientation property specifies how the cells (i.e. the icon and the text) of the item are positioned relative to each other. The item-padding property specifies the padding around each of the icon view's item. 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. The margin property specifies the space which is inserted at the edges of the icon view. 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. 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. The reorderable property specifies if the items can be reordered by DND. The row-spacing property specifies the space which is inserted between the rows of the icon view. The ::selection-mode property specifies the selection mode of icon view. If the mode is #GTK_SELECTION_MULTIPLE, rubberband selection is enabled, for the other modes, only keyboard selection is possible. The spacing property specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. 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. A [keybinding signal][GtkBindingSignal] 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. The ::item-activated signal is emitted when the method gtk_icon_view_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. the #GtkTreePath for the activated item The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] 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. the granularity of the move, as a #GtkMovementStep the number of @step units to move A [keybinding signal][GtkBindingSignal] 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. A [keybinding signal][GtkBindingSignal] 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. The ::selection-changed signal is emitted when the selection (i.e. the set of selected items) changes. A [keybinding signal][GtkBindingSignal] 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. A [keybinding signal][GtkBindingSignal] 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. A #GtkIconView The #GtkTreePath to be activated A #GtkIconView. A #GtkIconView. An enum for determining where a dropped item goes. no drop possible dropped item replaces the item droppped item is inserted to the left dropped item is inserted to the right dropped item is inserted above dropped item is inserted below A function used by gtk_icon_view_selected_foreach() to map all selected rows. It will be called on every selected row in the view. a #GtkIconView The #GtkTreePath of a selected row user data The #GtkImage widget displays an image. Various kinds of object can be displayed as an image; most typically, you would load a #GdkPixbuf ("pixel buffer") from a file, and then display that. There’s a convenience function to do this, gtk_image_new_from_file(), used as follows: |[<!-- language="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_new_from_file(), then create the #GtkImage with gtk_image_new_from_pixbuf(). The image file may contain an animation, if so the #GtkImage will display an animation (#GdkPixbufAnimation) instead of a static image. #GtkImage is a subclass of #GtkMisc, which implies that you can align it (center, left, right) and add padding to it, using #GtkMisc methods. #GtkImage is a “no window” widget (has no #GdkWindow 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 #GtkEventBox, then connect to the event signals on the event box. ## Handling button press events on a #GtkImage. |[<!-- language="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 #GtkMisc). 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 #GdkPixbuf using gdk_pixbuf_new_from_inline(). # CSS nodes GtkImage has a single CSS node with the name image. The style classes may appear on image CSS nodes: .icon-dropshadow, .lowres-icon. Creates a new empty #GtkImage widget. a newly created #GtkImage widget. Creates a #GtkImage displaying the given animation. The #GtkImage does not assume a reference to the animation; you still need to unref it if you own references. #GtkImage 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. a new #GtkImage widget an animation Creates a new #GtkImage displaying the file @filename. If the file isn’t found or can’t be loaded, the resulting #GtkImage will display a “broken image” icon. This function never returns %NULL, it always returns a valid #GtkImage 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_new_from_file() to load the file yourself, then create the #GtkImage from the pixbuf. (Or for animations, use gdk_pixbuf_animation_new_from_file()). The storage type (gtk_image_get_storage_type()) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new #GtkImage a filename Creates a #GtkImage 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. a new #GtkImage displaying the themed icon an icon a stock icon size (#GtkIconSize) Creates a #GtkImage 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. a new #GtkImage displaying the themed icon an icon name or %NULL a stock icon size (#GtkIconSize) Creates a #GtkImage displaying an icon set. Sample stock sizes are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of using this function, usually it’s better to create a #GtkIconFactory, put your icon sets in the icon factory, add the icon factory to the list of default factories with gtk_icon_factory_add_default(), and then use gtk_image_new_from_stock(). This will allow themes to override the icon you ship with your application. The #GtkImage does not assume a reference to the icon set; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. Use gtk_image_new_from_icon_name() instead. a new #GtkImage a #GtkIconSet a stock icon size (#GtkIconSize) Creates a new #GtkImage displaying @pixbuf. The #GtkImage does not assume a reference to the pixbuf; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. Note that this function just creates an #GtkImage from the pixbuf. The #GtkImage created will not react to state changes. Should you want that, you should use gtk_image_new_from_icon_name(). a new #GtkImage a #GdkPixbuf, or %NULL Creates a new #GtkImage displaying the resource file @resource_path. If the file isn’t found or can’t be loaded, the resulting #GtkImage will display a “broken image” icon. This function never returns %NULL, it always returns a valid #GtkImage 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_new_from_file() to load the file yourself, then create the #GtkImage from the pixbuf. (Or for animations, use gdk_pixbuf_animation_new_from_file()). The storage type (gtk_image_get_storage_type()) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new #GtkImage a resource path Creates a #GtkImage displaying a stock icon. Sample stock icon names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. Sample stock sizes are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. If the stock icon name isn’t known, the image will be empty. You can register your own stock icon names, see gtk_icon_factory_add_default() and gtk_icon_factory_add(). Use gtk_image_new_from_icon_name() instead. a new #GtkImage displaying the stock icon a stock icon name a stock icon size (#GtkIconSize) Creates a new #GtkImage displaying @surface. The #GtkImage does not assume a reference to the surface; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours. a new #GtkImage a #cairo_surface_t, or %NULL Resets the image to be empty. a #GtkImage Gets the #GdkPixbufAnimation being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ANIMATION (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned animation. the displayed animation, or %NULL if the image is empty a #GtkImage Gets the #GIcon and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned #GIcon. a #GtkImage place to store a #GIcon, or %NULL place to store an icon size (#GtkIconSize), or %NULL Gets the icon name and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see gtk_image_get_storage_type()). The returned string is owned by the #GtkImage and should not be freed. a #GtkImage place to store an icon name, or %NULL place to store an icon size (#GtkIconSize), or %NULL Gets the icon set and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()). Use gtk_image_get_icon_name() instead. a #GtkImage location to store a #GtkIconSet, or %NULL location to store a stock icon size (#GtkIconSize), or %NULL Gets the #GdkPixbuf being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PIXBUF (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned pixbuf. the displayed pixbuf, or %NULL if the image is empty a #GtkImage Gets the pixel size used for named icons. the pixel size used for named icons. a #GtkImage Gets the stock icon name and size being displayed by the #GtkImage. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()). The returned string is owned by the #GtkImage and should not be freed. Use gtk_image_get_icon_name() instead. a #GtkImage place to store a stock icon name, or %NULL place to store a stock icon size (#GtkIconSize), or %NULL Gets the type of representation being used by the #GtkImage to store image data. If the #GtkImage has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a #GtkImage Causes the #GtkImage to display the given animation (or display nothing, if you set the animation to %NULL). a #GtkImage the #GdkPixbufAnimation See gtk_image_new_from_file() for details. a #GtkImage a filename or %NULL See gtk_image_new_from_gicon() for details. a #GtkImage an icon an icon size (#GtkIconSize) See gtk_image_new_from_icon_name() for details. a #GtkImage an icon name or %NULL an icon size (#GtkIconSize) See gtk_image_new_from_icon_set() for details. Use gtk_image_set_from_icon_name() instead. a #GtkImage a #GtkIconSet a stock icon size (#GtkIconSize) See gtk_image_new_from_pixbuf() for details. a #GtkImage a #GdkPixbuf or %NULL See gtk_image_new_from_resource() for details. a #GtkImage a resource path or %NULL See gtk_image_new_from_stock() for details. Use gtk_image_set_from_icon_name() instead. a #GtkImage a stock icon name a stock icon size (#GtkIconSize) See gtk_image_new_from_surface() for details. a #GtkImage a cairo_surface_t or %NULL 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 gtk_image_set_from_icon_name(). a #GtkImage the new pixel size The GIcon displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. Use #GtkImage:icon-name instead. The "pixel-size" property can be used to specify a fixed size overriding the #GtkImage:icon-size property for images of type %GTK_IMAGE_ICON_NAME. A path to a resource file to display. Use #GtkImage:icon-name instead. Whether the icon displayed in the GtkImage will use standard icon names fallback. The value of this property is only relevant for images of type %GTK_IMAGE_ICON_NAME and %GTK_IMAGE_GICON. A GtkImageMenuItem is a menu item which has an icon next to the text label. This is functionally equivalent to: |[<!-- language="C" --> GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6); GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU); GtkWidget *label = gtk_label_new ("Music"); GtkWidget *menu_item = gtk_menu_item_new (); gtk_container_add (GTK_CONTAINER (box), icon); gtk_container_add (GTK_CONTAINER (box), label); gtk_container_add (GTK_CONTAINER (menu_item), box); gtk_widget_show_all (menu_item); ]| Note that the user may disable display of menu icons using the #GtkSettings:gtk-menu-images setting, so make sure to still fill in the text label. If you want to ensure that your menu items show an icon you are strongly encouraged to use a #GtkMenuItem with a #GtkImage instead. #GtkImageMenuItem has been deprecated since GTK+ 3.10. If you want to display an icon in a menu item, you should use #GtkMenuItem and pack a #GtkBox with a #GtkImage and a #GtkLabel instead. You should also consider using #GtkBuilder and the XML #GMenu description for creating menus, by following the [GMenu guide][https://developer.gnome.org/GMenu/]. You should consider using icons in menu items only sparingly, and for "objects" (or "nouns") elements only, like bookmarks, files, and links; "actions" (or "verbs") should not have icons. Furthermore, if you would like to display keyboard accelerator, you must pack the accel label into the box using gtk_box_pack_end() and align the label, otherwise the accelerator will not display correctly. The following code snippet adds a keyboard accelerator to the menu item, with a key binding of Ctrl+M: |[<!-- language="C" --> GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6); GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU); GtkWidget *label = gtk_accel_label_new ("Music"); GtkWidget *menu_item = gtk_menu_item_new (); GtkAccelGroup *accel_group = gtk_accel_group_new (); gtk_container_add (GTK_CONTAINER (box), icon); gtk_label_set_use_underline (GTK_LABEL (label), TRUE); gtk_label_set_xalign (GTK_LABEL (label), 0.0); gtk_widget_add_accelerator (menu_item, "activate", accel_group, GDK_KEY_m, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE); gtk_accel_label_set_accel_widget (GTK_ACCEL_LABEL (label), menu_item); gtk_box_pack_end (GTK_BOX (box), label, TRUE, TRUE, 0); gtk_container_add (GTK_CONTAINER (menu_item), box); gtk_widget_show_all (menu_item); ]| Creates a new #GtkImageMenuItem with an empty label. Use gtk_menu_item_new() instead. a new #GtkImageMenuItem Creates a new #GtkImageMenuItem containing the image and text from a stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. If you want this menu item to have changeable accelerators, then pass in %NULL for accel_group. Next call gtk_menu_item_set_accel_path() with an appropriate path for the menu item, use gtk_stock_lookup() to look up the standard accelerator for the stock item, and if one is found, call gtk_accel_map_add_entry() to register it. Use gtk_menu_item_new_with_mnemonic() instead. a new #GtkImageMenuItem. the name of the stock item. the #GtkAccelGroup to add the menu items accelerator to, or %NULL. Creates a new #GtkImageMenuItem containing a label. Use gtk_menu_item_new_with_label() instead. a new #GtkImageMenuItem. the text of the menu item. Creates a new #GtkImageMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. Use gtk_menu_item_new_with_mnemonic() instead. a new #GtkImageMenuItem the text of the menu item, with an underscore in front of the mnemonic character Returns whether the menu item will ignore the #GtkSettings:gtk-menu-images setting and always show the image, if available. %TRUE if the menu item will always show the image a #GtkImageMenuItem Gets the widget that is currently set as the image of @image_menu_item. See gtk_image_menu_item_set_image(). the widget set as image of @image_menu_item a #GtkImageMenuItem Checks whether the label set in the menuitem is used as a stock id to select the stock item for the item. %TRUE if the label set in the menuitem is used as a stock id to select the stock item for the item a #GtkImageMenuItem Specifies an @accel_group to add the menu items accelerator to (this only applies to stock items so a stock item must already be set, make sure to call gtk_image_menu_item_set_use_stock() and gtk_menu_item_set_label() with a valid stock item first). If you want this menu item to have changeable accelerators then you shouldnt need this (see gtk_image_menu_item_new_from_stock()). a #GtkImageMenuItem the #GtkAccelGroup If %TRUE, the menu item will ignore the #GtkSettings:gtk-menu-images setting and always show the image, if available. Use this property if the menuitem would be useless or hard to use without the image. a #GtkImageMenuItem %TRUE if the menuitem should always show the image Sets the image of @image_menu_item to the given widget. Note that it depends on the show-menu-images setting whether the image will be displayed or not. a #GtkImageMenuItem. a widget to set as the image for the menu item. If %TRUE, the label set in the menuitem is used as a stock id to select the stock item for the item. a #GtkImageMenuItem %TRUE if the menuitem should use a stock item The Accel Group to use for stock accelerator keys Use gtk_widget_add_accelerator() instead If %TRUE, the menu item will always show the image, if available. Use this property only if the menuitem would be useless or hard to use without the image. Use a #GtkMenuItem containing a #GtkBox with a #GtkAccelLabel and a #GtkImage instead Child widget to appear next to the menu text. Use a #GtkMenuItem containing a #GtkBox with a #GtkAccelLabel and a #GtkImage instead If %TRUE, the label set in the menuitem is used as a stock id to select the stock item for the item. Use a named icon from the #GtkIconTheme instead The parent class. Describes the image data representation used by a #GtkImage. If you want to get the image from the widget, you can only get the currently-stored representation. e.g. if the gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can call gtk_image_get_pixbuf() but not gtk_image_get_stock(). For empty images, you can request any storage type (call any of the "get" functions), but they will all return %NULL values. there is no image displayed by the widget the widget contains a #GdkPixbuf the widget contains a [stock item name][gtkstock] the widget contains a #GtkIconSet the widget contains a #GdkPixbufAnimation the widget contains a named icon. This image type was added in GTK+ 2.6 the widget contains a #GIcon. This image type was added in GTK+ 2.14 the widget contains a #cairo_surface_t. This image type was added in GTK+ 3.10 #GtkInfoBar 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 #GtkDialog, which has a action area at the bottom, #GtkInfoBar has an action area at the side. The API of #GtkInfoBar is very similar to #GtkDialog, allowing you to add buttons to the action area with gtk_info_bar_add_button() or gtk_info_bar_new_with_buttons(). The sensitivity of action widgets can be controlled with gtk_info_bar_set_response_sensitive(). To add widgets to the main content area of a #GtkInfoBar, use gtk_info_bar_get_content_area() and add your widgets to the container. Similar to #GtkMessageDialog, the contents of a #GtkInfoBar can by classified as error message, warning, informational message, etc, by using gtk_info_bar_set_message_type(). GTK+ may use the message type to determine how the message is displayed. A simple example for using a #GtkInfoBar: |[<!-- language="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); ]| # GtkInfoBar as GtkBuildable The GtkInfoBar implementation of the GtkBuildable interface exposes the content area and action area as internal children with the names “content_area” and “action_area”. GtkInfoBar 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 GtkInfoBar 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. Creates a new #GtkInfoBar object. a new #GtkInfoBar object Creates a new #GtkInfoBar with buttons. Button text/response ID pairs should be listed, with a %NULL 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 #GtkResponseType enumeration. If the user clicks one of these dialog buttons, GtkInfoBar will emit the “response” signal with the corresponding response ID. a new #GtkInfoBar stock ID or text to go in first button, or %NULL response ID for first button, then additional buttons, ending with %NULL Emits the “response” signal with the given @response_id. a #GtkInfoBar a response ID Add an activatable widget to the action area of a #GtkInfoBar, connecting a signal handler that will emit the #GtkInfoBar::response signal on the message area when the widget is activated. The widget is appended to the end of the message areas action area. a #GtkInfoBar an activatable widget response ID for @child 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. the #GtkButton widget that was added a #GtkInfoBar text of button response ID for the button Adds more buttons, same as calling gtk_info_bar_add_button() repeatedly. The variable argument list should be %NULL-terminated as with gtk_info_bar_new_with_buttons(). Each button must have both text and response ID. a #GtkInfoBar button text or stock ID response ID for first button, then more text-response_id pairs, ending with %NULL Returns the action area of @info_bar. the action area a #GtkInfoBar Returns the content area of @info_bar. the content area a #GtkInfoBar Returns the message type of the message area. the message type of the message area. a #GtkInfoBar the current value of the GtkInfoBar:revealed property. a #GtkInfoBar Returns whether the widget will display a standard close button. %TRUE if the widget displays standard close button a #GtkInfoBar Emits the “response” signal with the given @response_id. a #GtkInfoBar a response ID 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 @info_bar to be added to a widget hierarchy. a #GtkInfoBar a response ID Sets the message type of the message area. GTK+ uses this type to determine how the message is displayed. a #GtkInfoBar a #GtkMessageType 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. a #GtkInfoBar a response ID TRUE for sensitive Sets the GtkInfoBar:revealed property to @revealed. This will cause @info_bar to show up with a slide-in transition. Note that this property does not automatically show @info_bar and thus won’t have any effect if it is invisible. a #GtkInfoBar The new value of the property If true, a standard close button is shown. When clicked it emits the response %GTK_RESPONSE_CLOSE. a #GtkInfoBar %TRUE to include a close button The type of the message. The type may be used to determine the appearance of the info bar. Whether to include a standard close button. The ::close signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to dismiss the info bar. The default binding for this signal is the Escape key. Emitted when an action widget is clicked or the application programmer calls gtk_dialog_response(). The @response_id depends on which action widget was clicked. the response ID a #GtkInfoBar a response ID 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 #GtkInputPurpose of the entry. Some common sense is expected when using these flags - mixing @GTK_INPUT_HINT_LOWERCASE with any of the uppercase hints makes no sense. This enumeration may be extended in the future; input methods should ignore unknown values. No special behaviour suggested Suggest checking for typos Suggest not checking for typos Suggest word completion Suggest to convert all text to lowercase Suggest to capitalize all text Suggest to capitalize the first character of each word Suggest to capitalize the first word of each sentence Suggest to not show an onscreen keyboard (e.g for a calculator that already has all the keys). The text is vertical. Since 3.18 Suggest offering Emoji support. Since 3.22.20 Suggest not offering Emoji support. Since 3.22.20 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 @GTK_INPUT_PURPOSE_DIGITS and @GTK_INPUT_PURPOSE_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”. Allow any character Allow only alphabetic characters Allow only digits Edited field expects numbers Edited field expects phone number Edited field expects URL Edited field expects email address Edited field expects the name of a person Like @GTK_INPUT_PURPOSE_FREE_FORM, but characters are hidden Like @GTK_INPUT_PURPOSE_DIGITS, but characters are hidden Allow any character, in addition to control codes The #GtkInvisible 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. Creates a new #GtkInvisible. a new #GtkInvisible. Creates a new #GtkInvisible object for a specified screen a newly created #GtkInvisible object a #GdkScreen which identifies on which the new #GtkInvisible will be created. Returns the #GdkScreen object associated with @invisible the associated #GdkScreen. a #GtkInvisible. Sets the #GdkScreen where the #GtkInvisible object will be displayed. a #GtkInvisible. a #GdkScreen. Describes how a rendered element connects to adjacent elements. No junctions. Element connects on the top-left corner. Element connects on the top-right corner. Element connects on the bottom-left corner. Element connects on the bottom-right corner. Element connects on the top side. Element connects on the bottom side. Element connects on the left side. Element connects on the right side. Used for justifying the text inside a #GtkLabel widget. (See also #GtkAlignment). The text is placed at the left edge of the label. The text is placed at the right edge of the label. The text is placed in the center of the label. The text is placed is distributed across the label. Key snooper functions are called before normal event delivery. They can be used to implement custom key event handling. %TRUE to stop further processing of @event, %FALSE to continue. the widget to which the event will be delivered the key event data supplied to gtk_key_snooper_install() The name used for the stock full offset included by #GtkLevelBar. The name used for the stock high offset included by #GtkLevelBar. The name used for the stock low offset included by #GtkLevelBar. The #GtkLabel widget displays a small amount of text. As the name implies, most labels are used to label another widget such as a #GtkButton, a #GtkMenuItem, or a #GtkComboBox. # CSS nodes |[<!-- language="plain" --> label ├── [selection] ├── [link] ┊ ╰── [link] ]| GtkLabel 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 #GtkShortcutsWindow, 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. # GtkLabel as GtkBuildable The GtkLabel implementation of the GtkBuildable 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 #PangoAttribute values for this label. An example of a UI definition fragment specifying Pango attributes: |[ <object class="GtkLabel"> <attributes> <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> </attributes> </object> ]| The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. # Mnemonics Labels may contain “mnemonics”. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as `"_File"`, to the functions gtk_label_new_with_mnemonic() or gtk_label_set_text_with_mnemonic(). Mnemonics automatically activate any activatable widget the label is inside, such as a #GtkButton; if the label is not inside the mnemonic’s target widget, you have to tell the label about the target using gtk_label_set_mnemonic_widget(). Here’s a simple example where the label is inside a button: |[<!-- language="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: |[<!-- language="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 #GtkEntry, you have to point the label at the entry with gtk_label_set_mnemonic_widget(): |[<!-- language="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: |[<!-- language="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 gtk_label_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 gtk_label_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 #PangoAttrList on a label; gtk_label_set_attributes() may be a simpler way to set attributes in some cases. Be careful though; #PangoAttrList 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 #PangoAttribute requires knowledge of the exact string being displayed, so translations will cause problems. # Selectable labels Labels can be made selectable with gtk_label_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 gtk_label_set_line_wrap(). gtk_label_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 #GtkWidget:halign and #GtkWidget:valign properties. The #GtkLabel:width-chars and #GtkLabel: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 #GtkLabel:width-chars and #GtkLabel: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: |[<!-- language="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 #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function. Creates a new label with the given text inside it. You can pass %NULL to get an empty label widget. the new #GtkLabel The text of the label Creates a new #GtkLabel, 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 gtk_label_set_mnemonic_widget(). If gtk_label_set_mnemonic_widget() is not called, then the first activatable ancestor of the #GtkLabel 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. the new #GtkLabel The text of the label, with an underscore in front of the mnemonic character Gets the angle of rotation for the label. See gtk_label_set_angle(). the angle of rotation for the label a #GtkLabel Gets the attribute list that was set on the label using gtk_label_set_attributes(), if any. This function does not reflect attributes that come from the labels markup (see gtk_label_set_markup()). If you want to get the effective attributes for the label, use pango_layout_get_attribute (gtk_label_get_layout (label)). the attribute list, or %NULL if none was set. a #GtkLabel 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 #GtkLabel::activate-link handler or for use in a #GtkWidget::query-tooltip handler. the currently active URI. The string is owned by GTK+ and must not be freed or modified. a #GtkLabel Returns the ellipsizing position of the label. See gtk_label_set_ellipsize(). #PangoEllipsizeMode a #GtkLabel Returns the justification of the label. See gtk_label_set_justify(). #GtkJustification a #GtkLabel Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup. (See gtk_label_get_text()). the text of the label widget. This string is owned by the widget and must not be modified or freed. a #GtkLabel Gets the #PangoLayout used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with gtk_label_get_layout_offsets(). The returned layout is owned by the @label so need not be freed by the caller. The @label is free to recreate its layout at any time, so it should be considered read-only. the #PangoLayout for this label a #GtkLabel Obtains the coordinates where the label will draw the #PangoLayout representing the text in the label; useful to convert mouse events into coordinates inside the #PangoLayout, e.g. to take some action if some part of the label is clicked. Of course you will need to create a #GtkEventBox to receive the events, and pack the label inside it, since labels are windowless (they return %FALSE from gtk_widget_get_has_window()). Remember when using the #PangoLayout functions you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. a #GtkLabel location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Returns whether lines in the label are automatically wrapped. See gtk_label_set_line_wrap(). %TRUE if the lines of the label are automatically wrapped. a #GtkLabel Returns line wrap mode used by the label. See gtk_label_set_line_wrap_mode(). %TRUE if the lines of the label are automatically wrapped. a #GtkLabel Gets the number of lines to which an ellipsized, wrapping label should be limited. See gtk_label_set_lines(). The number of lines a #GtkLabel Retrieves the desired maximum width of @label, in characters. See gtk_label_set_width_chars(). the maximum width of the label in characters. a #GtkLabel 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. GDK keyval usable for accelerators, or #GDK_KEY_VoidSymbol a #GtkLabel Retrieves the target of the mnemonic (keyboard shortcut) of this label. See gtk_label_set_mnemonic_widget(). the target of the label’s mnemonic, or %NULL if none has been set and the default algorithm will be used. a #GtkLabel Gets the value set by gtk_label_set_selectable(). %TRUE if the user can copy text from the label a #GtkLabel Gets the selected range of characters in the label, returning %TRUE if there’s a selection. %TRUE if selection is non-empty a #GtkLabel return location for start of selection, as a character offset return location for end of selection, as a character offset Returns whether the label is in single line mode. %TRUE when the label is in single line mode. a #GtkLabel 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 gtk_label_get_label()) the text in the label widget. This is the internal string used by the label, and must not be modified. a #GtkLabel Returns whether the label is currently keeping track of clicked links. %TRUE if clicked links are remembered a #GtkLabel Returns whether the label’s text is interpreted as marked up with the [Pango text markup language][PangoMarkupFormat]. See gtk_label_set_use_markup (). %TRUE if the label’s text will be parsed for markup. a #GtkLabel Returns whether an embedded underline in the label indicates a mnemonic. See gtk_label_set_use_underline(). %TRUE whether an embedded underline in the label indicates the mnemonic accelerator keys. a #GtkLabel Retrieves the desired width of @label, in characters. See gtk_label_set_width_chars(). the width of the label in characters. a #GtkLabel Gets the #GtkLabel:xalign property for @label. the xalign property a #GtkLabel Gets the #GtkLabel:yalign property for @label. the yalign property a #GtkLabel Selects a range of characters in the label, if the label is selectable. See gtk_label_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. a #GtkLabel start offset (in characters not bytes) end offset (in characters not bytes) 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. a #GtkLabel the angle that the baseline of the label makes with the horizontal, in degrees, measured counterclockwise Sets a #PangoAttrList; 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 #GtkLabel:use-underline or #GtkLabel: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. a #GtkLabel a #PangoAttrList, or %NULL Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire string. a #GtkLabel a #PangoEllipsizeMode Sets the alignment of the lines in the text of the label relative to each other. %GTK_JUSTIFY_LEFT is the default value when the widget is first created with gtk_label_new(). If you instead want to set the alignment of the label as a whole, use gtk_widget_set_halign() instead. gtk_label_set_justify() has no effect on labels containing only a single line. a #GtkLabel a #GtkJustification Sets the text of the label. The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the #GtkLabel:use-underline and #GtkLabel:use-markup properties. a #GtkLabel the new text to set for the label Toggles line wrapping within the #GtkLabel 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 gtk_widget_set_size_request(). a #GtkLabel the setting If line wrapping is on (see gtk_label_set_line_wrap()) this controls how the line wrapping is done. The default is %PANGO_WRAP_WORD which means wrap on word boundaries. a #GtkLabel the line wrapping mode 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. a #GtkLabel the desired number of lines, or -1 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(): |[<!-- language="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 #GtkLabel:use-markup property to %TRUE as a side effect. If you set the label contents using the #GtkLabel:label property you should also ensure that you set the #GtkLabel:use-markup property accordingly. See also: gtk_label_set_text() a #GtkLabel a markup string (see [Pango markup format][PangoMarkupFormat]) 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 gtk_label_set_mnemonic_widget(). a #GtkLabel a markup string (see [Pango markup format][PangoMarkupFormat]) Sets the desired maximum width in characters of @label to @n_chars. a #GtkLabel the new desired maximum width, in characters. If the label has been set so that it has an mnemonic key (using i.e. gtk_label_set_markup_with_mnemonic(), gtk_label_set_text_with_mnemonic(), gtk_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 #GtkButton or a #GtkNotebook tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a #GtkEntry next to the label) you need to set it explicitly using this function. The target widget will be accelerated by emitting the GtkWidget::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. a #GtkLabel the target #GtkWidget, or %NULL to unset The pattern of underlines you want under the existing text within the #GtkLabel widget. For example if the current text of the label says “FooBarBaz” passing a pattern of “___ ___” will underline “Foo” and “Baz” but not “Bar”. The #GtkLabel you want to set the pattern to. The pattern as described above. Selectable labels allow the user to select text from the label, for copy-and-paste. a #GtkLabel %TRUE to allow selecting text in the label Sets whether the label is in single line mode. a #GtkLabel %TRUE if the label should be in single line mode Sets the text within the #GtkLabel widget. It overwrites any text that was there before. This function will clear any previously set mnemonic accelerators, and set the #GtkLabel:use-underline property to %FALSE as a side effect. This function will set the #GtkLabel:use-markup property to %FALSE as a side effect. See also: gtk_label_set_markup() a #GtkLabel The text you want to set 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 gtk_label_set_mnemonic_widget(). a #GtkLabel a string Sets whether the label should keep track of clicked links (and use a different color for them). a #GtkLabel %TRUE to track visited links Sets whether the text of the label contains markup in [Pango’s text markup language][PangoMarkupFormat]. See gtk_label_set_markup(). a #GtkLabel %TRUE if the label’s text should be parsed for markup. If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key. a #GtkLabel %TRUE if underlines in the text indicate mnemonics Sets the desired width in characters of @label to @n_chars. a #GtkLabel the new desired width, in characters. Sets the #GtkLabel:xalign property for @label. a #GtkLabel the new xalign value, between 0 and 1 Sets the #GtkLabel:yalign property for @label. a #GtkLabel the new yalign value, between 0 and 1 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. The preferred place to ellipsize the string, if the label does not have enough room to display the entire string, specified as a #PangoEllipsizeMode. Note that setting this property to a value other than %PANGO_ELLIPSIZE_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 #GtkNotebook tab-expand child property is set to %TRUE. Other ways to set a label's width are gtk_widget_set_size_request() and gtk_label_set_width_chars(). The contents of the label. If the string contains [Pango XML markup][PangoMarkupFormat], you will have to set the #GtkLabel:use-markup property to %TRUE in order for the label to display the markup attributes. See also gtk_label_set_markup() for a convenience function that sets both this property and the #GtkLabel:use-markup property at the same time. If the string contains underlines acting as mnemonics, you will have to set the #GtkLabel:use-underline property to %TRUE in order for the label to display them. 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. 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 #GtkLabel:width-chars and #GtkLabel:max-width-chars determine the width of ellipsized and wrapped labels. 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. Set this property to %TRUE to make the label track which links have been visited. It will then apply the #GTK_STATE_FLAG_VISITED when rendering this link, in addition to #GTK_STATE_FLAG_LINK. 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 #GtkLabel:width-chars and #GtkLabel:max-width-chars determine the width of ellipsized and wrapped labels. If line wrapping is on (see the #GtkLabel:wrap property) this controls how the line wrapping is done. The default is %PANGO_WRAP_WORD, which means wrap on word boundaries. The xalign property determines the horizontal aligment of the label text inside the labels size allocation. Compare this to #GtkWidget:halign, which determines how the labels size allocation is positioned in the space available for the label. The yalign property determines the vertical aligment of the label text inside the labels size allocation. Compare this to #GtkWidget:valign, which determines how the labels size allocation is positioned in the space available for the label. A [keybinding signal][GtkBindingSignal] 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. 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(). %TRUE if the link has been activated the URI that is activated The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard. The default binding for this signal is Ctrl-c. The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] 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 the granularity of the move, as a #GtkMovementStep the number of @step units to move %TRUE if the move should extend the selection 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. the menu that is being populated #GtkLayout is similar to #GtkDrawingArea 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 #GtkScrollable, and can contain child widgets since it’s a #GtkContainer. If you just want to draw, a #GtkDrawingArea is a better choice since it has lower overhead. If you just need to position child widgets at specific points, then #GtkFixed provides that functionality on its own. When handling expose events on a #GtkLayout, you must draw to the #GdkWindow returned by gtk_layout_get_bin_window(), rather than to the one returned by gtk_widget_get_window() as you would for a #GtkDrawingArea. Creates a new #GtkLayout. Unless you have a specific adjustment you’d like the layout to use for scrolling, pass %NULL for @hadjustment and @vadjustment. a new #GtkLayout horizontal scroll adjustment, or %NULL vertical scroll adjustment, or %NULL Retrieve the bin window of the layout used for drawing operations. a #GdkWindow a #GtkLayout This function should only be called after the layout has been placed in a #GtkScrolledWindow or otherwise configured for scrolling. It returns the #GtkAdjustment used for communication between the horizontal scrollbar and @layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_get_hadjustment() horizontal scroll adjustment a #GtkLayout 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 (). a #GtkLayout location to store the width set on @layout, or %NULL location to store the height set on @layout, or %NULL This function should only be called after the layout has been placed in a #GtkScrolledWindow or otherwise configured for scrolling. It returns the #GtkAdjustment used for communication between the vertical scrollbar and @layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_get_vadjustment() vertical scroll adjustment a #GtkLayout Moves a current child of @layout to a new position. a #GtkLayout a current child of @layout X position to move to Y position to move to Adds @child_widget to @layout, at position (@x,@y). @layout becomes the new parent container of @child_widget. a #GtkLayout child widget X position of child widget Y position of child widget Sets the horizontal scroll adjustment for the layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_set_hadjustment() a #GtkLayout new scroll adjustment Sets the size of the scrollable area of the layout. a #GtkLayout width of entire scrollable area height of entire scrollable area Sets the vertical scroll adjustment for the layout. See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details. Use gtk_scrollable_set_vadjustment() a #GtkLayout new scroll adjustment The #GtkLevelBar 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 gtk_level_bar_set_value() to set the current value, and gtk_level_bar_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 |[<!-- language="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 gtk_level_bar_set_min_value() and gtk_level_bar_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 #GTK_LEVEL_BAR_MODE_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. GtkLevelBar was introduced in GTK+ 3.6. # GtkLevelBar as GtkBuildable The GtkLevelBar implementation of the GtkBuildable 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 |[<!-- language="plain" --> levelbar[.discrete] ╰── trough ├── block.filled.level-name ┊ ├── block.empty ┊ ]| GtkLevelBar 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. Creates a new #GtkLevelBar. a #GtkLevelBar. Utility constructor that creates a new #GtkLevelBar for the specified interval. a #GtkLevelBar a positive value a positive 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 #GtkLevelBar: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. a #GtkLevelBar the name of the new offset the value for the new offset Return the value of the #GtkLevelBar:inverted property. %TRUE if the level bar is inverted a #GtkLevelBar Returns the value of the #GtkLevelBar:max-value property. a positive value a #GtkLevelBar Returns the value of the #GtkLevelBar:min-value property. a positive value a #GtkLevelBar Returns the value of the #GtkLevelBar:mode property. a #GtkLevelBarMode a #GtkLevelBar Fetches the value specified for the offset marker @name in @self, returning %TRUE in case an offset named @name was found. %TRUE if the specified offset is found a #GtkLevelBar the name of an offset in the bar location where to store the value Returns the value of the #GtkLevelBar:value property. a value in the interval between #GtkLevelBar:min-value and #GtkLevelBar:max-value a #GtkLevelBar Removes an offset marker previously added with gtk_level_bar_add_offset_value(). a #GtkLevelBar the name of an offset in the bar Sets the value of the #GtkLevelBar:inverted property. a #GtkLevelBar %TRUE to invert the level bar Sets the value of the #GtkLevelBar:max-value property. You probably want to update preexisting level offsets after calling this function. a #GtkLevelBar a positive value Sets the value of the #GtkLevelBar:min-value property. You probably want to update preexisting level offsets after calling this function. a #GtkLevelBar a positive value Sets the value of the #GtkLevelBar:mode property. a #GtkLevelBar a #GtkLevelBarMode Sets the value of the #GtkLevelBar:value property. a #GtkLevelBar a value in the interval between #GtkLevelBar:min-value and #GtkLevelBar:max-value Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction. The #GtkLevelBar:max-value property determaxes the maximum value of the interval that can be displayed by the bar. The #GtkLevelBar:min-value property determines the minimum value of the interval that can be displayed by the bar. The #GtkLevelBar:mode property determines the way #GtkLevelBar interprets the value properties to draw the level fill area. Specifically, when the value is #GTK_LEVEL_BAR_MODE_CONTINUOUS, #GtkLevelBar will draw a single block representing the current value in that area; when the value is #GTK_LEVEL_BAR_MODE_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 #GtkLevelBar:min-value and #GtkLevelBar:max-value. The #GtkLevelBar:value property determines the currently filled value of the level bar. Emitted when an offset specified on the bar changes value as an effect to gtk_level_bar_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. the name of the offset that changed value Describes how #GtkLevelBar contents should be rendered. Note that this enumeration could be extended with additional modes in the future. the bar has a continuous mode the bar has a discrete mode The type of license for an application. This enumeration can be expanded at later date. No license specified A license text is going to be specified by the developer The GNU General Public License, version 2.0 or later The GNU General Public License, version 3.0 or later The GNU Lesser General Public License, version 2.1 or later The GNU Lesser General Public License, version 3.0 or later The BSD standard license The MIT/X11 standard license The Artistic License, version 2.0 The GNU General Public License, version 2.0 only. Since 3.12. The GNU General Public License, version 3.0 only. Since 3.12. The GNU Lesser General Public License, version 2.1 only. Since 3.12. The GNU Lesser General Public License, version 3.0 only. Since 3.12. The GNU Affero General Public License, version 3.0 or later. Since: 3.22. The GNU Affero General Public License, version 3.0 only. Since: 3.22.27. A GtkLinkButton is a #GtkButton 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 gtk_link_button_new() or gtk_link_button_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 GtkLinkButton can be set specifically using gtk_link_button_set_uri(), and retrieved using gtk_link_button_get_uri(). By default, GtkLinkButton calls gtk_show_uri_on_window() when the button is clicked. This behaviour can be overridden by connecting to the #GtkLinkButton::activate-link signal and returning %TRUE from the signal handler. # CSS nodes GtkLinkButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .link style class. Creates a new #GtkLinkButton with the URI as its text. a new link button widget. a valid URI Creates a new #GtkLinkButton containing a label. a new link button widget. a valid URI the text of the button Retrieves the URI set using gtk_link_button_set_uri(). a valid URI. The returned string is owned by the link button and should not be modified or freed. a #GtkLinkButton Retrieves the “visited” state of the URI where the #GtkLinkButton 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 gtk_link_button_set_visited(). %TRUE if the link has been visited, %FALSE otherwise a #GtkLinkButton Sets @uri as the URI where the #GtkLinkButton points. As a side-effect this unsets the “visited” state of the button. a #GtkLinkButton a valid URI Sets the “visited” state of the URI where the #GtkLinkButton points. See gtk_link_button_get_visited() for more details. a #GtkLinkButton the new “visited” state The URI bound to this button. The 'visited' state of this button. A visited link is drawn in a different color. The ::activate-link signal is emitted each time the #GtkLinkButton has been clicked. The default handler will call gtk_show_uri_on_window() with the URI stored inside the #GtkLinkButton: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. The #GtkLinkButtonClass contains only private data. A GtkListBox is a vertical container that contains GtkListBoxRow 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 GtkListBox is often an alternative to #GtkTreeView, especially when the list contents has a more complicated layout than what is allowed by a #GtkCellRenderer, or when the contents is interactive (i.e. has a button in it). Although a #GtkListBox must have only #GtkListBoxRow children you can add any kind of widget to it via gtk_container_add(), and a #GtkListBoxRow widget will automatically be inserted between the list and the widget. #GtkListBoxRows can be marked as activatable or selectable. If a row is activatable, #GtkListBox::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 GtkListBox widget was added in GTK+ 3.10. # GtkListBox as GtkBuildable The GtkListBox implementation of the #GtkBuildable interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a <child> element. See gtk_list_box_set_placeholder() for info. # CSS nodes |[<!-- language="plain" --> list ╰── row[.activatable] ]| GtkListBox uses a single CSS node named list. Each GtkListBoxRow uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate. Creates a new #GtkListBox container. a new #GtkListBox Select all children of @box, if the selection mode allows it. a #GtkListBox Unselect all children of @box, if the selection mode allows it. a #GtkListBox Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with gtk_list_box_insert() or gtk_container_add()) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in GtkListBox. When using a model, filtering and sorting should be implemented by the model. a #GtkListBox the #GListModel to be bound to @box a function that creates widgets for items or %NULL in case you also passed %NULL as @model user data passed to @create_widget_func function for freeing @user_data This is a helper function for implementing DnD onto a #GtkListBox. The passed in @row will be highlighted via gtk_drag_highlight(), and any previously highlighted row will be unhighlighted. The row will also be unhighlighted when the widget gets a drag leave event. a #GtkListBox a #GtkListBoxRow If a row has previously been highlighted via gtk_list_box_drag_highlight_row() it will have the highlight removed. a #GtkListBox Returns whether rows activate on single clicks. %TRUE if rows are activated on single click, %FALSE otherwise a #GtkListBox Gets the adjustment (if any) that the widget uses to for vertical scrolling. the adjustment a #GtkListBox 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, %NULL is returned. the child #GtkWidget or %NULL a #GtkListBox the index of the row Gets the row at the @y position. the row or %NULL in case no row exists for the given y coordinate. a #GtkListBox position Gets the selected row. Note that the box may allow multiple selection, in which case you should use gtk_list_box_selected_foreach() to find all selected rows. the selected row a #GtkListBox Creates a list of all selected children. A #GList containing the #GtkWidget for each selected child. Free with g_list_free() when done. a #GtkListBox Gets the selection mode of the listbox. a #GtkSelectionMode a #GtkListBox Insert the @child into the @box 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 gtk_container_add(). If @position is -1, or larger than the total number of items in the @box, then the @child will be appended to the end. a #GtkListBox the #GtkWidget to add the position to insert @child in Update the filtering for all rows. Call this when result of the filter function on the @box 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. a #GtkListBox Update the separators for all rows. Call this when result of the header function on the @box is changed due to an external factor. a #GtkListBox Update the sorting for all rows. Call this when result of the sort function on the @box is changed due to an external factor. a #GtkListBox 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 gtk_container_add(). a #GtkListBox the #GtkWidget to add Select all children of @box, if the selection mode allows it. a #GtkListBox Make @row the currently selected row. a #GtkListBox The row to select or %NULL Calls a function for each selected child. Note that the selection cannot be modified from within this function. a #GtkListBox the function to call for each selected child user data to pass to the function If @single is %TRUE, rows will be activated when you click on them, otherwise you need to double-click. a #GtkListBox a boolean 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 @box is packed inside a #GtkScrolledWindow the adjustment from that will be picked up automatically, so there is no need to manually do that. a #GtkListBox the adjustment, or %NULL By setting a filter function on the @box 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 gtk_list_box_row_changed()) or when gtk_list_box_invalidate_filter() is called. Note that using a filter function is incompatible with using a model (see gtk_list_box_bind_model()). a #GtkListBox callback that lets you filter which rows to show user data passed to @filter_func destroy notifier for @user_data By setting a header function on the @box 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 gtk_list_box_row_get_header() and either update the state of the widget as needed, or set a new one using gtk_list_box_row_set_header(). If no header is needed, set the header to %NULL. 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 gtk_list_box_row_changed()) and when the row before changes (either by gtk_list_box_row_changed() on the previous row, or when the previous row becomes a different row). It is also called for all rows when gtk_list_box_invalidate_headers() is called. a #GtkListBox callback that lets you add row headers user data passed to @update_header destroy notifier for @user_data Sets the placeholder widget that is shown in the list when it doesn't display any visible children. a #GtkListBox a #GtkWidget or %NULL Sets how selection works in the listbox. See #GtkSelectionMode for details. a #GtkListBox The #GtkSelectionMode By setting a sort function on the @box 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 gtk_list_box_row_changed()) and when gtk_list_box_invalidate_sort() is called. Note that using a sort function is incompatible with using a model (see gtk_list_box_bind_model()). a #GtkListBox the sort function user data passed to @sort_func destroy notifier for @user_data Unselect all children of @box, if the selection mode allows it. a #GtkListBox Unselects a single row of @box, if the selection mode allows it. a #GtkListBox the row to unselected The ::row-activated signal is emitted when a row has been activated by the user. the activated row The ::row-selected signal is emitted when a new row is selected, or (with a %NULL @row) when the selection is cleared. When the @box is using #GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the #GtkListBox::selected-rows-changed signal instead. the selected row The ::select-all signal is a [keybinding signal][GtkBindingSignal] 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. The ::selected-rows-changed signal is emitted when the set of selected rows changes. The ::unselect-all signal is a [keybinding signal][GtkBindingSignal] 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. The parent class. a #GtkListBox a #GtkListBox Called for list boxes that are bound to a #GListModel with gtk_list_box_bind_model() for each item that gets added to the model. Versions of GTK+ prior to 3.18 called gtk_widget_show_all() on the rows created by the GtkListBoxCreateWidgetFunc, but this forced all widgets inside the row to be shown, and is no longer the case. Applications should be updated to show the desired row widgets. a #GtkWidget that represents @item the item from the model for which to create a widget for user data Will be called whenever the row changes or is added and lets you control if the row should be visible or not. %TRUE if the row should be visible, %FALSE otherwise the row that may be filtered user data A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the @box. a #GtkListBox a #GtkListBoxRow user data Creates a new #GtkListBoxRow, to be used as a child of a #GtkListBox. a new #GtkListBoxRow Marks @row 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 gtk_list_box_row_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 gtk_list_box_invalidate_sort() on any model change, but that is more expensive. a #GtkListBoxRow Gets the value of the #GtkListBoxRow:activatable property for this row. %TRUE if the row is activatable a #GtkListBoxRow Returns the current header of the @row. 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. the current header, or %NULL if none a #GtkListBoxRow Gets the current index of the @row in its #GtkListBox container. the index of the @row, or -1 if the @row is not in a listbox a #GtkListBoxRow Gets the value of the #GtkListBoxRow:selectable property for this row. %TRUE if the row is selectable a #GtkListBoxRow Returns whether the child is currently selected in its #GtkListBox container. %TRUE if @row is selected a #GtkListBoxRow Set the #GtkListBoxRow:activatable property for this row. a #GtkListBoxRow %TRUE to mark the row as activatable Sets the current header of the @row. 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. a #GtkListBoxRow the header, or %NULL Set the #GtkListBoxRow:selectable property for this row. a #GtkListBoxRow %TRUE to mark the row as selectable The property determines whether the #GtkListBox::row-activated signal will be emitted for this row. The property determines whether this row can be selected. 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 #GtkListBox::row-activated signal on the row’s parent #GtkListBox. The parent class. Compare two rows to determine which should be first. < 0 if @row1 should be before @row2, 0 if they are equal and > 0 otherwise the first row the second row user data Whenever @row changes or which row is before @row changes this is called, which lets you update the header on @row. You may remove or set a new one via gtk_list_box_row_set_header() or just change the state of the current header widget. the row to update the row before @row, or %NULL if it is first user data The #GtkListStore object is a list model for use with a #GtkTreeView widget. It implements the #GtkTreeModel interface, and consequentialy, can use all of the methods available there. It also implements the #GtkTreeSortable interface so it can be sorted by the view. Finally, it also implements the tree [drag and drop][gtk3-GtkTreeView-drag-and-drop] interfaces. The #GtkListStore 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 #GtkListStore 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 gtk_tree_model_row_changed() to emit the #GtkTreeModel::row_changed signal. This most commonly affects lists with #GdkPixbufs stored. An example for creating a simple list store: |[<!-- language="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 #GtkListStore 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 #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST 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 gtk_list_store_insert_with_values() and gtk_list_store_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 #GtkTreeModel signaling. In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() will first create a row, which triggers the #GtkTreeModel::row-inserted signal on #GtkListStore. The row, however, is still empty, and any signal handler connecting to #GtkTreeModel::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 #GtkListStore inside a #GtkTreeModelFilter and are using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the #GtkListStore will cause the #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that. # GtkListStore as GtkBuildable The GtkListStore implementation of the GtkBuildable 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: |[<!-- language="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> ]| 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 #GtkListStore with three columns, of type int, string and #GdkPixbuf respectively. a new #GtkListStore number of columns in the list store all #GType types for the columns, from first to last Non-vararg creation function. Used primarily by language bindings. a new #GtkListStore number of columns in the list store an array of #GType types for the columns, from first to last Appends a new row to @list_store. @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 gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the appended row Removes all rows from the list store. a #GtkListStore. 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 gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the new row position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, 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 gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL Inserts a new row before @sibling. If @sibling is %NULL, 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 gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL 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 |[<!-- language="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, gtk_list_store_insert_with_values() should generally be preferred when inserting rows in a sorted list store. A #GtkListStore An unset #GtkTreeIter to set to the new row, or %NULL position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_list_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings. A #GtkListStore An unset #GtkTreeIter to set to the new row, or %NULL. position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays > This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this #GtkListStore. %TRUE if the iter is valid, %FALSE if the iter is invalid. A #GtkListStore. A #GtkTreeIter. Moves @iter in @store to the position after @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the list. A #GtkListStore. A #GtkTreeIter. A #GtkTreeIter or %NULL. Moves @iter in @store to the position before @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the list. A #GtkListStore. A #GtkTreeIter. A #GtkTreeIter, or %NULL. Prepends a new row to @list_store. @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 gtk_list_store_set() or gtk_list_store_set_value(). A #GtkListStore An unset #GtkTreeIter to set to the prepend row 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 @list_store. %TRUE if @iter is valid, %FALSE if not. A #GtkListStore A valid #GtkTreeIter Reorders @store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. A #GtkListStore. 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. 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. a #GtkListStore row iterator pairs of column number and value, terminated with -1 This function is meant primarily for #GObjects that inherit from #GtkListStore, and should only be used when constructing a new #GtkListStore. It will not function after a row has been added, or a method on the #GtkTreeModel interface is called. A #GtkListStore Number of columns for the list store An array length n of #GTypes See gtk_list_store_set(); this version takes a va_list for use by language bindings. A #GtkListStore A valid #GtkTreeIter for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. A #GtkListStore A valid #GtkTreeIter for the row being modified column number to modify new value for the cell A variant of gtk_list_store_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. A #GtkListStore A valid #GtkTreeIter for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in @store. Note that this function only works with unsorted stores. A #GtkListStore. A #GtkTreeIter. Another #GtkTreeIter. GtkLockButton 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 #GPermission object. Concrete implementations of #GPermission may use PolicyKit or some other authorization framework. To obtain a PolicyKit-based #GPermission, 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:  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:  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:  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 #GtkLockButton:text-lock, #GtkLockButton:text-unlock, #GtkLockButton:tooltip-lock, #GtkLockButton:tooltip-unlock and #GtkLockButton:tooltip-not-authorized properties. Creates a new lock button which reflects the @permission. a new #GtkLockButton a #GPermission Obtains the #GPermission object that controls @button. the #GPermission of @button a #GtkLockButton Sets the #GPermission object that controls @button. a #GtkLockButton a #GPermission object, or %NULL The parent class. Like gtk_get_major_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. The maximum length of sequences in compose tables. Like gtk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. Like gtk_get_minor_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. A #GtkMenu is a #GtkMenuShell that implements a drop down menu consisting of a list of #GtkMenuItem objects which can be navigated and activated by the user to perform application functions. A #GtkMenu is most commonly dropped down by activating a #GtkMenuItem in a #GtkMenuBar or popped up by activating a #GtkMenuItem in another #GtkMenu. A #GtkMenu can also be popped up by activating a #GtkComboBox. Other composite widgets such as the #GtkNotebook can pop up a #GtkMenu as well. Applications can display a #GtkMenu as a popup menu by calling the gtk_menu_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. |[<!-- language="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. |[<!-- language="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 |[<!-- language="plain" --> menu ├── arrow.top ├── <child> ┊ ├── <child> ╰── arrow.bottom ]| The main CSS node of GtkMenu has name menu, and there are two subnodes with name arrow, for scrolling menu arrows. These subnodes get the .top and .bottom style classes. Creates a new #GtkMenu a new #GtkMenu Creates a #GtkMenu and populates it with menu items and submenus according to @model. The created menu items are connected to actions found in the #GtkApplicationWindow to which the menu belongs - typically by means of being attached to a widget (see gtk_menu_attach_to_widget()) that is contained within the #GtkApplicationWindows widget hierarchy. Actions can also be added using gtk_widget_insert_action_group() on the menu's attach widget or on any of its parent widgets. a new #GtkMenu a #GMenuModel Returns a list of the menus which are attached to this widget. This list is owned by GTK+ and must not be modified. the list of menus attached to his widget. a #GtkWidget Adds a new #GtkMenuItem 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 gtk_menu_detach(). a #GtkMenu a #GtkMenuItem The column number to attach the left side of the item to The column number to attach the right side of the item to The row number to attach the top of the item to The row number to attach the bottom of the item to Attaches the menu to the widget and provides a callback function that will be invoked when the menu calls gtk_menu_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. a #GtkMenu the #GtkWidget that the menu will be attached to the user supplied callback function that will be called when the menu calls gtk_menu_detach() Detaches the menu from the widget to which it had been attached. This function will call the callback function, @detacher, provided when the gtk_menu_attach_to_widget() function was called. a #GtkMenu Gets the #GtkAccelGroup which holds global accelerators for the menu. See gtk_menu_set_accel_group(). the #GtkAccelGroup associated with the menu a #GtkMenu Retrieves the accelerator path set on the menu. the accelerator path set on the menu. a valid #GtkMenu Returns the selected menu item from the menu. This is used by the #GtkComboBox. the #GtkMenuItem that was last selected in the menu. If a selection has not yet been made, the first menu item is selected. a #GtkMenu Returns the #GtkWidget that the menu is attached to. the #GtkWidget that the menu is attached to a #GtkMenu Retrieves the number of the monitor on which to show the menu. the number of the monitor on which the menu should be popped up or -1, if no monitor has been set a #GtkMenu Returns whether the menu reserves space for toggles and icons, regardless of their actual presence. Whether the menu reserves toggle space a #GtkMenu Returns whether the menu is torn off. See gtk_menu_set_tearoff_state(). %TRUE if the menu is currently torn off. a #GtkMenu Returns the title of the menu. See gtk_menu_set_title(). the title of the menu, or %NULL if the menu has no title set on it. This string is owned by GTK+ and should not be modified or freed. a #GtkMenu Places @menu on the given monitor. a #GtkMenu the monitor to place the menu on Removes the menu from the screen. a #GtkMenu Displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply %NULL 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. Please use gtk_menu_popup_at_widget(), gtk_menu_popup_at_pointer(). or gtk_menu_popup_at_rect() instead a #GtkMenu the menu shell containing the triggering menu item, or %NULL the menu item whose activation triggered the popup, or %NULL a user supplied function used to position the menu, or %NULL user supplied data to be passed to @func. the mouse button which was pressed to initiate the event. the time at which the activation event occurred. Displays @menu 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. @menu will be positioned at the pointer associated with @trigger_event. Properties that influence the behaviour of this function are #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, and #GtkMenu:menu-type-hint. Connect to the #GtkMenu::popped-up signal to find out how it was actually positioned. the #GtkMenu to pop up the #GdkEvent that initiated this request or %NULL if it's the current event Displays @menu 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. @menu 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 @menu to pin together. @menu can optionally be offset by #GtkMenu:rect-anchor-dx and #GtkMenu: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 #GtkMenu:anchor-hints and #GtkMenu:menu-type-hint. Connect to the #GtkMenu::popped-up signal to find out how it was actually positioned. the #GtkMenu to pop up the #GdkWindow @rect is relative to the #GdkRectangle to align @menu with the point on @rect to align with @menu's anchor point the point on @menu to align with @rect's anchor point the #GdkEvent that initiated this request or %NULL if it's the current event Displays @menu 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.  @menu will be positioned at @widget, aligning their anchor points. @widget_anchor and @menu_anchor determine anchor points on @widget and @menu to pin together. @menu can optionally be offset by #GtkMenu:rect-anchor-dx and #GtkMenu: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 #GtkMenu:anchor-hints and #GtkMenu:menu-type-hint. Connect to the #GtkMenu::popped-up signal to find out how it was actually positioned. the #GtkMenu to pop up the #GtkWidget to align @menu with the point on @widget to align with @menu's anchor point the point on @menu to align with @widget's anchor point the #GdkEvent that initiated this request or %NULL if it's the current event Displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply %NULL 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. Please use gtk_menu_popup_at_widget(), gtk_menu_popup_at_pointer(). or gtk_menu_popup_at_rect() instead a #GtkMenu a #GdkDevice the menu shell containing the triggering menu item, or %NULL the menu item whose activation triggered the popup, or %NULL a user supplied function used to position the menu, or %NULL user supplied data to be passed to @func destroy notify for @data the mouse button which was pressed to initiate the event the time at which the activation event occurred Moves @child to a new @position in the list of @menu children. a #GtkMenu the #GtkMenuItem to move the new position to place @child. Positions are numbered from 0 to n - 1 Repositions the menu according to its position function. a #GtkMenu Set the #GtkAccelGroup 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 gtk_window_add_accel_group(), in order for those windows to support all the accelerators contained in this group. a #GtkMenu the #GtkAccelGroup to be associated with the menu. 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 gtk_menu_item_set_accel_path() on each menu item that should support runtime user changable accelerators. Instead, by just calling gtk_menu_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 gtk_accel_map_add_entry(). Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). a valid #GtkMenu a valid accelerator path, or %NULL to unset the path Selects the specified menu item within the menu. This is used by the #GtkComboBox and should not be used by anyone else. a #GtkMenu the index of the menu item to select. Index values are from 0 to n-1 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. a #GtkMenu the number of the monitor on which the menu should be popped up Sets whether the menu should reserve space for drawing toggles or icons, regardless of their actual presence. a #GtkMenu whether to reserve size for toggles Sets the #GdkScreen on which the menu will be displayed. a #GtkMenu a #GdkScreen, or %NULL if the screen should be determined by the widget the menu is attached to Changes the tearoff state of the menu. A menu is normally displayed as drop down menu which persists as long as the menu is active. It can also be displayed as a tearoff menu which persists until it is closed or reattached. a #GtkMenu If %TRUE, menu is displayed as a tearoff menu. Sets the title string for the menu. The title is displayed when the menu is shown as a tearoff menu. If @title is %NULL, the menu will see if it is attached to a parent menu item, and if so it will try to use the same text as that menu item’s label. a #GtkMenu a string containing the title for the menu, or %NULL to inherit the title of the parent menu item, if any The accel group holding accelerators for the menu. An accel path used to conveniently construct accel paths of child items. The index of the currently selected menu item, or -1 if no menu item is selected. 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.  For example, %GDK_ANCHOR_FLIP_Y will replace %GDK_GRAVITY_NORTH_WEST with %GDK_GRAVITY_SOUTH_WEST 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 (), #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, #GtkMenu:menu-type-hint, and #GtkMenu::popped-up. The widget the menu is attached to. Setting this property attaches the menu without a #GtkMenuDetachFunc. If you need to use a detacher, use gtk_menu_attach_to_widget() directly. The #GdkWindowTypeHint to use for the menu's #GdkWindow. See gtk_menu_popup_at_rect (), gtk_menu_popup_at_widget (), gtk_menu_popup_at_pointer (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, and #GtkMenu::popped-up. The monitor the menu will be popped up on. 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 (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dy, #GtkMenu:menu-type-hint, and #GtkMenu::popped-up. 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 (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:menu-type-hint, and #GtkMenu::popped-up. 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. A boolean that indicates whether the menu is torn-off. A title that may be displayed by the window manager when this menu is torn-off. a #GtkScrollType 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.  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 (), #GtkMenu:anchor-hints, #GtkMenu:rect-anchor-dx, #GtkMenu:rect-anchor-dy, and #GtkMenu:menu-type-hint. the position of @menu after any possible flipping or %NULL if the backend can't obtain it the final position of @menu or %NULL if the backend can't obtain it %TRUE if the anchors were flipped horizontally %TRUE if the anchors were flipped vertically The #GtkMenuBar is a subclass of #GtkMenuShell which contains one or more #GtkMenuItems. The result is a standard menu bar which can hold many menu items. # CSS nodes GtkMenuBar has a single CSS node with name menubar. Creates a new #GtkMenuBar the new menu bar, as a #GtkWidget Creates a new #GtkMenuBar and populates it with menu items and submenus according to @model. The created menu items are connected to actions found in the #GtkApplicationWindow to which the menu bar belongs - typically by means of being contained within the #GtkApplicationWindows widget hierarchy. a new #GtkMenuBar a #GMenuModel Retrieves the current child pack direction of the menubar. See gtk_menu_bar_set_child_pack_direction(). the child pack direction a #GtkMenuBar Retrieves the current pack direction of the menubar. See gtk_menu_bar_set_pack_direction(). the pack direction a #GtkMenuBar Sets how widgets should be packed inside the children of a menubar. a #GtkMenuBar a new #GtkPackDirection Sets how items should be packed inside a menubar. a #GtkMenuBar a new #GtkPackDirection The child pack direction of the menubar. It determines how the widgets contained in child menuitems are arranged. The pack direction of the menubar. It determines how menuitems are arranged in the menubar. The #GtkMenuButton widget is used to display a popup when clicked on. This popup can be provided either as a #GtkMenu, a #GtkPopover or an abstract #GMenuModel. The #GtkMenuButton widget can hold any valid child widget. That is, it can hold almost any other standard #GtkWidget. The most commonly used child is #GtkImage. If no widget is explicitely added to the #GtkMenuButton, a #GtkImage is automatically created, using an arrow image oriented according to #GtkMenuButton:direction or the generic “open-menu-symbolic” icon if the direction is not set. The positioning of the popup is determined by the #GtkMenuButton:direction property of the menu button. For menus, the #GtkWidget:halign and #GtkWidget:valign properties of the menu are also taken into account. For example, when the direction is %GTK_ARROW_DOWN and the horizontal alignment is %GTK_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  - halign = center  - halign = end  ## Direction = Up - halign = start  - halign = center  - halign = end  ## Direction = Left - valign = start  - valign = center  - valign = end  ## Direction = Right - valign = start  - valign = center  - valign = end  # CSS nodes GtkMenuButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .popup style class. Creates a new #GtkMenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another #GtkWidget should you wish to. The newly created #GtkMenuButton widget Returns the parent #GtkWidget to use to line up with menu. a #GtkWidget value or %NULL a #GtkMenuButton Returns the direction the popup will be pointing at when popped up. a #GtkArrowType value a #GtkMenuButton Returns the #GMenuModel used to generate the popup. a #GMenuModel or %NULL a #GtkMenuButton Returns the #GtkPopover that pops out of the button. If the button is not using a #GtkPopover, this function returns %NULL. a #GtkPopover or %NULL a #GtkMenuButton Returns the #GtkMenu that pops out of the button. If the button does not use a #GtkMenu, this function returns %NULL. a #GtkMenu or %NULL a #GtkMenuButton Returns whether a #GtkPopover or a #GtkMenu will be constructed from the menu model. %TRUE if using a #GtkPopover a #GtkMenuButton Sets the #GtkWidget to use to line the menu with when popped up. Note that the @align_widget must contain the #GtkMenuButton itself. Setting it to %NULL 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. a #GtkMenuButton a #GtkWidget 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 %GTK_ARROW_NONE for a @direction, the popup will behave as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). a #GtkMenuButton a #GtkArrowType Sets the #GMenuModel from which the popup will be constructed, or %NULL to dissociate any existing menu model and disable the button. Depending on the value of #GtkMenuButton:use-popover, either a #GtkMenu will be created with gtk_menu_new_from_model(), or a #GtkPopover with gtk_popover_new_from_model(). In either case, actions will be connected as documented for these functions. If #GtkMenuButton:popup or #GtkMenuButton:popover are already set, those widgets are dissociated from the @menu_button, and those properties are set to %NULL. a #GtkMenuButton a #GMenuModel, or %NULL to unset and disable the button Sets the #GtkPopover that will be popped up when the @menu_button is clicked, or %NULL to dissociate any existing popover and disable the button. If #GtkMenuButton:menu-model or #GtkMenuButton:popup are set, those objects are dissociated from the @menu_button, and those properties are set to %NULL. a #GtkMenuButton a #GtkPopover, or %NULL to unset and disable the button Sets the #GtkMenu that will be popped up when the @menu_button is clicked, or %NULL to dissociate any existing menu and disable the button. If #GtkMenuButton:menu-model or #GtkMenuButton:popover are set, those objects are dissociated from the @menu_button, and those properties are set to %NULL. a #GtkMenuButton a #GtkMenu, or %NULL to unset and disable the button Sets whether to construct a #GtkPopover instead of #GtkMenu when gtk_menu_button_set_menu_model() is called. Note that this property is only consulted when a new menu model is set. a #GtkMenuButton %TRUE to construct a popover from the menu model The #GtkWidget to use to align the menu with. The #GtkArrowType representing the direction in which the menu or popover will be popped out. The #GMenuModel from which the popup will be created. Depending on the #GtkMenuButton:use-popover property, that may be a menu or a popover. See gtk_menu_button_set_menu_model() for the interaction with the #GtkMenuButton:popup property. The #GtkPopover that will be popped up when the button is clicked. The #GtkMenu that will be popped up when the button is clicked. Whether to construct a #GtkPopover from the menu model, or a #GtkMenu. A user function supplied when calling gtk_menu_attach_to_widget() which will be called when the menu is later detached from the widget. the #GtkWidget that the menu is being detached from. the #GtkMenu being detached. An enumeration representing directional movements within a menu. To the parent menu shell To the submenu, if any, associated with the item To the next menu item To the previous menu item The #GtkMenuItem 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 GtkMenuItem derives from #GtkBin it can hold any valid child widget, although only a few are really useful. By default, a GtkMenuItem sets a #GtkAccelLabel as its child. GtkMenuItem has direct functions to set the label and its mnemonic. For more advanced label settings, you can fetch the child widget from the GtkBin. An example for setting markup and accelerator on a MenuItem: |[<!-- language="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); ]| # GtkMenuItem as GtkBuildable The GtkMenuItem implementation of the #GtkBuildable interface supports adding a submenu by specifying “submenu” as the “type” attribute of a <child> element. An example of UI definition fragment with submenus: |[ <object class="GtkMenuItem"> <child type="submenu"> <object class="GtkMenu"/> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> menuitem ├── <child> ╰── [arrow.right] ]| GtkMenuItem 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. Creates a new #GtkMenuItem. the newly created #GtkMenuItem Creates a new #GtkMenuItem whose child is a #GtkLabel. the newly created #GtkMenuItem the text for the label Creates a new #GtkMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. a new #GtkMenuItem The text of the button, with an underscore in front of the mnemonic character Emits the #GtkMenuItem::activate signal on the given item the menu item Emits the #GtkMenuItem::deselect signal on the given item. the menu item Sets @text on the @menu_item label The text in the @menu_item label. This is the internal string used by the label, and must not be modified. a #GtkMenuItem Emits the #GtkMenuItem::select signal on the given item. the menu item Sets @text on the @menu_item label a #GtkMenuItem the text you want to set Emits the #GtkMenuItem::toggle-size-allocate signal on the given item. the menu item. the allocation to use as signal data. Emits the #GtkMenuItem::toggle-size-request signal on the given item. the menu item the requisition to use as signal data. Emits the #GtkMenuItem::activate signal on the given item the menu item Emits the #GtkMenuItem::deselect signal on the given item. the menu item Retrieve the accelerator path that was previously set on @menu_item. See gtk_menu_item_set_accel_path() for details. the accelerator path corresponding to this menu item’s functionality, or %NULL if not set a valid #GtkMenuItem Sets @text on the @menu_item label The text in the @menu_item label. This is the internal string used by the label, and must not be modified. a #GtkMenuItem Returns whether the @menu_item reserves space for the submenu indicator, regardless if it has a submenu or not. %TRUE if @menu_item always reserves space for the submenu indicator a #GtkMenuItem Gets whether the menu item appears justified at the right side of the menu bar. See gtk_menu_item_set_right_justified() %TRUE if the menu item will appear at the far right if added to a menu bar. a #GtkMenuItem Gets the submenu underneath this menu item, if any. See gtk_menu_item_set_submenu(). submenu for this menu item, or %NULL if none a #GtkMenuItem Checks if an underline in the text indicates the next character should be used for the mnemonic accelerator key. %TRUE if an embedded underline in the label indicates the mnemonic accelerator key. a #GtkMenuItem Emits the #GtkMenuItem::select signal on the given item. the menu item Set the accelerator path on @menu_item, through which runtime changes of the menu item’s accelerator caused by the user can be identified and saved to persistent storage (see gtk_accel_map_save() on this). To set up a default accelerator for this menu item, call gtk_accel_map_add_entry() with the same @accel_path. See also gtk_accel_map_add_entry() on the specifics of accelerator paths, and gtk_menu_set_accel_path() for a more convenient variant of this function. This function is basically a convenience wrapper that handles calling gtk_widget_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 gtk_menu_set_accel_group() for this to work. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). a valid #GtkMenuItem accelerator path, corresponding to this menu item’s functionality, or %NULL to unset the current path. Sets @text on the @menu_item label a #GtkMenuItem the text you want to set Sets whether the @menu_item 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. a #GtkMenuItem the new value Sets whether the menu item appears justified at the right side of a menu bar. This was traditionally done for “Help” menu items, but is now considered a bad idea. (If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the left.) If you insist on using it, use gtk_widget_set_hexpand() and gtk_widget_set_halign(). a #GtkMenuItem. if %TRUE the menu item will appear at the far right if added to a menu bar Sets or replaces the menu item’s submenu, or removes it when a %NULL submenu is passed. a #GtkMenuItem the submenu, or %NULL If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key. a #GtkMenuItem %TRUE if underlines in the text indicate mnemonics Emits the #GtkMenuItem::toggle-size-allocate signal on the given item. the menu item. the allocation to use as signal data. Emits the #GtkMenuItem::toggle-size-request signal on the given item. the menu item the requisition to use as signal data. 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. The text for the child label. Sets whether the menu item appears justified at the right side of a menu bar. The submenu attached to the menu item, or %NULL if it has none. %TRUE if underlines in the text indicate mnemonics. Emitted when the item is activated. Emitted when the item is activated, but also if the menu item has a submenu. For normal applications, the relevant signal is #GtkMenuItem::activate. The parent class. If %TRUE, then we should always hide the menu when the %GtkMenuItem is activated. Otherwise, it is up to the caller. the menu item the menu item the requisition to use as signal data. the menu item. the allocation to use as signal data. a #GtkMenuItem the text you want to set The text in the @menu_item label. This is the internal string used by the label, and must not be modified. a #GtkMenuItem the menu item the menu item A user function supplied when calling gtk_menu_popup() which controls the positioning of the menu when it is displayed. The function sets the @x and @y parameters to the coordinates where the menu is to be drawn. To make the menu appear on a different monitor than the mouse pointer, gtk_menu_set_monitor() must be called. a #GtkMenu. address of the #gint representing the horizontal position where the menu shall be drawn. address of the #gint representing the vertical position where the menu shall be drawn. This is an output parameter. This parameter controls how menus placed outside the monitor are handled. If this is set to %TRUE and part of the menu is outside the monitor then GTK+ pushes the window into the visible area, effectively modifying the popup position. Note that moving and possibly resizing the menu around will alter the scroll position to keep the menu items “in place”, i.e. at the same monitor position they would have been without resizing. In practice, this behavior is only useful for combobox popups or option menus and cannot be used to simply confine a menu to monitor boundaries. In that case, changing the scroll offset is not desirable. the data supplied by the user in the gtk_menu_popup() @data parameter. A #GtkMenuShell is the abstract base class used to derive the #GtkMenu and #GtkMenuBar subclasses. A #GtkMenuShell is a container of #GtkMenuItem objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A #GtkMenuItem 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. Cancels the selection within the menu shell. a #GtkMenuShell Deactivates the menu shell. Typically this results in the menu shell being erased from the screen. a #GtkMenuShell Adds a new #GtkMenuItem to the menu shell’s item list at the position indicated by @position. a #GtkMenuShell The #GtkMenuItem to add The position in the item list where @child is added. Positions are numbered from 0 to n-1 Selects the menu item from the menu shell. a #GtkMenuShell The #GtkMenuItem to select Activates the menu item within the menu shell. a #GtkMenuShell the #GtkMenuItem to activate if %TRUE, force the deactivation of the menu shell after the menu item is activated Adds a new #GtkMenuItem to the end of the menu shell's item list. a #GtkMenuShell The #GtkMenuItem to add Establishes a binding between a #GtkMenuShell and a #GMenuModel. 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 %NULL 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-%NULL 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 #GtkActionable 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 #GtkMenuShell outside of a #GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using gtk_widget_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 #GMenuModel. For most cases you are probably better off using gtk_menu_new_from_model() or gtk_menu_bar_new_from_model() or just directly passing the #GMenuModel to gtk_application_set_app_menu() or gtk_application_set_menubar(). a #GtkMenuShell the #GMenuModel to bind to or %NULL to remove binding the namespace for actions in @model %TRUE if toplevel items in @shell should have separators between them Cancels the selection within the menu shell. a #GtkMenuShell Deactivates the menu shell. Typically this results in the menu shell being erased from the screen. a #GtkMenuShell Deselects the currently selected item from the menu shell, if any. a #GtkMenuShell Gets the parent menu shell. The parent menu shell of a submenu is the #GtkMenu or #GtkMenuBar from which it was opened up. the parent #GtkMenuShell a #GtkMenuShell Gets the currently selected item. the currently selected item a #GtkMenuShell Returns %TRUE if the menu shell will take the keyboard focus on popup. %TRUE if the menu shell will take the keyboard focus on popup. a #GtkMenuShell Adds a new #GtkMenuItem to the menu shell’s item list at the position indicated by @position. a #GtkMenuShell The #GtkMenuItem to add The position in the item list where @child is added. Positions are numbered from 0 to n-1 Adds a new #GtkMenuItem to the beginning of the menu shell's item list. a #GtkMenuShell The #GtkMenuItem to add Select the first visible or selectable child of the menu shell; don’t select tearoff items unless the only item is a tearoff item. a #GtkMenuShell 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. Selects the menu item from the menu shell. a #GtkMenuShell The #GtkMenuItem to select 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() a #GtkMenuShell %TRUE if the menu shell should take the keyboard focus on popup A boolean that determines whether the menu and its submenus grab the keyboard focus. See gtk_menu_shell_set_take_focus() and gtk_menu_shell_get_take_focus(). An action signal that activates the current menu item within the menu shell. if %TRUE, hide the menu after activating the menu item An action signal which cancels the selection within the menu shell. Causes the #GtkMenuShell::selection-done signal to be emitted. A keybinding signal which moves the focus in the given @direction. the direction to cycle in This signal is emitted when a menu shell is deactivated. The ::insert signal is emitted when a new #GtkMenuItem is added to a #GtkMenuShell. A separate signal is used instead of GtkContainer::add because of the need for an additional position parameter. The inverse of this signal is the GtkContainer::removed signal. the #GtkMenuItem that is being inserted the position at which the insert occurs An keybinding signal which moves the current menu item in the direction specified by @direction. the direction to move The ::move-selected signal is emitted to move the selection to another item. %TRUE to stop the signal emission, %FALSE to continue +1 to move to the next item, -1 to move to the previous This signal is emitted when a selection has been completed within a menu shell. a #GtkMenuShell a #GtkMenuShell a #GtkMenuShell The #GtkMenuItem to select a #GtkMenuShell The #GtkMenuItem to add The position in the item list where @child is added. Positions are numbered from 0 to n-1 A #GtkMenuToolButton is a #GtkToolItem that contains a button and a small additional button with an arrow. When clicked, the arrow button pops up a dropdown menu. Use gtk_menu_tool_button_new() to create a new #GtkMenuToolButton. # GtkMenuToolButton as GtkBuildable The GtkMenuToolButton implementation of the GtkBuildable 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: |[ <object class="GtkMenuToolButton"> <child type="menu"> <object class="GtkMenu"/> </child> </object> ]| Creates a new #GtkMenuToolButton using @icon_widget as icon and @label as label. the new #GtkMenuToolButton a widget that will be used as icon widget, or %NULL a string that will be used as label, or %NULL Creates a new #GtkMenuToolButton. The new #GtkMenuToolButton will contain an icon and label from the stock item indicated by @stock_id. Use gtk_menu_tool_button_new() instead. the new #GtkMenuToolButton the name of a stock item Gets the #GtkMenu associated with #GtkMenuToolButton. the #GtkMenu associated with #GtkMenuToolButton a #GtkMenuToolButton Sets the tooltip markup text to be used as tooltip for the arrow button which pops up the menu. See gtk_tool_item_set_tooltip_text() for setting a tooltip on the whole #GtkMenuToolButton. a #GtkMenuToolButton markup text to be used as tooltip text for button’s arrow button Sets the tooltip text to be used as tooltip for the arrow button which pops up the menu. See gtk_tool_item_set_tooltip_text() for setting a tooltip on the whole #GtkMenuToolButton. a #GtkMenuToolButton text to be used as tooltip text for button’s arrow button Sets the #GtkMenu that is popped up when the user clicks on the arrow. If @menu is NULL, the arrow button becomes insensitive. a #GtkMenuToolButton the #GtkMenu associated with #GtkMenuToolButton The ::show-menu signal is emitted before the menu is shown. It can be used to populate the menu on demand, using gtk_menu_tool_button_set_menu(). Note that even if you populate the menu dynamically in this way, you must set an empty menu on the #GtkMenuToolButton beforehand, since the arrow is made insensitive if the menu is not set. The parent class. #GtkMessageDialog presents a dialog with some message text. It’s simply a convenience widget; you could construct the equivalent of #GtkMessageDialog from #GtkDialog without too much effort, but #GtkMessageDialog saves typing. One difference from #GtkDialog is that #GtkMessageDialog sets the #GtkWindow: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 gtk_dialog_run(), though you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically makes the dialog modal and waits for the user to respond to it. gtk_dialog_run() returns when any dialog button is clicked. An example for using a modal dialog: |[<!-- language="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 #GtkMessageDialog as follows: An example for a non-modal dialog: |[<!-- language="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); ]| # GtkMessageDialog as GtkBuildable The GtkMessageDialog implementation of the GtkBuildable interface exposes the message area as an internal child with the name “message_area”. 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 #GtkResponseType. See #GtkDialog for more details. a new #GtkMessageDialog transient parent, or %NULL for none flags type of message set of buttons to use printf()-style format string, or %NULL arguments for @message_format 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 #GtkResponseType. See #GtkDialog 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 gtk_message_dialog_set_markup() instead, since you can’t pass the markup string either as the format (it might contain “%” characters) or as a string argument. |[<!-- language="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); ]| a new #GtkMessageDialog transient parent, or %NULL for none flags type of message set of buttons to use printf()-style format string, or %NULL arguments for @message_format 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 gtk_message_dialog_new_with_markup() does. Thus, if the arguments may contain special XML characters, you should use g_markup_printf_escaped() to escape it. |[<!-- language="C" --> gchar *msg; msg = g_markup_printf_escaped (message_format, ...); gtk_message_dialog_format_secondary_markup (message_dialog, "%s", msg); g_free (msg); ]| a #GtkMessageDialog printf()-style markup string (see [Pango markup format][PangoMarkupFormat]), or %NULL arguments for @message_format Sets the secondary text of the message dialog to be @message_format (with printf()-style). a #GtkMessageDialog printf()-style format string, or %NULL arguments for @message_format Gets the dialog’s image. Use #GtkDialog for dialogs with images the dialog’s image a #GtkMessageDialog 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 gtk_dialog_get_content_area() for the corresponding function in the parent #GtkDialog. A #GtkBox corresponding to the “message area” in the @message_dialog. a #GtkMessageDialog Sets the dialog’s image to @image. Use #GtkDialog to create dialogs with images a #GtkMessageDialog the image Sets the text of the message dialog to be @str, which is marked up with the [Pango text markup language][PangoMarkupFormat]. a #GtkMessageDialog markup string (see [Pango markup format][PangoMarkupFormat]) The image for this dialog. Use #GtkDialog to create dialogs with images The #GtkBox that corresponds to the message area of this dialog. See gtk_message_dialog_get_message_area() for a detailed description of this area. The type of the message. The secondary text of the message dialog. %TRUE if the secondary text of the dialog includes Pango markup. See pango_parse_markup(). The primary text of the message dialog. If the dialog has a secondary text, this will appear as the title. %TRUE if the primary text of the dialog includes Pango markup. See pango_parse_markup(). The type of message being displayed in the dialog. Informational message Non-fatal warning message Question requiring a choice Fatal error message None of the above The #GtkMisc 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 #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the child widget, so GtkMisc should not be used in new code. To reflect this fact, all #GtkMisc API has been deprecated. Gets the X and Y alignment of the widget within its allocation. See gtk_misc_set_alignment(). Use #GtkWidget alignment and margin properties. a #GtkMisc location to store X alignment of @misc, or %NULL location to store Y alignment of @misc, or %NULL Gets the padding in the X and Y directions of the widget. See gtk_misc_set_padding(). Use #GtkWidget alignment and margin properties. a #GtkMisc location to store padding in the X direction, or %NULL location to store padding in the Y direction, or %NULL Sets the alignment of the widget. Use #GtkWidget's alignment (#GtkWidget:halign and #GtkWidget:valign) and margin properties or #GtkLabel's #GtkLabel:xalign and #GtkLabel:yalign properties. a #GtkMisc. the horizontal alignment, from 0 (left) to 1 (right). the vertical alignment, from 0 (top) to 1 (bottom). Sets the amount of space to add around the widget. Use #GtkWidget alignment and margin properties. a #GtkMisc. the amount of space to add on the left and right of the widget, in pixels. the amount of space to add on the top and bottom of the widget, in pixels. The horizontal alignment. A value of 0.0 means left alignment (or right on RTL locales); a value of 1.0 means right alignment (or left on RTL locales). Use gtk_widget_set_halign() instead. If you are using #GtkLabel, use #GtkLabel:xalign instead. The amount of space to add on the left and right of the widget, in pixels. Use gtk_widget_set_margin_start() and gtk_widget_set_margin_end() instead The vertical alignment. A value of 0.0 means top alignment; a value of 1.0 means bottom alignment. Use gtk_widget_set_valign() instead. If you are using #GtkLabel, use #GtkLabel:yalign instead. The amount of space to add on the top and bottom of the widget, in pixels. Use gtk_widget_set_margin_top() and gtk_widget_set_margin_bottom() instead GtkModelButton is a button class that can use a #GAction as its model. In contrast to #GtkToggleButton or #GtkRadioButton, which can also be backed by a #GAction via the #GtkActionable:action-name property, GtkModelButton 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 gtk_popover_new_from_model(); they can also be used manually in a #GtkPopoverMenu. When the action is specified via the #GtkActionable:action-name and #GtkActionable: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 #GtkModelButton:role property. The content of the button is specified by the #GtkModelButton:text and #GtkModelButton:icon properties. The appearance of model buttons can be influenced with the #GtkModelButton:centered and #GtkModelButton:iconic properties. Model buttons have built-in support for submenus in #GtkPopoverMenu. To make a GtkModelButton that opens a submenu when activated, set the #GtkModelButton:menu-name property. To make a button that goes back to the parent menu, you should set the #GtkModelButton:inverted property to place the submenu indicator at the opposite side. # Example |[ <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">view.cut</property> <property name="text" translatable="yes">Cut</property> </object> </child> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">view.copy</property> <property name="text" translatable="yes">Copy</property> </object> </child> <child> <object class="GtkModelButton"> <property name="visible">True</property> <property name="action-name">view.paste</property> <property name="text" translatable="yes">Paste</property> </object> </child> </object> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> modelbutton ├── <child> ╰── check ]| |[<!-- language="plain" --> modelbutton ├── <child> ╰── radio ]| |[<!-- language="plain" --> modelbutton ├── <child> ╰── arrow ]| GtkModelButton 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. |[<!-- language="plain" --> button.model ├── <child> ╰── check ]| Iconic model buttons (see #GtkModelButton: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. Creates a new GtkModelButton. the newly created #GtkModelButton widget The state of the button. This is reflecting the state of the associated #GAction. Whether to render the button contents centered instead of left-aligned. This property should be set for title-like items. A #GIcon that will be used if iconic appearance for the button is desired. 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. 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. 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. Specifies whether the button is a plain, check or radio button. When #GtkActionable:action-name is set, the role will be determined from the action and does not have to be set explicitly. The label for the button. 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. A multihead-aware GTK+ module may have a gtk_module_display_init() function with this prototype. GTK+ calls this function for each opened display. an open #GdkDisplay Each GTK+ module must have a function gtk_module_init() with this prototype. This function is called after loading the module. GTK+ always passes %NULL for this argument GTK+ always passes %NULL for this argument This should not be accessed directly. Use the accessor functions below. Creates a new #GtkMountOperation a new #GtkMountOperation transient parent of the window, or %NULL Gets the transient parent used by the #GtkMountOperation the transient parent for windows shown by @op a #GtkMountOperation Gets the screen on which windows of the #GtkMountOperation will be shown. the screen on which windows of @op are shown a #GtkMountOperation Returns whether the #GtkMountOperation is currently displaying a window. %TRUE if @op is currently displaying a window a #GtkMountOperation Sets the transient parent for windows shown by the #GtkMountOperation. a #GtkMountOperation transient parent of the window, or %NULL Sets the screen to show windows of the #GtkMountOperation on. a #GtkMountOperation a #GdkScreen The parent class. Move forward or back by graphemes Move left or right by graphemes Move forward or back by words Move up or down lines (wrapped lines) Move to either end of a line Move up or down paragraphs (newline-ended lines) Move to either end of a paragraph Move by pages Move to ends of the buffer Move horizontally by pages Native dialogs are platform dialogs that don't use #GtkDialog or #GtkWindow. 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 #GtkDialog functions cannot be used on such objects, but we need a similar API in order to drive them. The #GtkNativeDialog 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 #GtkNativeDialog::response signal when the user finished with the dialog. There is also a gtk_native_dialog_run() helper that makes it easy to run any native dialog in a modal way with a recursive mainloop, similar to gtk_dialog_run(). Hides the dialog if it is visilbe, aborting any interaction. Once this is called the #GtkNativeDialog::response signal will not be emitted until after the next call to gtk_native_dialog_show(). If the dialog is not visible this does nothing. a #GtkNativeDialog 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 #GtkNativeDialog::response signal will be emitted. Multiple calls while the dialog is visible will be ignored. a #GtkNativeDialog 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 GtkWindow) because there is no reference from the windowing system to the #GtkNativeDialog. a #GtkNativeDialog Returns whether the dialog is modal. See gtk_native_dialog_set_modal(). %TRUE if the dialog is set to be modal a #GtkNativeDialog Gets the title of the #GtkNativeDialog. the title of the dialog, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkNativeDialog Fetches the transient parent for this window. See gtk_native_dialog_set_transient_for(). the transient parent for this window, or %NULL if no transient parent has been set. a #GtkNativeDialog Determines whether the dialog is visible. %TRUE if the dialog is visible a #GtkNativeDialog Hides the dialog if it is visilbe, aborting any interaction. Once this is called the #GtkNativeDialog::response signal will not be emitted until after the next call to gtk_native_dialog_show(). If the dialog is not visible this does nothing. a #GtkNativeDialog Blocks in a recursive main loop until @self emits the #GtkNativeDialog::response signal. It then returns the response ID from the ::response signal emission. Before entering the recursive main loop, gtk_native_dialog_run() calls gtk_native_dialog_show() on the dialog for you. After gtk_native_dialog_run() returns, then dialog will be hidden. Typical usage of this function might be: |[<!-- language="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. response ID a #GtkNativeDialog 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 gtk_native_dialog_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. a #GtkNativeDialog whether the window is modal Sets the title of the #GtkNativeDialog. a #GtkNativeDialog title of the dialog 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 %NULL for @parent unsets the current transient window. a #GtkNativeDialog parent window, or %NULL 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 #GtkNativeDialog::response signal will be emitted. Multiple calls while the dialog is visible will be ignored. a #GtkNativeDialog Whether the window should be modal with respect to its transient parent. The title of the dialog window The transient parent of the dialog, or %NULL for none. Whether the window is currenlty visible. Emitted when the user responds to the dialog. When this is called the dialog has been hidden. If you call gtk_native_dialog_hide() before the user responds to the dialog this signal will not be emitted. the response ID a #GtkNativeDialog a #GtkNativeDialog The #GtkNotebook widget is a #GtkContainer whose children are pages that can be switched between using tab labels along one edge. There are many configuration options for GtkNotebook. Among other things, you can choose on which edge the tabs appear (see gtk_notebook_set_tab_pos()), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see gtk_notebook_set_scrollable()), and whether there will be a popup menu allowing the users to switch pages. (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable()) # GtkNotebook as GtkBuildable The GtkNotebook implementation of the #GtkBuildable 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 GtkNotebook: |[ <object class="GtkNotebook"> <child> <object class="GtkLabel" id="notebook-content"> <property name="label">Content</property> </object> </child> <child type="tab"> <object class="GtkLabel" id="notebook-tab"> <property name="label">Tab</property> </object> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> notebook ├── header.top │ ├── [<action widget>] │ ├── tabs │ │ ├── [arrow] │ │ ├── tab │ │ │ ╰── <tab label> ┊ ┊ ┊ │ │ ├── tab[.reorderable-page] │ │ │ ╰── <tab label> │ │ ╰── [arrow] │ ╰── [<action widget>] │ ╰── stack ├── <child> ┊ ╰── <child> ]| GtkNotebook 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 gtk_notebook_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. Creates a new #GtkNotebook widget with no pages. the newly created #GtkNotebook Appends a page to @notebook. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” Appends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a #GtkLabel or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a #GtkLabel, @menu_label must be specified if the page-switch menu is to be used. Removes the child from the notebook. This function is very similar to gtk_container_remove(), but additionally informs the notebook that the removal is happening as part of a tab DND operation, which should not be cancelled. a #GtkNotebook a child Gets one of the action widgets. See gtk_notebook_set_action_widget(). The action widget with the given @pack_type or %NULL when this action widget has not been set a #GtkNotebook pack type of the action widget to receive Returns the page number of the current page. the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned. a #GtkNotebook Gets the current group name for @notebook. the group name, or %NULL if none is set a #GtkNotebook Retrieves the menu label widget of the page containing @child. the menu label, or %NULL if the notebook page does not have a menu label other than the default (the tab label). a #GtkNotebook a widget contained in a page of @notebook Retrieves the text of the menu label for the page containing @child. the text of the tab label, or %NULL if the widget does not have a menu label other than the default menu label, or the menu label widget is not a #GtkLabel. The string is owned by the widget and must not be freed. a #GtkNotebook the child widget of a page of the notebook. Gets the number of pages in a notebook. the number of pages in the notebook a #GtkNotebook Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num is out of bounds a #GtkNotebook the index of a page in the notebook, or -1 to get the last page Returns whether the tab label area has arrows for scrolling. See gtk_notebook_set_scrollable(). %TRUE if arrows for scrolling are present a #GtkNotebook Returns whether a bevel will be drawn around the notebook pages. See gtk_notebook_set_show_border(). %TRUE if the bevel is drawn a #GtkNotebook Returns whether the tabs of the notebook are shown. See gtk_notebook_set_show_tabs(). %TRUE if the tabs are shown a #GtkNotebook Returns whether the tab contents can be detached from @notebook. %TRUE if the tab is detachable. a #GtkNotebook a child #GtkWidget Returns the horizontal width of a tab border. this function returns zero horizontal width of a tab border a #GtkNotebook Returns the tab label widget for the page @child. %NULL is returned if @child is not in @notebook or if no tab label has specifically been set for @child. the tab label a #GtkNotebook the page Retrieves the text of the tab label for the page containing @child. the text of the tab label, or %NULL if the tab label widget is not a #GtkLabel. The string is owned by the widget and must not be freed. a #GtkNotebook a widget contained in a page of @notebook Gets the edge at which the tabs for switching pages in the notebook are drawn. the edge at which the tabs are drawn a #GtkNotebook Gets whether the tab can be reordered via drag and drop or not. %TRUE if the tab is reorderable. a #GtkNotebook a child #GtkWidget Returns the vertical width of a tab border. this function returns zero vertical width of a tab border a #GtkNotebook Insert a page into @notebook at the given position. the index (starting from 0) of the inserted page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages Insert a page into @notebook at the given position, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the inserted page in the notebook a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a #GtkLabel or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a #GtkLabel, @menu_label must be specified if the page-switch menu is to be used. the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages. Switches to the next page. Nothing happens if the current page is the last page. a #GtkNotebook Finds the index of the page which contains the given child widget. the index of the page containing @child, or -1 if @child is not in the notebook a #GtkNotebook a #GtkWidget Disables the popup menu. a #GtkNotebook 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. a #GtkNotebook Prepends a page to @notebook. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” Prepends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a #GtkNotebook the #GtkWidget to use as the contents of the page the #GtkWidget to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a #GtkLabel or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a #GtkLabel, @menu_label must be specified if the page-switch menu is to be used. Switches to the previous page. Nothing happens if the current page is the first page. a #GtkNotebook Removes a page from the notebook given its index in the notebook. a #GtkNotebook the index of a notebook page, starting from 0. If -1, the last page will be removed. 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. a #GtkNotebook the child to move the new position, or -1 to move to the end 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 #GtkBox 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 gtk_container_foreach(). a #GtkNotebook a #GtkWidget pack type of the action widget Switches to the page number @page_num. Note that due to historical reasons, GtkNotebook 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. a #GtkNotebook 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. Sets a group name for @notebook. Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a %NULL group name will not be able to exchange tabs with any other notebook. a #GtkNotebook the name of the notebook group, or %NULL to unset it Changes the menu label for the page containing @child. a #GtkNotebook the child widget the menu label, or %NULL for default Creates a new label and sets it as the menu label of @child. a #GtkNotebook the child widget the label text Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. a #GtkNotebook %TRUE if scroll arrows should be added Sets whether a bevel will be drawn around the notebook pages. This only has a visual effect when the tabs are not shown. See gtk_notebook_set_show_tabs(). a #GtkNotebook %TRUE if a bevel should be drawn around the notebook Sets whether to show the tabs for the notebook or not. a #GtkNotebook %TRUE if the tabs should be shown Sets whether the tab can be detached from @notebook to another notebook or widget. Note that 2 notebooks must share a common group identificator (see gtk_notebook_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 GtkWidget** pointing to the child widget that corresponds to the dropped tab. Note that you should use gtk_notebook_detach_tab() instead of gtk_container_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. |[<!-- language="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. a #GtkNotebook a child #GtkWidget whether the tab is detachable or not Changes the tab label for @child. If %NULL is specified for @tab_label, then the page will have the label “page N”. a #GtkNotebook the page the tab label widget to use, or %NULL for default tab label Creates a new label and sets it as the tab label for the page containing @child. a #GtkNotebook the page the label text Sets the edge at which the tabs for switching pages in the notebook are drawn. a #GtkNotebook. the edge to draw the tabs at Sets whether the notebook tab can be reordered via drag and drop or not. a #GtkNotebook a child #GtkWidget whether the tab is reorderable or not Group name for tab drag and drop. 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 #GtkNotebook:group-name ). a #GtkNotebook that @page should be added to, or %NULL. the tab of @notebook that is being detached the X coordinate where the drop happens the Y coordinate where the drop happens the ::page-added signal is emitted in the notebook right after a page is added to the notebook. the child #GtkWidget affected the new page number for @child the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook. the child #GtkWidget affected the @child page number the ::page-reordered signal is emitted in the notebook right after a page has been reordered. the child #GtkWidget affected the new page number for @child Emitted when the user or a function changes the current page. the new current page the index of the page Used to determine the layout of pages on a sheet when printing multiple pages per sheet.         GtkNumerableIcon is a subclass of #GEmblemedIcon that can show a number or short string as an emblem. The number can be overlayed on top of another emblem, if desired. It supports theming by taking font and color information from a provided #GtkStyleContext; see gtk_numerable_icon_set_style_context(). Typical numerable icons:   Creates a new unthemed #GtkNumerableIcon. a new #GIcon a #GIcon to overlay on Creates a new #GtkNumerableIcon which will themed according to the passed #GtkStyleContext. This is a convenience constructor that calls gtk_numerable_icon_set_style_context() internally. a new #GIcon a #GIcon to overlay on a #GtkStyleContext Returns the #GIcon that was set as the base background image, or %NULL if there’s none. The caller of this function does not own a reference to the returned #GIcon. a #GIcon, or %NULL a #GtkNumerableIcon Returns the icon name used as the base background image, or %NULL if there’s none. an icon name, or %NULL a #GtkNumerableIcon Returns the value currently displayed by @self. the currently displayed value a #GtkNumerableIcon Returns the currently displayed label of the icon, or %NULL. the currently displayed label a #GtkNumerableIcon Returns the #GtkStyleContext used by the icon for theming, or %NULL if there’s none. a #GtkStyleContext, or %NULL. This object is internal to GTK+ and should not be unreffed. Use g_object_ref() if you want to keep it around a #GtkNumerableIcon Updates the icon to use @icon as the base background image. If @icon is %NULL, @self will go back using style information or default theming for its background image. If this method is called and an icon name was already set as background for the icon, @icon will be used, i.e. the last method called between gtk_numerable_icon_set_background_gicon() and gtk_numerable_icon_set_background_icon_name() has always priority. a #GtkNumerableIcon a #GIcon, or %NULL Updates the icon to use the icon named @icon_name from the current icon theme as the base background image. If @icon_name is %NULL, @self will go back using style information or default theming for its background image. If this method is called and a #GIcon was already set as background for the icon, @icon_name will be used, i.e. the last method called between gtk_numerable_icon_set_background_icon_name() and gtk_numerable_icon_set_background_gicon() has always priority. a #GtkNumerableIcon an icon name, or %NULL Sets the currently displayed value of @self to @count. The numeric value is always clamped to make it two digits, i.e. between -99 and 99. Setting a count of zero removes the emblem. If this method is called, and a label was already set on the icon, it will automatically be reset to %NULL before rendering the number, i.e. the last method called between gtk_numerable_icon_set_count() and gtk_numerable_icon_set_label() has always priority. a #GtkNumerableIcon a number between -99 and 99 Sets the currently displayed value of @self to the string in @label. Setting an empty label removes the emblem. Note that this is meant for displaying short labels, such as roman numbers, or single letters. For roman numbers, consider using the Unicode characters U+2160 - U+217F. Strings longer than two characters will likely not be rendered very well. If this method is called, and a number was already set on the icon, it will automatically be reset to zero before rendering the label, i.e. the last method called between gtk_numerable_icon_set_label() and gtk_numerable_icon_set_count() has always priority. a #GtkNumerableIcon a short label, or %NULL Updates the icon to fetch theme information from the given #GtkStyleContext. a #GtkNumerableIcon a #GtkStyleContext GtkOffscreenWindow is strictly intended to be used for obtaining snapshots of widgets that are not part of a normal widget hierarchy. Since #GtkOffscreenWindow 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 GtkOffscreenWindow and then retrieve the snapshot as a #cairo_surface_t or #GdkPixbuf. GtkOffscreenWindow derives from #GtkWindow only as an implementation detail. Applications should not use any API specific to #GtkWindow to operate on this object. It should be treated as a #GtkBin that has no parent widget. When contained offscreen widgets are redrawn, GtkOffscreenWindow will emit a #GtkWidget::damage-event signal. Creates a toplevel container widget that is used to retrieve snapshots of widgets without showing them on the screen. A pointer to a #GtkWidget Retrieves a snapshot of the contained widget in the form of a #GdkPixbuf. This is a new pixbuf with a reference count of 1, and the application should unreference it once it is no longer needed. A #GdkPixbuf pointer, or %NULL. the #GtkOffscreenWindow contained widget. Retrieves a snapshot of the contained widget in the form of a #cairo_surface_t. If you need to keep this around over window resizes then you should add a reference to it. A #cairo_surface_t pointer to the offscreen surface, or %NULL. the #GtkOffscreenWindow contained widget. The parent class. The #GtkOrientable 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 #GtkBox/#GtkHBox/#GtkVBox or #GtkScale/#GtkHScale/#GtkVScale). #GtkOrientable is more flexible in that it allows the orientation to be changed at runtime, allowing the widgets to “flip”. #GtkOrientable was introduced in GTK+ 2.16. Retrieves the orientation of the @orientable. the orientation of the @orientable. a #GtkOrientable Sets the orientation of the @orientable. a #GtkOrientable the orientable’s new orientation. The orientation of the orientable. Represents the orientation of widgets and other objects which can be switched between horizontal and vertical orientation on the fly, like #GtkToolbar or #GtkGesturePan. The element is in horizontal orientation. The element is in vertical orientation. GtkOverlay 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 #GtkWidget:halign and #GtkWidget:valign properties. E.g. a widget with both alignments set to %GTK_ALIGN_START will be placed at the top left corner of the GtkOverlay container, whereas an overlay with halign set to %GTK_ALIGN_CENTER and valign set to %GTK_ALIGN_END will be placed a the bottom edge of the GtkOverlay, 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 #GtkOverlay::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. # GtkOverlay as GtkBuildable The GtkOverlay implementation of the GtkBuildable interface supports placing a child as an overlay by specifying “overlay” as the “type” attribute of a `<child>` element. # CSS nodes GtkOverlay 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. Creates a new #GtkOverlay. a new #GtkOverlay object. Adds @widget to @overlay. The widget will be stacked on top of the main widget added with gtk_container_add(). The position at which @widget is placed is determined from its #GtkWidget:halign and #GtkWidget:valign properties. a #GtkOverlay a #GtkWidget to be added to the container Convenience function to get the value of the #GtkOverlay:pass-through child property for @widget. whether the widget is a pass through child. a #GtkOverlay an overlay child of #GtkOverlay Moves @child to a new @index in the list of @overlay children. The list contains overlays in the order that these were added to @overlay by default. See also #GtkOverlay:index. A widget’s index in the @overlay 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. a #GtkOverlay the overlaid #GtkWidget to move the new index for @child in the list of overlay children of @overlay, starting from 0. If negative, indicates the end of the list Convenience function to set the value of the #GtkOverlay:pass-through child property for @widget. a #GtkOverlay an overlay child of #GtkOverlay whether the child should pass the input through 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 %GTK_ALIGN_FILL will cause the overlay to be full-width/height). If the main child is a #GtkScrolledWindow, the overlays are placed relative to its contents. %TRUE if the @allocation has been filled the child widget to position return location for the allocation The parent class. Name for the A3 paper size. Name for the A4 paper size. Name for the A5 paper size. Name for the B5 paper size. Name for the Executive paper size. Name for the Legal paper size. Name for the Letter paper size. The key used by the “Print to file” printer to store the file name of the output without the path to the directory and the file extension. The key used by the “Print to file” printer to store the directory to which the output should be written. The key used by the “Print to file” printer to store the format of the output. The supported values are “PS” and “PDF”. The key used by the “Print to file” printer to store the URI to which the output should be written. GTK+ itself supports only “file://” URIs. Use this priority for functionality related to size allocation. It is used internally by GTK+ to compute the sizes of widgets. This priority is higher than %GDK_PRIORITY_REDRAW to avoid resizing a widget which was just redrawn. Determines how widgets should be packed inside menubars and menuitems contained in menubars. Widgets are packed left-to-right Widgets are packed right-to-left Widgets are packed top-to-bottom Widgets are packed bottom-to-top Represents the packing location #GtkBox children. (See: #GtkVBox, #GtkHBox, and #GtkButtonBox). The child is packed into the start of the box The child is packed into the end of the box Struct defining a pad action entry. the type of pad feature that will trigger this action entry. the 0-indexed button/ring/strip number that will trigger this action entry. the mode that will trigger this action entry, or -1 for all modes. Human readable description of this action entry, this string should be deemed user-visible. action name that will be activated in the #GActionGroup. The type of a pad action. Action is triggered by a pad button Action is triggered by a pad ring Action is triggered by a pad strip #GtkPadController 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 #GAction objects, thus letting the application give those a more semantic meaning. Buttons and sensors are not constrained to triggering a single action, some %GDK_SOURCE_TABLET_PAD 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_device_pad_get_n_groups() and gdk_device_pad_get_group_n_modes(). Each of the actions that a given button/strip/ring performs for a given mode is defined by #GtkPadActionEntry, it contains an action name that will be looked up in the given #GActionGroup and activated whenever the specified input element and mode are triggered. A simple example of #GtkPadController usage, assigning button 1 in all modes and pad devices to an "invert-selection" action: |[ 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 #GVariantType. Creates a new #GtkPadController that will associate events from @pad to actions. A %NULL pad may be provided so the controller manages all pad devices generically, it is discouraged to mix #GtkPadController objects with %NULL and non-%NULL @pad argument on the same @window, as execution order is not guaranteed. The #GtkPadController is created with no mapped actions. In order to map pad events to actions, use gtk_pad_controller_set_action_entries() or gtk_pad_controller_set_action(). A newly created #GtkPadController a #GtkWindow #GActionGroup to trigger actions from A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads Adds an individual action to @controller. 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. a #GtkPadController the type of pad feature that will trigger this action the 0-indexed button/ring/strip number that will trigger this action the mode that will trigger this action, or -1 for all modes. Human readable description of this action, this string should be deemed user-visible. action name that will be activated in the #GActionGroup This is a convenience function to add a group of action entries on @controller. See #GtkPadActionEntry and gtk_pad_controller_set_action(). a #GtkPadController the action entries to set on @controller the number of elements in @entries See also gtk_print_settings_set_orientation(). Portrait mode. Landscape mode. Reverse portrait mode. Reverse landscape mode. See also gtk_print_settings_set_page_ranges(). start of page range. end of page range. See also gtk_print_job_set_page_set(). All pages. Even pages. Odd pages. A GtkPageSetup 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 #GtkPrintOperation when printing. The benefit of splitting this out of the #GtkPrintSettings 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 #GtkPageSetup use gtk_page_setup_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 |[<!-- language="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. Creates a new #GtkPageSetup. a new #GtkPageSetup. Reads the page setup from the file @file_name. Returns a new #GtkPageSetup object with the restored page setup, or %NULL if an error occurred. See gtk_page_setup_to_file(). the restored #GtkPageSetup the filename to read the page setup from Desrialize a page setup from an a{sv} variant in the format produced by gtk_page_setup_to_gvariant(). a new #GtkPageSetup object an a{sv} #GVariant Reads the page setup from the group @group_name in the key file @key_file. Returns a new #GtkPageSetup object with the restored page setup, or %NULL if an error occurred. the restored #GtkPageSetup the #GKeyFile to retrieve the page_setup from the name of the group in the key_file to read, or %NULL to use the default name “Page Setup” Copies a #GtkPageSetup. a copy of @other the #GtkPageSetup to copy Gets the bottom margin in units of @unit. the bottom margin a #GtkPageSetup the unit for the return value Gets the left margin in units of @unit. the left margin a #GtkPageSetup the unit for the return value Gets the page orientation of the #GtkPageSetup. the page orientation a #GtkPageSetup Returns the page height in units of @unit. Note that this function takes orientation and margins into consideration. See gtk_page_setup_get_paper_height(). the page height. a #GtkPageSetup the unit for the return value Returns the page width in units of @unit. Note that this function takes orientation and margins into consideration. See gtk_page_setup_get_paper_width(). the page width. a #GtkPageSetup the unit for the return value Returns the paper height in units of @unit. Note that this function takes orientation, but not margins into consideration. See gtk_page_setup_get_page_height(). the paper height. a #GtkPageSetup the unit for the return value Gets the paper size of the #GtkPageSetup. the paper size a #GtkPageSetup Returns the paper width in units of @unit. Note that this function takes orientation, but not margins into consideration. See gtk_page_setup_get_page_width(). the paper width. a #GtkPageSetup the unit for the return value Gets the right margin in units of @unit. the right margin a #GtkPageSetup the unit for the return value Gets the top margin in units of @unit. the top margin a #GtkPageSetup the unit for the return value Reads the page setup from the file @file_name. See gtk_page_setup_to_file(). %TRUE on success a #GtkPageSetup the filename to read the page setup from Reads the page setup from the group @group_name in the key file @key_file. %TRUE on success a #GtkPageSetup the #GKeyFile to retrieve the page_setup from the name of the group in the key_file to read, or %NULL to use the default name “Page Setup” Sets the bottom margin of the #GtkPageSetup. a #GtkPageSetup the new bottom margin in units of @unit the units for @margin Sets the left margin of the #GtkPageSetup. a #GtkPageSetup the new left margin in units of @unit the units for @margin Sets the page orientation of the #GtkPageSetup. a #GtkPageSetup a #GtkPageOrientation value Sets the paper size of the #GtkPageSetup without changing the margins. See gtk_page_setup_set_paper_size_and_default_margins(). a #GtkPageSetup a #GtkPaperSize Sets the paper size of the #GtkPageSetup and modifies the margins according to the new paper size. a #GtkPageSetup a #GtkPaperSize Sets the right margin of the #GtkPageSetup. a #GtkPageSetup the new right margin in units of @unit the units for @margin Sets the top margin of the #GtkPageSetup. a #GtkPageSetup the new top margin in units of @unit the units for @margin This function saves the information from @setup to @file_name. %TRUE on success a #GtkPageSetup the file to save to Serialize page setup to an a{sv} variant. a new, floating, #GVariant a #GtkPageSetup This function adds the page setup from @setup to @key_file. a #GtkPageSetup the #GKeyFile to save the page setup to the group to add the settings to in @key_file, or %NULL to use the default name “Page Setup” The type of function that is passed to gtk_print_run_page_setup_dialog_async(). This function will be called when the page setup dialog is dismissed, and also serves as destroy notify for @data. the #GtkPageSetup that has been user data that has been passed to gtk_print_run_page_setup_dialog_async() Describes the panning direction of a #GtkGesturePan panned towards the left panned towards the right panned upwards panned downwards #GtkPaned 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 gtk_paned_pack1() and gtk_paned_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 #GtkFrame with the shadow type set to %GTK_SHADOW_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 #GtkPaned 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 gtk_paned_set_position(). # CSS nodes |[<!-- language="plain" --> paned ├── <child> ├── separator[.wide] ╰── <child> ]| GtkPaned 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. |[<!-- language="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); ]| Creates a new #GtkPaned widget. a new #GtkPaned. the paned’s orientation. Adds a child to the top or left pane with default parameters. This is equivalent to `gtk_paned_pack1 (paned, child, FALSE, TRUE)`. a paned widget the child to add Adds a child to the bottom or right pane with default parameters. This is equivalent to `gtk_paned_pack2 (paned, child, TRUE, TRUE)`. a paned widget the child to add Obtains the first child of the paned widget. first child, or %NULL if it is not set. a #GtkPaned widget Obtains the second child of the paned widget. second child, or %NULL if it is not set. a #GtkPaned widget Returns the #GdkWindow 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. the paned’s handle window. a #GtkPaned Obtains the position of the divider between the two panes. position of the divider a #GtkPaned widget Gets the #GtkPaned:wide-handle property. %TRUE if the paned should have a wide handle a #GtkPaned Adds a child to the top or left pane. a paned widget the child to add should this child expand when the paned widget is resized. can this child be made smaller than its requisition. Adds a child to the bottom or right pane. a paned widget the child to add should this child expand when the paned widget is resized. can this child be made smaller than its requisition. Sets the position of the divider between the two panes. a #GtkPaned widget pixel position of divider, a negative value means that the position is unset. Sets the #GtkPaned:wide-handle property. a #GtkPaned the new value for the #GtkPaned:wide-handle property The largest possible value for the position property. This property is derived from the size and shrinkability of the widget's children. The smallest possible value for the position property. This property is derived from the size and shrinkability of the widget's children. 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). The ::accept-position signal is a [keybinding signal][GtkBindingSignal] 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. The ::cancel-position signal is a [keybinding signal][GtkBindingSignal] 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. The ::cycle-child-focus signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cycle the focus between the children of the paned. The default binding is f6. whether cycling backward or forward The ::cycle-handle-focus signal is a [keybinding signal][GtkBindingSignal] 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. whether cycling backward or forward The ::move-handle signal is a [keybinding signal][GtkBindingSignal] which gets emitted to move the handle when the user is using key bindings to move it. a #GtkScrollType The ::toggle-handle-focus is a [keybinding signal][GtkBindingSignal] 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. GtkPaperSize 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, GtkPaperSize allows to construct custom paper sizes with arbitrary dimensions. The #GtkPaperSize 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. Creates a new #GtkPaperSize 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 %NULL, the default paper size is returned, see gtk_paper_size_get_default(). a new #GtkPaperSize, use gtk_paper_size_free() to free it a paper size name, or %NULL Creates a new #GtkPaperSize object with the given parameters. a new #GtkPaperSize object, use gtk_paper_size_free() to free it the paper name the human-readable name the paper width, in units of @unit the paper height, in units of @unit the unit for @width and @height. not %GTK_UNIT_NONE. Deserialize a paper size from an a{sv} variant in the format produced by gtk_paper_size_to_gvariant(). a new #GtkPaperSize object an a{sv} #GVariant Creates a new #GtkPaperSize object by using IPP information. If @ipp_name is not a recognized paper name, @width and @height are used to construct a custom #GtkPaperSize object. a new #GtkPaperSize, use gtk_paper_size_free() to free it an IPP paper name the paper width, in points the paper height in points Reads a paper size from the group @group_name in the key file @key_file. a new #GtkPaperSize object with the restored paper size, or %NULL if an error occurred the #GKeyFile to retrieve the papersize from the name of the group in the key file to read, or %NULL to read the first group Creates a new #GtkPaperSize 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 #GtkPaperSize object. a new #GtkPaperSize, use gtk_paper_size_free() to free it a PPD paper name the corresponding human-readable name the paper width, in points the paper height in points Copies an existing #GtkPaperSize. a copy of @other a #GtkPaperSize Free the given #GtkPaperSize object. a #GtkPaperSize Gets the default bottom margin for the #GtkPaperSize. the default bottom margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the default left margin for the #GtkPaperSize. the default left margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the default right margin for the #GtkPaperSize. the default right margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the default top margin for the #GtkPaperSize. the default top margin a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the human-readable name of the #GtkPaperSize. the human-readable name of @size a #GtkPaperSize object Gets the paper height of the #GtkPaperSize, in units of @unit. the paper height a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Gets the name of the #GtkPaperSize. the name of @size a #GtkPaperSize object Gets the PPD name of the #GtkPaperSize, which may be %NULL. the PPD name of @size a #GtkPaperSize object Gets the paper width of the #GtkPaperSize, in units of @unit. the paper width a #GtkPaperSize object the unit for the return value, not %GTK_UNIT_NONE Returns %TRUE if @size is not a standard paper size. whether @size is a custom paper size. a #GtkPaperSize object Compares two #GtkPaperSize objects. %TRUE, if @size1 and @size2 represent the same paper size a #GtkPaperSize object another #GtkPaperSize object Returns %TRUE if @size is an IPP standard paper size. whether @size is not an IPP custom paper size. a #GtkPaperSize object Changes the dimensions of a @size to @width x @height. a custom #GtkPaperSize object the new width in units of @unit the new height in units of @unit the unit for @width and @height Serialize a paper size to an a{sv} variant. a new, floating, #GVariant a #GtkPaperSize This function adds the paper size from @size to @key_file. a #GtkPaperSize the #GKeyFile to save the paper size to the group to add the settings to in @key_file Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK+ and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated #GtkPaperSize objects whether to include custom paper sizes as defined in the page setup dialog Priorities for path lookups. See also gtk_binding_set_add_path(). Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Widget path types. See also gtk_binding_set_add_path(). Deprecated Deprecated Deprecated These flags serve two purposes. First, the application can call gtk_places_sidebar_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 #GtkPlacesSidebar::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 gtk_places_sidebar_set_open_flags(), then the sidebar will only use #GTK_PLACES_OPEN_NORMAL in the #GtkPlacesSidebar::open-location signal. This is the default mode of operation. This is the default mode that #GtkPlacesSidebar 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. When passed to gtk_places_sidebar_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 #GtkPlacesSidebar::open-location signal when the user selects that a location be opened in a new tab instead of in the standard fashion. Similar to @GTK_PLACES_OPEN_NEW_TAB, but indicates that the application can open folders in new windows. #GtkPlacesSidebar 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 #GtkFileChooser 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 gtk_places_sidebar_add_shortcut(). To make use of the places sidebar, an application at least needs to connect to the #GtkPlacesSidebar::open-location signal. This is emitted when the user selects in the sidebar a location to open. The application should also call gtk_places_sidebar_set_location() when it changes the currently-viewed location. # CSS nodes GtkPlacesSidebar 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 Creates a new #GtkPlacesSidebar widget. The application should connect to at least the #GtkPlacesSidebar::open-location signal to be notified when the user makes a selection in the sidebar. a newly created #GtkPlacesSidebar 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. a places sidebar location to add as an application-specific shortcut Returns the value previously set with gtk_places_sidebar_set_local_only(). %TRUE if the sidebar will only show local files. a places sidebar Gets the currently selected location in the @sidebar. This can be %NULL when nothing is selected, for example, when gtk_places_sidebar_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 @sidebar. Also, if you connect to the #GtkPlacesSidebar::populate-popup signal, you can use this function to get the location that is being referred to during the callbacks for your menu items. a #GFile with the selected location, or %NULL if nothing is visually selected. a places sidebar This function queries the bookmarks added by the user to the places sidebar, and returns one of them. This function is used by #GtkFileChooser to implement the “Alt-1”, “Alt-2”, etc. shortcuts, which activate the cooresponding bookmark. The bookmark specified by the index @n, or %NULL 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". a places sidebar index of the bookmark to query Gets the open flags. the #GtkPlacesOpenFlags of @sidebar a #GtkPlacesSidebar Returns the value previously set with gtk_places_sidebar_set_show_connect_to_server() It is recommended to group this functionality with the drives and network location under the new 'Other Location' item %TRUE if the sidebar will display a “Connect to Server” item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_desktop() %TRUE if the sidebar will display a builtin shortcut to the desktop folder. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_enter_location() %TRUE if the sidebar will display an “Enter Location” item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_other_locations() %TRUE if the sidebar will display an “Other Locations” item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_recent() %TRUE if the sidebar will display a builtin shortcut for recent files a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_starred_location() %TRUE if the sidebar will display a Starred item. a places sidebar Returns the value previously set with gtk_places_sidebar_set_show_trash() %TRUE if the sidebar will display a “Trash” item. a places sidebar Gets the list of shortcuts. A #GSList of #GFile of the locations that have been added as application-specific shortcuts with gtk_places_sidebar_add_shortcut(). To free this list, you can use |[<!-- language="C" --> g_slist_free_full (list, (GDestroyNotify) g_object_unref); ]| a places sidebar Removes an application-specific shortcut that has been previously been inserted with gtk_places_sidebar_add_shortcut(). If the @location is not a shortcut in the sidebar, then nothing is done. a places sidebar location to remove Make the GtkPlacesSidebar 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 GtkPlacesSidebar. You only need to unset the state when the drag ends on some other widget on your application. a places sidebar. whether to show the valid targets or not. drag context used to ask the source about the action that wants to perform, so hints are more accurate. Sets whether the @sidebar should only show local files. a places sidebar whether to show only local files Sets the location that is being shown in the widgets surrounding the @sidebar, for example, in a folder view in a file manager. In turn, the @sidebar 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. a places sidebar location to select, or %NULL for no current path 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 @sidebar 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 #GtkPlacesSidebar::open-location signal is emitted, its flags argument will be set to one of the @flags that was passed in gtk_places_sidebar_set_open_flags(). Passing 0 for @flags will cause #GTK_PLACES_OPEN_NORMAL to always be sent to callbacks for the “open-location” signal. a places sidebar Bitmask of modes in which the calling application can open locations Sets whether the @sidebar 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 #GtkPlacesSidebar::show-connect-to-server signal. It is recommended to group this functionality with the drives and network location under the new 'Other Location' item a places sidebar whether to show an item for the Connect to Server command Sets whether the @sidebar 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. a places sidebar whether to show an item for the Desktop folder Sets whether the @sidebar 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 #GtkPlacesSidebar::show-enter-location signal. a places sidebar whether to show an item to enter a location Sets whether the @sidebar 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 #GtkPlacesSidebar::show-other-locations signal. a places sidebar whether to show an item for the Other Locations view Sets whether the @sidebar 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. a places sidebar whether to show an item for recent files If you enable this, you should connect to the #GtkPlacesSidebar::show-starred-location signal. a places sidebar whether to show an item for Starred files Sets whether the @sidebar should show an item for the Trash location. a places sidebar whether to show an item for the Trash location If :populate-all is %TRUE, the #GtkPlacesSidebar::populate-popup signal is also emitted for popovers. 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. the final drag action that the sidebar should pass to the drag side of the drag-and-drop operation. Possible drag actions that need to be asked for. 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. The drag action to use, for example, #GDK_ACTION_COPY or #GDK_ACTION_MOVE, or 0 if no action is allowed here (i.e. drops are not allowed in the specified @dest_file). #GdkDragContext with information about the drag operation #GFile with the tentative location that is being hovered for a drop List of #GFile that are being dragged 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. Destination #GFile. #GList of #GFile that got dropped. Drop action to perform. 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 #GtkPlacesSidebar can track the progress of the operation and, for example, show a notification. the #GMountOperation that is going to start. 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. #GFile to which the caller should switch. a single value from #GtkPlacesOpenFlags specifying how the @location should be opened. 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 gtk_places_sidebar_get_location() to get the file to which the item refers. The @selected_item argument may be %NULL in case the selection refers to a volume. In this case, @selected_volume will be non-%NULL. In this case, the calling application will have to g_object_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 #GtkMenu, and you were expected to add your items as #GtkMenuItems. Since 3.18, the popup may be implemented as a #GtkPopover, in which case @container will be something else, e.g. a #GtkBox, 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 #GtkPlacesSidebar::populate-all to %TRUE to request that this signal is emitted for populating popovers as well. a #GtkMenu or another #GtkContainer #GFile with the item to which the popup should refer, or %NULL in the case of a @selected_volume. #GVolume if the selected item is a volume, or %NULL if it is a file. 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, g_file_mount_enclosing_volume(). use the #GtkPlacesSidebar::show-other-locations signal to connect to network servers. 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". 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 message with a summary of the error to show. secondary message with details of the error to show. 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. use the #GtkPlacesSidebar::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 #GtkPlacesSidebar::open-location 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. a single value from #GtkPlacesOpenFlags specifying how it should be opened. 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. a single value from #GtkPlacesOpenFlags specifying how the starred file should be opened. 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 #GtkPlacesSidebar can track the progress of the operation and, for example, show a notification. the #GMountOperation that is going to start. Together with #GtkSocket, #GtkPlug 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 #GtkSocket widget and passes the ID of that widget’s window to the other process, which then creates a #GtkPlug with that window ID. Any widgets contained in the #GtkPlug then will appear inside the first application’s window. The communication between a #GtkSocket and a #GtkPlug 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 #GtkPlug and #GtkSocket 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 #GtkPlug and #GtkSocket, you need to include the `gtk/gtkx.h` header. Creates a new plug widget inside the #GtkSocket identified by @socket_id. If @socket_id is 0, the plug is left “unplugged” and can later be plugged into a #GtkSocket by gtk_socket_add_id(). the new #GtkPlug widget. the window ID of the socket, or 0. Create a new plug widget inside the #GtkSocket identified by socket_id. the new #GtkPlug widget. the #GdkDisplay on which @socket_id is displayed the XID of the socket’s window. Finish the initialization of @plug for a given #GtkSocket identified by @socket_id. This function will generally only be used by classes deriving from #GtkPlug. a #GtkPlug. the XID of the socket’s window. Finish the initialization of @plug for a given #GtkSocket identified by @socket_id which is currently displayed on @display. This function will generally only be used by classes deriving from #GtkPlug. a #GtkPlug. the #GdkDisplay associated with @socket_id’s #GtkSocket. the XID of the socket’s window. Determines whether the plug is embedded in a socket. %TRUE if the plug is embedded in a socket a #GtkPlug Gets the window ID of a #GtkPlug widget, which can then be used to embed this window inside another window, for instance with gtk_socket_add_id(). the window ID for the plug a #GtkPlug. Retrieves the socket the plug is embedded in. the window of the socket, or %NULL a #GtkPlug %TRUE if the plug is embedded in a socket. The window of the socket the plug is embedded in. Gets emitted when the plug becomes embedded in a socket. Determines how the size should be computed to achieve the one of the visibility mode for the scrollbars. The scrollbar is always visible. The view size is independent of the content. The scrollbar will appear and disappear as necessary. For example, when all of a #GtkTreeView can not be seen. The scrollbar should never appear. In this mode the content determines the size. 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 GtkPopover 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 gtk_popover_new(), or updated afterwards through gtk_popover_set_relative_to(), by default they will point to the whole widget area, although this behavior can be changed through gtk_popover_set_pointing_to(). The position of a popover relative to the widget it is attached to can also be changed through gtk_popover_set_position(). By default, #GtkPopover 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, gtk_popover_set_modal() may be called on it to tweak its behavior. ## GtkPopover as menu replacement GtkPopover is often used to replace menus. To facilitate this, it supports being populated from a #GMenuModel, using gtk_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. |[ <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 GtkPopover 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. #GtkPopoverMenu or created using gtk_popover_new_from_model(). Particular uses of GtkPopover, such as touch selection popups or magnifiers in #GtkEntry or #GtkTextView get style classes like .touch-selection or .magnifier to differentiate from plain popovers. Creates a new popover to point to @relative_to a new #GtkPopover #GtkWidget the popover is related to Creates a #GtkPopover 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 #GtkApplicationWindow 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 gtk_widget_insert_action_group() on the menus attach widget or on any of its parent widgets. the new #GtkPopover #GtkWidget the popover is related to a #GMenuModel Establishes a binding between a #GtkPopover and a #GMenuModel. The contents of @popover are removed and then refilled with menu items according to @model. When @model changes, @popover is updated. Calling this function twice on @popover with different @model will cause the first binding to be replaced with a binding to the new model. If @model is %NULL then any previous binding is undone and all children are removed. If @action_namespace is non-%NULL 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 #GtkActionable 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 #GtkMenuShell outside of a #GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using gtk_widget_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 #GMenuModel. a #GtkPopover the #GMenuModel to bind to or %NULL to remove binding the namespace for actions in @model Returns the constraint for placing this popover. See gtk_popover_set_constrain_to(). the constraint for placing this popover. a #GtkPopover Gets the widget that should be set as the default while the popover is shown. the default widget, or %NULL if there is none a #GtkPopover Returns whether the popover is modal, see gtk_popover_set_modal to see the implications of this. #TRUE if @popover is modal a #GtkPopover 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. %TRUE if a rectangle to point to was set. a #GtkPopover location to store the rectangle Returns the preferred position of @popover. The preferred position. a #GtkPopover Returns the widget @popover is currently attached to a #GtkWidget a #GtkPopover Returns whether show/hide transitions are enabled on this popover. You can show or hide the popover without transitions using gtk_widget_show() and gtk_widget_hide() while gtk_popover_popup() and gtk_popover_popdown() will use transitions. #TRUE if the show and hide transitions of the given popover are enabled, #FALSE otherwise. a #GtkPopover Pops @popover down.This is different than a gtk_widget_hide() call in that it shows the popover with a transition. If you want to hide the popover without a transition, use gtk_widget_hide(). a #GtkPopover Pops @popover up. This is different than a gtk_widget_show() call in that it shows the popover with a transition. If you want to show the popover without a transition, use gtk_widget_show(). a #GtkPopover Sets a constraint for positioning this popover. Note that not all platforms support placing popovers freely, and may already impose constraints. a #GtkPopover the new constraint Sets the widget that should be set as default widget while the popover is shown (see gtk_window_set_default()). #GtkPopover remembers the previous default widget and reestablishes it when the popover is dismissed. a #GtkPopover the new default widget, or %NULL Sets whether @popover 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. a #GtkPopover #TRUE to make popover claim all input within the toplevel Sets the rectangle that @popover will point to, in the coordinate space of the widget @popover is attached to, see gtk_popover_set_relative_to(). a #GtkPopover rectangle to point to Sets the preferred position for @popover to appear. If the @popover 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 #GtkPopover may choose to appear on the opposite side a #GtkPopover preferred popover position Sets a new widget to be attached to @popover. If @popover 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 %NULL on an attached @popover, it will be detached from its previous widget, and consequently destroyed unless extra references are kept. a #GtkPopover a #GtkWidget Sets whether show/hide transitions are enabled on this popover You can show or hide the popover without transitions using gtk_widget_show() and gtk_widget_hide() while gtk_popover_popup() and gtk_popover_popdown() will use transitions. a #GtkPopover Whether transitions are enabled Sets a constraint for the popover position. Sets whether the popover is modal (so other elements in the window do not receive input while the popover is visible). Marks a specific rectangle to be pointed. Sets the preferred position of the popover. Sets the attached widget. Whether show/hide transitions are enabled for this popover. You can show or hide the popover without transitions using gtk_widget_show() and gtk_widget_hide() while gtk_popover_popup() and gtk_popover_popdown() will use transitions. This signal is emitted when the popover is dismissed either through API or user interaction. Describes constraints to positioning of popovers. More values may be added to this enumeration in the future. Don't constrain the popover position beyond what is imposed by the implementation Constrain the popover to the boundaries of the window that it is attached to GtkPopoverMenu is a subclass of #GtkPopover that treats its children like menus and allows switching between them. It is meant to be used primarily together with #GtkModelButton, but any widget can be used, such as #GtkSpinButton or #GtkScale. In this respect, GtkPopoverMenu is more flexible than popovers that are created from a #GMenuModel with gtk_popover_new_from_model(). To add a child as a submenu, set the #GtkPopoverMenu:submenu child property to the name of the submenu. To let the user open this submenu, add a #GtkModelButton whose #GtkModelButton: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 #GtkModelButton to switch back to the parent menu. Such a button should use the #GtkModelButton:inverted and #GtkModelButton: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 |[ <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, #GtkPopoverMenu instances have a single css node called "popover" and get the .menu style class. Creates a new popover menu. a new #GtkPopoverMenu Opens a submenu of the @popover. The @name must be one of the names given to the submenus of @popover with #GtkPopoverMenu:submenu, or "main" to switch back to the main menu. #GtkModelButton will open submenus automatically when the #GtkModelButton:menu-name property is set, so this function is only needed when you are using other kinds of widgets to initiate menu changes. a #GtkPopoverMenu the name of the menu to switch to Describes which edge of a widget a certain feature is positioned at, e.g. the tabs of a #GtkNotebook, the handle of a #GtkHandleBox or the label of a #GtkScale. The feature is at the left edge. The feature is at the right edge. The feature is at the top edge. The feature is at the bottom edge. A GtkPrintContext 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 #PangoLayout and #PangoContext objects that match the font metrics of the cairo surface. GtkPrintContext objects gets passed to the #GtkPrintOperation::begin-print, #GtkPrintOperation::end-print, #GtkPrintOperation::request-page-setup and #GtkPrintOperation::draw-page signals on the #GtkPrintOperation. ## Using GtkPrintContext in a #GtkPrintOperation::draw-page callback |[<!-- language="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. Creates a new #PangoContext that can be used with the #GtkPrintContext. a new Pango context for @context a #GtkPrintContext Creates a new #PangoLayout that is suitable for use with the #GtkPrintContext. a new Pango layout for @context a #GtkPrintContext Obtains the cairo context that is associated with the #GtkPrintContext. the cairo context of @context a #GtkPrintContext Obtains the horizontal resolution of the #GtkPrintContext, in dots per inch. the horizontal resolution of @context a #GtkPrintContext Obtains the vertical resolution of the #GtkPrintContext, in dots per inch. the vertical resolution of @context a #GtkPrintContext Obtains the hardware printer margins of the #GtkPrintContext, in units. %TRUE if the hard margins were retrieved a #GtkPrintContext top hardware printer margin bottom hardware printer margin left hardware printer margin right hardware printer margin Obtains the height of the #GtkPrintContext, in pixels. the height of @context a #GtkPrintContext Obtains the #GtkPageSetup that determines the page dimensions of the #GtkPrintContext. the page setup of @context a #GtkPrintContext Returns a #PangoFontMap that is suitable for use with the #GtkPrintContext. the font map of @context a #GtkPrintContext Obtains the width of the #GtkPrintContext, in pixels. the width of @context a #GtkPrintContext 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. a #GtkPrintContext the cairo context the horizontal resolution to use with @cr the vertical resolution to use with @cr See also gtk_print_settings_set_duplex(). No duplex. Horizontal duplex. Vertical duplex. Error codes that identify various errors that can occur while using the GTK+ printing support. An unspecified error occurred. An internal error occurred. A memory allocation failed. An error occurred while loading a page setup or paper size from a key file. Registers an error quark for #GtkPrintOperation if necessary. The error quark used for #GtkPrintOperation errors. GtkPrintOperation is the high-level, portable printing API. It looks a bit different than other GTK+ dialogs such as the #GtkFileChooser, since some platforms don’t expose enough infrastructure to implement a good print dialog. On such platforms, GtkPrintOperation 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 GtkPrintOperation object with gtk_print_operation_new() when the user selects to print. Then you set some properties on it, e.g. the page size, any #GtkPrintSettings from previous print operations, the number of pages, the current page, etc. Then you start the print operation by calling gtk_print_operation_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 #GtkPrintOperation, the main one being #GtkPrintOperation::draw-page, which you are supposed to catch and render the page on the provided #GtkPrintContext using Cairo. # The high-level printing API |[<!-- language="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 GtkPrintOperation uses an external application to do print preview. To implement a custom print preview, an application must connect to the preview signal. The functions gtk_print_operation_preview_render_page(), gtk_print_operation_preview_end_preview() and gtk_print_operation_preview_is_selected() are useful when implementing a print preview. Creates a new #GtkPrintOperation. a new #GtkPrintOperation Cancels a running print operation. This function may be called from a #GtkPrintOperation::begin-print, #GtkPrintOperation::paginate or #GtkPrintOperation::draw-page signal handler to stop the currently running print operation. a #GtkPrintOperation Signalize that drawing of particular page is complete. It is called after completion of page drawing (e.g. drawing in another thread). If gtk_print_operation_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. a #GtkPrintOperation Returns the default page setup, see gtk_print_operation_set_default_page_setup(). the default page setup a #GtkPrintOperation Gets the value of #GtkPrintOperation:embed-page-setup property. whether page setup selection combos are embedded a #GtkPrintOperation Call this when the result of a print operation is %GTK_PRINT_OPERATION_RESULT_ERROR, either as returned by gtk_print_operation_run(), or in the #GtkPrintOperation::done signal handler. The returned #GError will contain more details on what went wrong. a #GtkPrintOperation Gets the value of #GtkPrintOperation:has-selection property. whether there is a selection a #GtkPrintOperation Returns the number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this function should never be called before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the #GtkPrintOperation::status-changed signal and call gtk_print_operation_get_n_pages_to_print() when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. the number of pages that will be printed a #GtkPrintOperation Returns the current print settings. Note that the return value is %NULL until either gtk_print_operation_set_print_settings() or gtk_print_operation_run() have been called. the current print settings of @op. a #GtkPrintOperation Returns the status of the print operation. Also see gtk_print_operation_get_status_string(). the status of the print operation a #GtkPrintOperation 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 #GtkStatusbar. Use gtk_print_operation_get_status() to obtain a status value that is suitable for programmatic use. a string representation of the status of the print operation a #GtkPrintOperation Gets the value of #GtkPrintOperation:support-selection property. whether the application supports print of selection a #GtkPrintOperation A convenience function to find out if the print operation is finished, either successfully (%GTK_PRINT_STATUS_FINISHED) or unsuccessfully (%GTK_PRINT_STATUS_FINISHED_ABORTED). 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. %TRUE, if the print operation is finished. a #GtkPrintOperation 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 #GtkPrintOperation::status-changed signal on @op 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 gtk_print_operation_set_allow_async() or set the #GtkPrintOperation:allow-async property the operation will run asynchronously if this is supported on the platform. The #GtkPrintOperation::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). |[<!-- language="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 gtk_print_operation_run() can only be called once on a given #GtkPrintOperation. the result of the print operation. A return value of %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with gtk_print_operation_get_print_settings() and store them for reuse with the next print operation. A value of %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS means the operation is running asynchronously, and will emit the #GtkPrintOperation::done signal when done. a #GtkPrintOperation the action to start Transient parent of the dialog Sets whether the gtk_print_operation_run() may return before the print operation is completed. Note that some platforms may not allow asynchronous operation. a #GtkPrintOperation %TRUE to allow asynchronous operation Sets the current page. If this is called before gtk_print_operation_run(), the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. a #GtkPrintOperation the current page, 0-based Sets the label for the tab holding custom widgets. a #GtkPrintOperation the label to use, or %NULL to use the default label Makes @default_page_setup the default page setup for @op. This page setup will be used by gtk_print_operation_run(), but it can be overridden on a per-page basis by connecting to the #GtkPrintOperation::request-page-setup signal. a #GtkPrintOperation a #GtkPageSetup, or %NULL Sets up the #GtkPrintOperation to wait for calling of gtk_print_operation_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. a #GtkPrintOperation Embed page size combo box and orientation combo box into page setup page. Selected page setup is stored as default page setup in #GtkPrintOperation. a #GtkPrintOperation %TRUE to embed page setup selection in the #GtkPrintUnixDialog Sets up the #GtkPrintOperation 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. a #GtkPrintOperation the filename for the exported file Sets whether there is a selection to print. Application has to set number of pages to which the selection will draw by gtk_print_operation_set_n_pages() in a callback of #GtkPrintOperation::begin-print. a #GtkPrintOperation %TRUE indicates that a selection exists 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. a #GtkPrintOperation a string that identifies the print job 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 #GtkPrintOperation::begin-print signal hander. Note that the page numbers passed to the #GtkPrintOperation::request-page-setup and #GtkPrintOperation::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. a #GtkPrintOperation the number of pages Sets the print settings for @op. This is typically used to re-establish print settings from a previous print operation, see gtk_print_operation_run(). a #GtkPrintOperation #GtkPrintSettings If @show_progress is %TRUE, the print operation will show a progress dialog during the print operation. a #GtkPrintOperation %TRUE to show a progress dialog Sets whether selection is supported by #GtkPrintOperation. a #GtkPrintOperation %TRUE to support selection 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. a #GtkPrintOperation %TRUE to track status after printing Sets up the transformation for the cairo context obtained from #GtkPrintContext in such a way that distances are measured in units of @unit. a #GtkPrintOperation the unit to use If @full_page is %TRUE, the transformation for the cairo context obtained from #GtkPrintContext 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). a #GtkPrintOperation %TRUE to set up the #GtkPrintContext for the full page Determines whether the print operation may run asynchronously or not. Some systems don't support asynchronous printing, but those that do will return %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and emit the #GtkPrintOperation::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 %GTK_PRINT_OPERATION_ACTION_EXPORT support asynchronous operation. The current page in the document. If this is set before gtk_print_operation_run(), the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. If this is %NULL, GTK+ uses a default label. The #GtkPageSetup used by default. This page setup will be used by gtk_print_operation_run(), but it can be overridden on a per-page basis by connecting to the #GtkPrintOperation::request-page-setup signal. If %TRUE, page size combo box and orientation combo box are embedded into page setup page. 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. 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. 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. 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 #GtkPrintOperation::begin-print signal hander. Note that the page numbers passed to the #GtkPrintOperation::request-page-setup and #GtkPrintOperation::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. The number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this value should never be get before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the #GtkPrintOperation::status-changed signal and call gtk_print_operation_get_n_pages_to_print() when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. The #GtkPrintSettings used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see gtk_print_operation_run(). Determines whether to show a progress dialog during the print operation. The status of the print operation. 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 #GtkStatusbar. See the #GtkPrintOperation:status property for a status value that is suitable for programmatic use. If %TRUE, the print operation will support print of selection. This allows the print dialog to show a "Selection" button. 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. The transformation for the cairo context obtained from #GtkPrintContext is set up in such a way that distances are measured in units of @unit. If %TRUE, the transformation for the cairo context obtained from #GtkPrintContext 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). 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 #GtkPrintContext and paginate the document accordingly, and then set the number of pages with gtk_print_operation_set_n_pages(). the #GtkPrintContext for the current operation 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 #GtkPrintOperation::custom-widget-apply signal is emitted on the operation. Then you can read out any information you need from the widgets. A custom widget that gets embedded in the print dialog, or %NULL Emitted right before #GtkPrintOperation::begin-print if you added a custom widget in the #GtkPrintOperation::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. the custom widget added in create-custom-widget 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 %GTK_PRINT_OPERATION_RESULT_ERROR then you can call gtk_print_operation_get_error() for more information. If you enabled print status tracking then gtk_print_operation_is_finished() may still return %FALSE after #GtkPrintOperation::done was emitted. the result of the print operation 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 gtk_print_context_get_cairo_context(). |[<!-- language="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 gtk_print_operation_set_use_full_page() and gtk_print_operation_set_unit() before starting the print operation to set up the transformation of the cairo context according to your needs. the #GtkPrintContext for the current operation the number of the currently printed page (0-based) Emitted after all pages have been rendered. A handler for this signal can clean up any resources that have been allocated in the #GtkPrintOperation::begin-print handler. the #GtkPrintContext for the current operation Emitted after the #GtkPrintOperation::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 gtk_print_operation_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. %TRUE if pagination is complete the #GtkPrintContext for the current operation 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 gtk_print_context_set_cairo_context(). The custom preview implementation can use gtk_print_operation_preview_is_selected() and gtk_print_operation_preview_render_page() to find pages which are selected for print and render them. The preview must be finished by calling gtk_print_operation_preview_end_preview() (typically in response to the user clicking a close button). %TRUE if the listener wants to take over control of the preview the #GtkPrintOperationPreview for the current operation the #GtkPrintContext that will be used the #GtkWindow to use as window parent, or %NULL 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. the #GtkPrintContext for the current operation the number of the currently printed page (0-based) the #GtkPageSetup Emitted at between the various phases of the print operation. See #GtkPrintStatus for the phases that are being discriminated. Use gtk_print_operation_get_status() to find out the current status. 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. the custom widget added in create-custom-widget actual page setup actual print settings The @action parameter to gtk_print_operation_run() determines what action the print operation should perform. Show the print dialog. Start to print without showing the print dialog, based on the current print settings. Show the print preview. Export to a file. This requires the export-filename property to be set. The parent class. Ends a preview. This function must be called to finish a custom print preview. a #GtkPrintOperationPreview Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a #GtkPrintOperationPreview a page number Renders a page to the preview, using the print context that was passed to the #GtkPrintOperation::preview handler together with @preview. 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. a #GtkPrintOperationPreview the page to render Ends a preview. This function must be called to finish a custom print preview. a #GtkPrintOperationPreview Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a #GtkPrintOperationPreview a page number Renders a page to the preview, using the print context that was passed to the #GtkPrintOperation::preview handler together with @preview. 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. a #GtkPrintOperationPreview the page to render 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 gtk_print_context_set_cairo_context(). the current #GtkPrintContext the #GtkPageSetup for the current page 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. the current #GtkPrintContext a #GtkPrintOperationPreview the page to render %TRUE if the page has been selected for printing a #GtkPrintOperationPreview a page number a #GtkPrintOperationPreview A value of this type is returned by gtk_print_operation_run(). An error has occurred. The print settings should be stored. The print operation has been canceled, the print settings should not be stored. The print operation is not complete yet. This value will only be returned when running asynchronously. See also gtk_print_job_set_pages() All pages. Current page. Range of pages. Selected pages. See also gtk_print_settings_set_quality(). Low quality. Normal quality. High quality. Draft quality. A GtkPrintSettings 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. Creates a new #GtkPrintSettings object. a new #GtkPrintSettings object Reads the print settings from @file_name. Returns a new #GtkPrintSettings object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. See gtk_print_settings_to_file(). the restored #GtkPrintSettings the filename to read the settings from Deserialize print settings from an a{sv} variant in the format produced by gtk_print_settings_to_gvariant(). a new #GtkPrintSettings object an a{sv} #GVariant Reads the print settings from the group @group_name in @key_file. Returns a new #GtkPrintSettings object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. the restored #GtkPrintSettings the #GKeyFile to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Copies a #GtkPrintSettings object. a newly allocated copy of @other a #GtkPrintSettings Calls @func for each key-value pair of @settings. a #GtkPrintSettings the function to call user data for @func Looks up the string value associated with @key. the string value for @key a #GtkPrintSettings a key Returns the boolean represented by the value that is associated with @key. The string “true” represents %TRUE, any other string %FALSE. %TRUE, if @key maps to a true value. a #GtkPrintSettings a key Gets the value of %GTK_PRINT_SETTINGS_COLLATE. whether to collate the printed pages a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. the default source a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_DITHER. the dithering that is used a #GtkPrintSettings Returns the double value associated with @key, or 0. the double value of @key a #GtkPrintSettings a key 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(). the floating point number associated with @key a #GtkPrintSettings a key the default value Gets the value of %GTK_PRINT_SETTINGS_DUPLEX. whether to print the output in duplex. a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS. the finishings a #GtkPrintSettings Returns the integer value of @key, or 0. the integer value of @key a #GtkPrintSettings a key Returns the value of @key, interpreted as an integer, or the default value. the integer value of @key a #GtkPrintSettings a key the default value Returns the value associated with @key, interpreted as a length. The returned value is converted to @units. the length value of @key, converted to @unit a #GtkPrintSettings a key the unit of the return value Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. the media type a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_N_COPIES. the number of copies to print a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. the number of pages per sheet a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. layout of page in number-up mode a #GtkPrintSettings Get the value of %GTK_PRINT_SETTINGS_ORIENTATION, converted to a #GtkPageOrientation. the orientation a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. the output bin a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. an array of #GtkPageRanges. Use g_free() to free the array when it is no longer needed. a #GtkPrintSettings return location for the length of the returned array Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET. the set of pages to print a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT, converted to @unit. the paper height, in units of @unit a #GtkPrintSettings the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, converted to a #GtkPaperSize. the paper size a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH, converted to @unit. the paper width, in units of @unit a #GtkPrintSettings the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. which pages to print a #GtkPrintSettings Convenience function to obtain the value of %GTK_PRINT_SETTINGS_PRINTER. the printer name a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. the resolution in lpi (lines per inch) a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_QUALITY. the print quality a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION. the resolution in dpi a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X. the horizontal resolution in dpi a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y. the vertical resolution in dpi a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_REVERSE. whether to reverse the order of the printed pages a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_SCALE. the scale in percent a #GtkPrintSettings Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR. whether to use color a #GtkPrintSettings Returns %TRUE, if a value is associated with @key. %TRUE, if @key has a value a #GtkPrintSettings a key Reads the print settings from @file_name. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. See gtk_print_settings_to_file(). %TRUE on success a #GtkPrintSettings the filename to read the settings from 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 #GFileError or #GKeyFileError. %TRUE on success a #GtkPrintSettings the #GKeyFile to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Associates @value with @key. a #GtkPrintSettings a key a string value, or %NULL Sets @key to a boolean value. a #GtkPrintSettings a key a boolean Sets the value of %GTK_PRINT_SETTINGS_COLLATE. a #GtkPrintSettings whether to collate the output Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. a #GtkPrintSettings the default source Sets the value of %GTK_PRINT_SETTINGS_DITHER. a #GtkPrintSettings the dithering that is used Sets @key to a double value. a #GtkPrintSettings a key a double value Sets the value of %GTK_PRINT_SETTINGS_DUPLEX. a #GtkPrintSettings a #GtkPrintDuplex value Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS. a #GtkPrintSettings the finishings Sets @key to an integer value. a #GtkPrintSettings a key an integer Associates a length in units of @unit with @key. a #GtkPrintSettings a key a length the unit of @length Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. a #GtkPrintSettings the media type Sets the value of %GTK_PRINT_SETTINGS_N_COPIES. a #GtkPrintSettings the number of copies Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. a #GtkPrintSettings the number of pages per sheet Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. a #GtkPrintSettings a #GtkNumberUpLayout value Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION. a #GtkPrintSettings a page orientation Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. a #GtkPrintSettings the output bin Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. a #GtkPrintSettings an array of #GtkPageRanges the length of @page_ranges Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET. a #GtkPrintSettings a #GtkPageSet value Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a #GtkPrintSettings the paper height the units of @height Sets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, %GTK_PRINT_SETTINGS_PAPER_WIDTH and %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a #GtkPrintSettings a paper size Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH. a #GtkPrintSettings the paper width the units of @width Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. a #GtkPrintSettings a #GtkPrintPages value Convenience function to set %GTK_PRINT_SETTINGS_PRINTER to @printer. a #GtkPrintSettings the printer name Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. a #GtkPrintSettings the resolution in lpi (lines per inch) Sets the value of %GTK_PRINT_SETTINGS_QUALITY. a #GtkPrintSettings a #GtkPrintQuality value Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a #GtkPrintSettings the resolution in dpi Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a #GtkPrintSettings the horizontal resolution in dpi the vertical resolution in dpi Sets the value of %GTK_PRINT_SETTINGS_REVERSE. a #GtkPrintSettings whether to reverse the output Sets the value of %GTK_PRINT_SETTINGS_SCALE. a #GtkPrintSettings the scale in percent Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR. a #GtkPrintSettings whether to use color This function saves the print settings from @settings to @file_name. If the file could not be loaded then error is set to either a #GFileError or #GKeyFileError. %TRUE on success a #GtkPrintSettings the file to save to Serialize print settings to an a{sv} variant. a new, floating, #GVariant a #GtkPrintSettings This function adds the print settings from @settings to @key_file. a #GtkPrintSettings the #GKeyFile to save the print settings to the group to add the settings to in @key_file, or %NULL to use the default “Print Settings” Removes any value associated with @key. This has the same effect as setting the value to %NULL. a #GtkPrintSettings a key The status gives a rough indication of the completion of a running print operation. The printing has not started yet; this status is set initially, and while the print dialog is shown. This status is set while the begin-print signal is emitted and during pagination. This status is set while the pages are being rendered. The print job is being sent off to the printer. The print job has been sent to the printer, but is not printed for some reason, e.g. the printer may be stopped. Some problem has occurred during printing, e.g. a paper jam. The printer is processing the print job. The printing has been completed successfully. The printing has been aborted. The #GtkProgressBar is typically used to display the progress of a long running operation. It provides a visual clue that processing is underway. The GtkProgressBar 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 GtkProgressBar 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 gtk_progress_bar_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 #GtkProgressBar 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 gtk_progress_bar_pulse() periodically to update the progress bar. There is quite a bit of flexibility provided to control the appearance of the #GtkProgressBar. 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 |[<!-- language="plain" --> progressbar[.osd] ├── [text] ╰── trough[.empty][.full] ╰── progress[.pulse] ]| GtkProgressBar 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 GtkProgressBar. The .osd class on the progressbar node is for use in overlays like the one Epiphany has for page loading progress. Creates a new #GtkProgressBar. a #GtkProgressBar. Returns the ellipsizing position of the progress bar. See gtk_progress_bar_set_ellipsize(). #PangoEllipsizeMode a #GtkProgressBar Returns the current fraction of the task that’s been completed. a fraction from 0.0 to 1.0 a #GtkProgressBar Gets the value set by gtk_progress_bar_set_inverted(). %TRUE if the progress bar is inverted a #GtkProgressBar Retrieves the pulse step set with gtk_progress_bar_set_pulse_step(). a fraction from 0.0 to 1.0 a #GtkProgressBar Gets the value of the #GtkProgressBar:show-text property. See gtk_progress_bar_set_show_text(). %TRUE if text is shown in the progress bar a #GtkProgressBar Retrieves the text that is displayed with the progress bar, if any, otherwise %NULL. 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. text, or %NULL; this string is owned by the widget and should not be modified or freed. a #GtkProgressBar 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 gtk_progress_bar_pulse() causes the block to move by a little bit (the amount of movement per pulse is determined by gtk_progress_bar_set_pulse_step()). a #GtkProgressBar Sets the mode used to ellipsize (add an ellipsis: "...") the text if there is not enough space to render the entire string. a #GtkProgressBar a #PangoEllipsizeMode Causes the progress bar to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a #GtkProgressBar fraction of the task that’s been completed Progress bars normally grow from top to bottom or left to right. Inverted progress bars grow in the opposite direction. a #GtkProgressBar %TRUE to invert the progress bar Sets the fraction of total progress bar length to move the bouncing block for each call to gtk_progress_bar_pulse(). a #GtkProgressBar fraction between 0.0 and 1.0 Sets whether the progress bar will show text next to the bar. The shown text is either the value of the #GtkProgressBar:text property or, if that is %NULL, the #GtkProgressBar: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 #GtkProgressBar:show-text to %TRUE and #GtkProgressBar:text to the empty string (not %NULL). a #GtkProgressBar whether to show text Causes the given @text to appear next to the progress bar. If @text is %NULL and #GtkProgressBar:show-text is %TRUE, the current value of #GtkProgressBar:fraction will be displayed as a percentage. If @text is non-%NULL and #GtkProgressBar: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 #GtkProgressBar:show-text is %TRUE. a #GtkProgressBar a UTF-8 string, or %NULL The preferred place to ellipsize the string, if the progress bar does not have enough room to display the entire string, specified as a #PangoEllipsizeMode. Note that setting this property to a value other than %PANGO_ELLIPSIZE_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 gtk_widget_set_size_request(). Sets whether the progress bar will show a text in addition to the bar itself. The shown text is either the value of the #GtkProgressBar:text property or, if that is %NULL, the #GtkProgressBar: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 #GtkProgressBar:show-text to %TRUE and #GtkProgressBar:text to the empty string (not %NULL). Describes the stage at which events are fed into a #GtkEventController. Events are not delivered automatically. Those can be manually fed through gtk_event_controller_handle_event(). This should only be used when full control about when, or whether the controller handles the event is needed. 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. 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. 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. A #GtkRadioAction is similar to #GtkRadioMenuItem. A number of radio actions can be linked together so that only one may be active at any one time. Creates a new #GtkRadioAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). a new #GtkRadioAction A unique name for the action The label displayed in menu items and on buttons, or %NULL A tooltip for this action, or %NULL The stock icon to display in widgets representing this action, or %NULL The value which gtk_radio_action_get_current_value() should return if this action is selected. Obtains the value property of the currently active member of the group to which @action belongs. The value of the currently active group member a #GtkRadioAction Returns the list representing the radio group for this object. Note that the returned list is only valid until the next change to the group. A common way to set up a group of radio group is the following: |[<!-- language="C" --> GSList *group = NULL; GtkRadioAction *action; while ( ...more actions to add... /) { action = gtk_radio_action_new (...); gtk_radio_action_set_group (action, group); group = gtk_radio_action_get_group (action); } ]| the list representing the radio group for this object the action object Joins a radio action object to the group of another radio action object. Use this in language bindings instead of the gtk_radio_action_get_group() and gtk_radio_action_set_group() methods A common way to set up a group of radio actions is the following: |[<!-- language="C" --> GtkRadioAction *action; GtkRadioAction *last_action; while ( ...more actions to add... /) { action = gtk_radio_action_new (...); gtk_radio_action_join_group (action, last_action); last_action = action; } ]| the action object a radio action object whos group we are joining, or %NULL to remove the radio action from its group Sets the currently active group member to the member with value property @current_value. a #GtkRadioAction the new value Sets the radio group for the radio action object. the action object a list representing a radio group, or %NULL The value property of the currently active member of the group to which this action belongs. Sets a new group for a radio action. The value is an arbitrary integer which can be used as a convenient way to determine which action in the group is currently active in an ::activate or ::changed signal handler. See gtk_radio_action_get_current_value() and #GtkRadioActionEntry for convenient ways to get and set this property. The ::changed signal is emitted on every member of a radio group when the active member is changed. The signal gets emitted after the ::activate signals for the previous and current active members. the member of @action's group which has just been activated #GtkRadioActionEntry structs are used with gtk_action_group_add_radio_actions() to construct groups of radio actions. The name of the action. The stock id for the action, or the name of an icon from the icon theme. The label for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The accelerator for the action, in the format understood by gtk_accelerator_parse(). The tooltip for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The value to set on the radio action. See gtk_radio_action_get_current_value(). A single radio button performs the same basic function as a #GtkCheckButton, 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 #GtkRadioButton is one way of giving the user a choice from many options. Radio button widgets are created with gtk_radio_button_new(), passing %NULL 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, gtk_radio_button_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 gtk_radio_button_new_from_widget() with a #GtkRadioButton that already has a group assigned to it. The convenience function gtk_radio_button_new_with_label_from_widget() is also provided. To retrieve the group a #GtkRadioButton is assigned to, use gtk_radio_button_get_group(). To remove a #GtkRadioButton from one group and make it part of a new one, use gtk_radio_button_set_group(). The group list does not need to be freed, as each #GtkRadioButton will remove itself and its list item when it is destroyed. # CSS nodes |[<!-- language="plain" --> radiobutton ├── radio ╰── <child> ]| A GtkRadioButton with indicator (see gtk_toggle_button_set_mode()) has a main CSS node with name radiobutton and a subnode with name radio. |[<!-- language="plain" --> button.radio ├── radio ╰── <child> ]| A GtkRadioButton 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. |[<!-- language="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 #GtkToggleButton::toggled signal, as does the previously selected button. Inside the #GtkToggleButton::toggled handler, gtk_toggle_button_get_active() can be used to determine if the button has been selected or deselected. Creates a new #GtkRadioButton. To be of any practical value, a widget should then be packed into the radio button. a new radio button an existing radio button group, or %NULL if you are creating a new group. Creates a new #GtkRadioButton, adding it to the same group as @radio_group_member. As with gtk_radio_button_new(), a widget should be packed into the radio button. a new radio button. an existing #GtkRadioButton. Creates a new #GtkRadioButton with a text label. a new radio button. an existing radio button group, or %NULL if you are creating a new group. the text label to display next to the radio button. Creates a new #GtkRadioButton with a text label, adding it to the same group as @radio_group_member. a new radio button. widget to get radio group from or %NULL a text string to display next to the radio button. Creates a new #GtkRadioButton containing a label, adding it to the same group as @group. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the button. a new #GtkRadioButton the radio button group, or %NULL the text of the button, with an underscore in front of the mnemonic character Creates a new #GtkRadioButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the button. a new #GtkRadioButton widget to get radio group from or %NULL the text of the button, with an underscore in front of the mnemonic character Retrieves the group assigned to a radio button. a linked list containing all the radio buttons in the same group as @radio_button. The returned list is owned by the radio button and must not be modified or freed. a #GtkRadioButton. Joins a #GtkRadioButton object to the group of another #GtkRadioButton object Use this in language bindings instead of the gtk_radio_button_get_group() and gtk_radio_button_set_group() methods A common way to set up a group of radio buttons is the following: |[<!-- language="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; } ]| the #GtkRadioButton object a radio button object whos group we are joining, or %NULL to remove the radio button from its group Sets a #GtkRadioButton’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. a #GtkRadioButton. an existing radio button group, such as one returned from gtk_radio_button_get_group(), or %NULL. Sets a new group for a radio button. 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. 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 #GtkRadioMenuItem 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. |[<!-- language="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 |[<!-- language="plain" --> menuitem ├── radio.left ╰── <child> ]| GtkRadioMenuItem has a main CSS node with name menuitem, and a subnode with name radio, which gets the .left or .right style class. Creates a new #GtkRadioMenuItem. a new #GtkRadioMenuItem the group to which the radio menu item is to be attached, or %NULL Creates a new #GtkRadioMenuItem adding it to the same group as @group. The new #GtkRadioMenuItem An existing #GtkRadioMenuItem Creates a new #GtkRadioMenuItem whose child is a simple #GtkLabel. A new #GtkRadioMenuItem group the radio menu item is inside, or %NULL the text for the label Creates a new GtkRadioMenuItem whose child is a simple GtkLabel. The new #GtkRadioMenuItem is added to the same group as @group. The new #GtkRadioMenuItem an existing #GtkRadioMenuItem the text for the label Creates a new #GtkRadioMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the menu item. a new #GtkRadioMenuItem group the radio menu item is inside, or %NULL the text of the button, with an underscore in front of the mnemonic character Creates a new GtkRadioMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the mnemonic for the menu item. The new #GtkRadioMenuItem is added to the same group as @group. The new #GtkRadioMenuItem An existing #GtkRadioMenuItem the text of the button, with an underscore in front of the mnemonic character Returns the group to which the radio menu item belongs, as a #GList of #GtkRadioMenuItem. The list belongs to GTK+ and should not be freed. the group of @radio_menu_item a #GtkRadioMenuItem Joins a #GtkRadioMenuItem object to the group of another #GtkRadioMenuItem object. This function should be used by language bindings to avoid the memory manangement of the opaque #GSList of gtk_radio_menu_item_get_group() and gtk_radio_menu_item_set_group(). A common way to set up a group of #GtkRadioMenuItem instances is: |[ 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; } ]| a #GtkRadioMenuItem a #GtkRadioMenuItem whose group we are joining, or %NULL to remove the @radio_menu_item from its current group Sets the group of a radio menu item, or changes it. a #GtkRadioMenuItem. the new group, or %NULL. The radio menu item whose group this widget belongs to. A #GtkRadioToolButton is a #GtkToolItem 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 gtk_radio_tool_button_new() to create a new GtkRadioToolButton. Use gtk_radio_tool_button_new_from_widget() to create a new GtkRadioToolButton that is part of the same group as an existing GtkRadioToolButton. # CSS nodes GtkRadioToolButton has a single CSS node with name toolbutton. Creates a new #GtkRadioToolButton, adding it to @group. The new #GtkRadioToolButton An existing radio button group, or %NULL if you are creating a new group Creates a new #GtkRadioToolButton, adding it to @group. The new #GtkRadioToolButton will contain an icon and label from the stock item indicated by @stock_id. Use gtk_radio_tool_button_new() instead. The new #GtkRadioToolButton an existing radio button group, or %NULL if you are creating a new group the name of a stock item Creates a new #GtkRadioToolButton adding it to the same group as @gruup The new #GtkRadioToolButton An existing #GtkRadioToolButton, or %NULL Creates a new #GtkRadioToolButton adding it to the same group as @group. The new #GtkRadioToolButton will contain an icon and label from the stock item indicated by @stock_id. gtk_radio_tool_button_new_from_widget A new #GtkRadioToolButton An existing #GtkRadioToolButton. the name of a stock item Returns the radio button group @button belongs to. The group @button belongs to. a #GtkRadioToolButton Adds @button to @group, removing it from the group it belonged to before. a #GtkRadioToolButton an existing radio button group, or %NULL Sets a new group for a radio tool button. #GtkRange is the common base class for widgets which visualize an adjustment, e.g #GtkScale or #GtkScrollbar. Apart from signals for monitoring the parameters of the adjustment, #GtkRange 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 gtk_range_set_fill_level(). Get the #GtkAdjustment which is the “model” object for #GtkRange. See gtk_range_set_adjustment() for details. The return value does not have a reference added, so should not be unreferenced. a #GtkAdjustment a #GtkRange Gets the current position of the fill level indicator. The current fill level A #GtkRange Gets the value set by gtk_range_set_flippable(). %TRUE if the range is flippable a #GtkRange Gets the value set by gtk_range_set_inverted(). %TRUE if the range is inverted a #GtkRange Gets the sensitivity policy for the stepper that points to the 'lower' end of the GtkRange’s adjustment. The lower stepper’s sensitivity policy. a #GtkRange This function is useful mainly for #GtkRange subclasses. See gtk_range_set_min_slider_size(). Use the min-height/min-width CSS properties on the slider node. The minimum size of the range’s slider. a #GtkRange This function returns the area that contains the range’s trough and its steppers, in widget->window coordinates. This function is useful mainly for #GtkRange subclasses. a #GtkRange return location for the range rectangle Gets whether the range is restricted to the fill level. %TRUE if @range is restricted to the fill level. A #GtkRange Gets the number of digits to round the value to when it changes. See #GtkRange::change-value. the number of digits to round to a #GtkRange Gets whether the range displays the fill level graphically. %TRUE if @range shows the fill level. A #GtkRange This function returns sliders range along the long dimension, in widget->window coordinates. This function is useful mainly for #GtkRange subclasses. a #GtkRange return location for the slider's start, or %NULL return location for the slider's end, or %NULL This function is useful mainly for #GtkRange subclasses. See gtk_range_set_slider_size_fixed(). whether the range’s slider has a fixed size. a #GtkRange Gets the sensitivity policy for the stepper that points to the 'upper' end of the GtkRange’s adjustment. The upper stepper’s sensitivity policy. a #GtkRange Gets the current value of the range. current value of the range. a #GtkRange 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 #GtkScale and nonzero for #GtkScrollbar, and indicates the size of the visible area of the widget being scrolled. The page size affects the size of the scrollbar slider. a #GtkRange a #GtkAdjustment 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 gtk_range_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 gtk_range_set_restrict_to_fill_level() and is by default enabled. a #GtkRange the new position of the fill level indicator If a range is flippable, it will switch its direction if it is horizontal and its direction is %GTK_TEXT_DIR_RTL. See gtk_widget_get_direction(). a #GtkRange %TRUE to make the range flippable Sets the step and page sizes for the range. The step size is used when the user clicks the #GtkScrollbar arrows or moves #GtkScale via arrow keys. The page size is used for example when moving via Page Up or Page Down keys. a #GtkRange step size page size 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. a #GtkRange %TRUE to invert the range Sets the sensitivity policy for the stepper that points to the 'lower' end of the GtkRange’s adjustment. a #GtkRange the lower stepper’s sensitivity policy. Sets the minimum size of the range’s slider. This function is useful mainly for #GtkRange subclasses. Use the min-height/min-width CSS properties on the slider node. a #GtkRange The slider’s minimum size Sets the allowable values in the #GtkRange, 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.) a #GtkRange minimum range value maximum range value Sets whether the slider is restricted to the fill level. See gtk_range_set_fill_level() for a general description of the fill level concept. A #GtkRange Whether the fill level restricts slider movement. Sets the number of digits to round the value to when it changes. See #GtkRange::change-value. a #GtkRange the precision in digits, or -1 Sets whether a graphical fill level is show on the trough. See gtk_range_set_fill_level() for a general description of the fill level concept. A #GtkRange Whether a fill level indicator graphics is shown. 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 #GtkRange subclasses. a #GtkRange %TRUE to make the slider size constant Sets the sensitivity policy for the stepper that points to the 'upper' end of the GtkRange’s adjustment. a #GtkRange the upper stepper’s sensitivity policy. 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 #GtkRange::value-changed signal if the value changes. a #GtkRange new value of the range The fill level (e.g. prebuffering of a network stream). See gtk_range_set_fill_level(). The restrict-to-fill-level property controls whether slider movement is restricted to an upper boundary set by the fill level. See gtk_range_set_restrict_to_fill_level(). The number of digits to round the value to when it changes, or -1. See #GtkRange::change-value. The show-fill-level property controls whether fill level indicator graphics are displayed on the trough. See gtk_range_set_show_fill_level(). Emitted before clamping a value, to give the application a chance to adjust the bounds. the value before we clamp The #GtkRange::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 GtkRange::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 #GtkRange:round-digits. %TRUE to prevent other handlers from being invoked for the signal, %FALSE to propagate the signal further the type of scroll action that was performed the new value resulting from the scroll action Virtual function that moves the slider. Used for keybindings. how to move the slider Emitted when the range value changes. Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated quark-ified type identifier quark-ified property identifier like “GtkScrollbar::spacing” field similar to one found in #GtkSettingsValue field similar to one found in #GtkSettingsValue A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses borders in the form `"{ left, right, top, bottom }"` for integers left, right, top and bottom. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkBorder. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a color given either by its name or in the form `{ red, green, blue }` where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GdkColor. a #GParamSpec the #GString to be parsed a #GValue which must hold #GdkColor values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a single enumeration value. The enumeration value can be specified by its name, its nickname or its numeric value. For consistency with flags parsing, the value may be surrounded by parentheses. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GEnumValue. a #GParamSpec the #GString to be parsed a #GValue which must hold enum values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses flags. Flags can be specified by their name, their nickname or numerically. Multiple flags can be specified in the form `"( flag1 | flag2 | ... )"`. %TRUE if @gstring could be parsed and @property_value has been set to the resulting flags value. a #GParamSpec the #GString to be parsed a #GValue which must hold flags values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a requisition in the form `"{ width, height }"` for integers %width and %height. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkRequisition. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. The #GtkRcStyle-struct is used to represent a set of information about the appearance of a widget. This can later be composited together with other #GtkRcStyle-struct<!-- -->s to form a #GtkStyle. Creates a new #GtkRcStyle with no fields set and a reference count of 1. Use #GtkCssProvider instead. the newly-created #GtkRcStyle Makes a copy of the specified #GtkRcStyle. This function will correctly copy an RC style that is a member of a class derived from #GtkRcStyle. Use #GtkCssProvider instead. the resulting #GtkRcStyle the style to copy Name Pixmap name A #PangoFontDescription #GtkRcFlags Foreground colors Background colors Text colors Base colors X thickness Y thickness The parent class. The #GtkRcTokenType enumeration represents the tokens in the RC file. It is exposed so that theme engines can reuse these tokens when parsing the theme-engine specific portions of a RC file. Use #GtkCssProvider instead. Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated Deprecated A #GtkRecentAction represents a list of recently used files, which can be shown by widgets such as #GtkRecentChooserDialog or #GtkRecentChooserMenu. To construct a submenu showing recently used files, use a #GtkRecentAction as the action for a <menuitem>. To construct a menu toolbutton showing the recently used files in the popup menu, use a #GtkRecentAction as the action for a <toolitem> element. Creates a new #GtkRecentAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). the newly created #GtkRecentAction. a unique name for the action the label displayed in menu items and on buttons, or %NULL a tooltip for the action, or %NULL the stock icon to display in widgets representing the action, or %NULL Creates a new #GtkRecentAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). the newly created #GtkRecentAction a unique name for the action the label displayed in menu items and on buttons, or %NULL a tooltip for the action, or %NULL the stock icon to display in widgets representing the action, or %NULL a #GtkRecentManager, or %NULL for using the default #GtkRecentManager Returns the value set by gtk_recent_chooser_menu_set_show_numbers(). %TRUE if numbers should be shown. a #GtkRecentAction Sets whether a number should be added to the items shown by the widgets representing @action. The numbers are shown to provide a unique character for a mnemonic to be used inside the menu item's label. Only the first ten items get a number to avoid clashes. a #GtkRecentAction %TRUE if the shown items should be numbered Whether the items should be displayed with a number. #GtkRecentChooser 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 #GtkRecentChooserWidget, #GtkRecentChooserDialog and #GtkRecentChooserMenu. Recently used files are supported since GTK+ 2.10. Adds @filter to the list of #GtkRecentFilter objects held by @chooser. If no previous filter objects were defined, this function will call gtk_recent_chooser_set_filter(). a #GtkRecentChooser a #GtkRecentFilter Gets the URI currently selected by @chooser. a newly allocated string holding a URI. a #GtkRecentChooser Gets the list of recently used resources in form of #GtkRecentInfo objects. The return value of this function is affected by the “sort-type” and “limit” properties of @chooser. A newly allocated list of #GtkRecentInfo objects. You should use gtk_recent_info_unref() on every item of the list, and then free the list itself using g_list_free(). a #GtkRecentChooser Gets the #GtkRecentFilter objects held by @chooser. A singly linked list of #GtkRecentFilter objects. You should just free the returned list using g_slist_free(). a #GtkRecentChooser Removes @filter from the list of #GtkRecentFilter objects held by @chooser. a #GtkRecentChooser a #GtkRecentFilter Selects all the items inside @chooser, if the @chooser supports multiple selection. a #GtkRecentChooser Selects @uri inside @chooser. %TRUE if @uri was found. a #GtkRecentChooser a URI Sets @uri as the current URI for @chooser. %TRUE if the URI was found. a #GtkRecentChooser a URI Sets the comparison function used when sorting to be @sort_func. If the @chooser has the sort type set to #GTK_RECENT_SORT_CUSTOM then the chooser will sort using this function. To the comparison function will be passed two #GtkRecentInfo 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. a #GtkRecentChooser the comparison function user data to pass to @sort_func, or %NULL destroy notifier for @sort_data, or %NULL Unselects all the items inside @chooser. a #GtkRecentChooser Unselects @uri inside @chooser. a #GtkRecentChooser a URI Adds @filter to the list of #GtkRecentFilter objects held by @chooser. If no previous filter objects were defined, this function will call gtk_recent_chooser_set_filter(). a #GtkRecentChooser a #GtkRecentFilter Gets the #GtkRecentInfo currently selected by @chooser. a #GtkRecentInfo. Use gtk_recent_info_unref() when when you have finished using it. a #GtkRecentChooser Gets the URI currently selected by @chooser. a newly allocated string holding a URI. a #GtkRecentChooser Gets the #GtkRecentFilter object currently used by @chooser to affect the display of the recently used resources. a #GtkRecentFilter object. a #GtkRecentChooser Gets the list of recently used resources in form of #GtkRecentInfo objects. The return value of this function is affected by the “sort-type” and “limit” properties of @chooser. A newly allocated list of #GtkRecentInfo objects. You should use gtk_recent_info_unref() on every item of the list, and then free the list itself using g_list_free(). a #GtkRecentChooser Gets the number of items returned by gtk_recent_chooser_get_items() and gtk_recent_chooser_get_uris(). A positive integer, or -1 meaning that all items are returned. a #GtkRecentChooser Gets whether only local resources should be shown in the recently used resources selector. See gtk_recent_chooser_set_local_only() %TRUE if only local resources should be shown. a #GtkRecentChooser Gets whether @chooser can select multiple items. %TRUE if @chooser can select more than one item. a #GtkRecentChooser Retrieves whether @chooser should show an icon near the resource. %TRUE if the icons should be displayed, %FALSE otherwise. a #GtkRecentChooser Retrieves whether @chooser should show the recently used resources that were not found. %TRUE if the resources not found should be displayed, and %FALSE otheriwse. a #GtkRecentChooser Returns whether @chooser should display recently used resources registered as private. %TRUE if the recent chooser should show private items, %FALSE otherwise. a #GtkRecentChooser Gets whether @chooser should display tooltips containing the full path of a recently user resource. %TRUE if the recent chooser should show tooltips, %FALSE otherwise. a #GtkRecentChooser Gets the value set by gtk_recent_chooser_set_sort_type(). the sorting order of the @chooser. a #GtkRecentChooser Gets the URI of the recently used resources. The return value of this function is affected by the “sort-type” and “limit” properties of @chooser. Since the returned array is %NULL terminated, @length may be %NULL. A newly allocated, %NULL-terminated array of strings. Use g_strfreev() to free it. a #GtkRecentChooser return location for a the length of the URI list, or %NULL Gets the #GtkRecentFilter objects held by @chooser. A singly linked list of #GtkRecentFilter objects. You should just free the returned list using g_slist_free(). a #GtkRecentChooser Removes @filter from the list of #GtkRecentFilter objects held by @chooser. a #GtkRecentChooser a #GtkRecentFilter Selects all the items inside @chooser, if the @chooser supports multiple selection. a #GtkRecentChooser Selects @uri inside @chooser. %TRUE if @uri was found. a #GtkRecentChooser a URI Sets @uri as the current URI for @chooser. %TRUE if the URI was found. a #GtkRecentChooser a URI Sets @filter as the current #GtkRecentFilter object used by @chooser to affect the displayed recently used resources. a #GtkRecentChooser a #GtkRecentFilter Sets the number of items that should be returned by gtk_recent_chooser_get_items() and gtk_recent_chooser_get_uris(). a #GtkRecentChooser a positive integer, or -1 for all items 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. a #GtkRecentChooser %TRUE if only local files can be shown Sets whether @chooser can select multiple items. a #GtkRecentChooser %TRUE if @chooser can select more than one item Sets whether @chooser should show an icon near the resource when displaying it. a #GtkRecentChooser whether to show an icon near the resource Sets whether @chooser should display the recently used resources that it didn’t find. This only applies to local resources. a #GtkRecentChooser whether to show the local items we didn’t find Whether to show recently used resources marked registered as private. a #GtkRecentChooser %TRUE to show private items, %FALSE otherwise Sets whether to show a tooltips containing the full path of each recently used resource in a #GtkRecentChooser widget. a #GtkRecentChooser %TRUE if tooltips should be shown Sets the comparison function used when sorting to be @sort_func. If the @chooser has the sort type set to #GTK_RECENT_SORT_CUSTOM then the chooser will sort using this function. To the comparison function will be passed two #GtkRecentInfo 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. a #GtkRecentChooser the comparison function user data to pass to @sort_func, or %NULL destroy notifier for @sort_data, or %NULL Changes the sorting order of the recently used resources list displayed by @chooser. a #GtkRecentChooser sort order that the chooser should use Unselects all the items inside @chooser. a #GtkRecentChooser Unselects @uri inside @chooser. a #GtkRecentChooser a URI The #GtkRecentFilter object to be used when displaying the recently used resources. The maximum number of recently used resources to be displayed, or -1 to display all items. Whether this #GtkRecentChooser should display only local (file:) resources. The #GtkRecentManager instance used by the #GtkRecentChooser to display the list of recently used resources. Allow the user to select multiple resources. Whether this #GtkRecentChooser should display an icon near the item. Whether this #GtkRecentChooser 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). Whether this #GtkRecentChooser should display a tooltip containing the full path of the recently used resources. Sorting order to be used when displaying the recently used resources. 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`. 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. #GtkRecentChooserDialog is a dialog box suitable for displaying the recently used documents. This widgets works by putting a #GtkRecentChooserWidget inside a #GtkDialog. It exposes the #GtkRecentChooserIface interface, so you can use all the #GtkRecentChooser functions on the recent chooser dialog as well as those for #GtkDialog. Note that #GtkRecentChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a #GtkRecentChooser. ## Typical usage ## {#gtkrecentchooser-typical-usage} In the simplest of cases, you can use the following code to use a #GtkRecentChooserDialog to select a recently used file: |[<!-- language="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. Creates a new #GtkRecentChooserDialog. This function is analogous to gtk_dialog_new_with_buttons(). a new #GtkRecentChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL, stock ID or text to go in the first button, or %NULL response ID for the first button, then additional (button, id) pairs, ending with %NULL Creates a new #GtkRecentChooserDialog 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 #GtkRecentManager object. a new #GtkRecentChooserDialog Title of the dialog, or %NULL Transient parent of the dialog, or %NULL, a #GtkRecentManager stock ID or text to go in the first button, or %NULL response ID for the first button, then additional (button, id) pairs, ending with %NULL These identify the various errors that can occur while calling #GtkRecentChooser functions. Indicates that a file does not exist Indicates a malformed URI %TRUE if the URI was found. a #GtkRecentChooser a URI a newly allocated string holding a URI. a #GtkRecentChooser %TRUE if @uri was found. a #GtkRecentChooser a URI a #GtkRecentChooser a URI a #GtkRecentChooser a #GtkRecentChooser A newly allocated list of #GtkRecentInfo objects. You should use gtk_recent_info_unref() on every item of the list, and then free the list itself using g_list_free(). a #GtkRecentChooser a #GtkRecentChooser a #GtkRecentFilter a #GtkRecentChooser a #GtkRecentFilter A singly linked list of #GtkRecentFilter objects. You should just free the returned list using g_slist_free(). a #GtkRecentChooser a #GtkRecentChooser the comparison function user data to pass to @sort_func, or %NULL destroy notifier for @sort_data, or %NULL #GtkRecentChooserMenu is a widget suitable for displaying recently used files inside a menu. It can be used to set a sub-menu of a #GtkMenuItem using gtk_menu_item_set_submenu(), or as the menu of a #GtkMenuToolButton. Note that #GtkRecentChooserMenu does not have any methods of its own. Instead, you should use the functions that work on a #GtkRecentChooser. Note also that #GtkRecentChooserMenu does not support multiple filters, as it has no way to let the user choose between them as the #GtkRecentChooserWidget and #GtkRecentChooserDialog widgets do. Thus using gtk_recent_chooser_add_filter() on a #GtkRecentChooserMenu widget will yield the same effects as using gtk_recent_chooser_set_filter(), replacing any currently set filter with the supplied filter; gtk_recent_chooser_remove_filter() will remove any currently set #GtkRecentFilter object and will unset the current filter; gtk_recent_chooser_list_filters() will return a list containing a single #GtkRecentFilter object. Recently used files are supported since GTK+ 2.10. Creates a new #GtkRecentChooserMenu 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 #GtkRecentChooser interface. This widget creates its own #GtkRecentManager object. See the gtk_recent_chooser_menu_new_for_manager() function to know how to create a #GtkRecentChooserMenu widget bound to another #GtkRecentManager object. a new #GtkRecentChooserMenu Creates a new #GtkRecentChooserMenu 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 #GtkRecentManager object or if you wish to share a common #GtkRecentManager object among multiple #GtkRecentChooser widgets. a new #GtkRecentChooserMenu, bound to @manager. a #GtkRecentManager Returns the value set by gtk_recent_chooser_menu_set_show_numbers(). %TRUE if numbers should be shown. a #GtkRecentChooserMenu Sets whether a number should be added to the items of @menu. 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. a #GtkRecentChooserMenu whether to show numbers Whether the first ten items in the menu should be prepended by a number acting as a unique mnemonic. #GtkRecentChooserWidget is a widget suitable for selecting recently used files. It is the main building block of a #GtkRecentChooserDialog. Most applications will only need to use the latter; you can use #GtkRecentChooserWidget as part of a larger window if you have special needs. Note that #GtkRecentChooserWidget does not have any methods of its own. Instead, you should use the functions that work on a #GtkRecentChooser. Recently used files are supported since GTK+ 2.10. Creates a new #GtkRecentChooserWidget object. This is an embeddable widget used to access the recently used resources list. a new #GtkRecentChooserWidget Creates a new #GtkRecentChooserWidget 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 #GtkRecentManager object. a new #GtkRecentChooserWidget a #GtkRecentManager Meta-data to be passed to gtk_recent_manager_add_full() when registering a recently used resource. a UTF-8 encoded string, containing the name of the recently used resource to be displayed, or %NULL; a UTF-8 encoded string, containing a short description of the resource, or %NULL; the MIME type of the resource; the name of the application that is registering this recently used resource; command line used to launch this resource; may contain the “\%f” and “\%u” escape characters which will be expanded to the resource file path and URI respectively when the command line is retrieved; a vector of strings containing groups names; whether this resource should be displayed only by the applications that have registered it or not. A #GtkRecentFilter can be used to restrict the files being shown in a #GtkRecentChooser. Files can be filtered based on their name (with gtk_recent_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), on the application that has registered them (with gtk_recent_filter_add_application()), or by a custom filter function (with gtk_recent_filter_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 #GtkRecentFilter 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 #GtkRecentChooser, see gtk_recent_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_recent_filter_filter(). Recently used files are supported since GTK+ 2.10. ## GtkRecentFilter as GtkBuildable The GtkRecentFilter implementation of the GtkBuildable 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 gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern() or gtk_recent_filter_add_application(). An example of a UI definition fragment specifying GtkRecentFilter rules: |[ <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> ]| Creates a new #GtkRecentFilter 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 gtk_recent_filter_add_pattern(), gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_application(), gtk_recent_filter_add_age(). To create a filter that accepts any recently used resource, use: |[<!-- language="C" --> GtkRecentFilter *filter = gtk_recent_filter_new (); gtk_recent_filter_add_pattern (filter, "*"); ]| a new #GtkRecentFilter Adds a rule that allows resources based on their age - that is, the number of days elapsed since they were last modified. a #GtkRecentFilter number of days Adds a rule that allows resources based on the name of the application that has registered them. a #GtkRecentFilter an application name 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. a #GtkRecentFilter bitfield of flags indicating the information that the custom filter function needs. callback function; if the function returns %TRUE, then the file will be displayed. data to pass to @func function to call to free @data when it is no longer needed. Adds a rule that allows resources based on the name of the group to which they belong a #GtkRecentFilter a group name Adds a rule that allows resources based on their registered MIME type. a #GtkRecentFilter a MIME type Adds a rule that allows resources based on a pattern matching their display name. a #GtkRecentFilter a file pattern Adds a rule allowing image files in the formats supported by GdkPixbuf. a #GtkRecentFilter Tests whether a file should be displayed according to @filter. The #GtkRecentFilterInfo @filter_info should include the fields returned from gtk_recent_filter_get_needed(), and must set the #GtkRecentFilterInfo.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 #GtkRecentChooser. %TRUE if the file should be displayed a #GtkRecentFilter a #GtkRecentFilterInfo containing information about a recently used resource Gets the human-readable name for the filter. See gtk_recent_filter_set_name(). the name of the filter, or %NULL. The returned string is owned by the filter object and should not be freed. a #GtkRecentFilter Gets the fields that need to be filled in for the #GtkRecentFilterInfo passed to gtk_recent_filter_filter() This function will not typically be used by applications; it is intended principally for use in the implementation of #GtkRecentChooser. bitfield of flags indicating needed fields when calling gtk_recent_filter_filter() a #GtkRecentFilter 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. a #GtkRecentFilter then human readable name of @filter These flags indicate what parts of a #GtkRecentFilterInfo struct are filled or need to be filled. the URI of the file being tested the string that will be used to display the file in the recent chooser the mime type of the file the list of applications that have registered the file the groups to which the file belongs to the number of days elapsed since the file has been registered The type of function that is used with custom filters, see gtk_recent_filter_add_custom(). %TRUE if the file should be displayed a #GtkRecentFilterInfo that is filled according to the @needed flags passed to gtk_recent_filter_add_custom() user data passed to gtk_recent_filter_add_custom() A GtkRecentFilterInfo struct is used to pass information about the tested file to gtk_recent_filter_filter(). #GtkRecentFilterFlags to indicate which fields are set. The URI of the file being tested. The string that will be used to display the file in the recent chooser. MIME type of the file. The list of applications that have registered the file. The groups to which the file belongs to. The number of days elapsed since the file has been registered. #GtkRecentInfo-struct contains private data only, and should be accessed using the provided API. #GtkRecentInfo constains all the meta-data associated with an entry in the recently used files list. Creates a #GAppInfo for the specified #GtkRecentInfo the newly created #GAppInfo, or %NULL. In case of error, @error will be set either with a %GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR a #GtkRecentInfo the name of the application that should be mapped to a #GAppInfo; if %NULL is used then the default application for the MIME type is used Checks whether the resource pointed by @info still exists. At the moment this check is done only on resources pointing to local files. %TRUE if the resource exists a #GtkRecentInfo Gets the timestamp (seconds from system’s Epoch) when the resource was added to the recently used resources list. the number of seconds elapsed from system’s Epoch when the resource was added to the list, or -1 on failure. a #GtkRecentInfo Gets the number of days elapsed since the last update of the resource pointed by @info. a positive integer containing the number of days elapsed since the time this resource was last modified a #GtkRecentInfo Gets the data regarding the application that has registered the resource pointed by @info. If the command line contains any escape characters defined inside the storage specification, they will be expanded. %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 #GtkRecentInfo and should not be modified or freed a #GtkRecentInfo the name of the application that has registered this item return location for the string containing the command line return location for the number of times this item was registered return location for the timestamp this item was last registered for this application Retrieves the list of applications that have registered this resource. a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. a #GtkRecentInfo return location for the length of the returned list Gets the (short) description of the resource. the description of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Gets the name of the resource. If none has been defined, the basename of the resource is obtained. the display name of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Retrieves the icon associated to the resource MIME type. a #GIcon containing the icon, or %NULL. Use g_object_unref() when finished using the icon a #GtkRecentInfo Returns all groups registered for the recently used item @info. The array of returned group names will be %NULL terminated, so length might optionally be %NULL. a newly allocated %NULL terminated array of strings. Use g_strfreev() to free it. a #GtkRecentInfo return location for the number of groups returned Retrieves the icon of size @size associated to the resource MIME type. a #GdkPixbuf containing the icon, or %NULL. Use g_object_unref() when finished using the icon. a #GtkRecentInfo the size of the icon in pixels Gets the MIME type of the resource. the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo Gets the timestamp (seconds from system’s Epoch) when the meta-data for the resource was last modified. the number of seconds elapsed from system’s Epoch when the resource was last modified, or -1 on failure. a #GtkRecentInfo 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. %TRUE if the private flag was found, %FALSE otherwise a #GtkRecentInfo 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”. A newly-allocated string in UTF-8 encoding free it with g_free() an #GtkRecentInfo Gets the URI of the resource. the URI of the resource. The returned string is owned by the recent manager, and should not be freed. a #GtkRecentInfo 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 gtk_recent_info_get_uri(). a newly allocated UTF-8 string containing the resource’s URI or %NULL. Use g_free() when done using it. a #GtkRecentInfo Gets the timestamp (seconds from system’s Epoch) when the meta-data for the resource was last visited. the number of seconds elapsed from system’s Epoch when the resource was last visited, or -1 on failure. a #GtkRecentInfo Checks whether an application registered this resource using @app_name. %TRUE if an application with name @app_name was found, %FALSE otherwise a #GtkRecentInfo a string containing an application name Checks whether @group_name appears inside the groups registered for the recently used item @info. %TRUE if the group was found a #GtkRecentInfo name of a group Checks whether the resource is local or not by looking at the scheme of its URI. %TRUE if the resource is local a #GtkRecentInfo Gets the name of the last application that have registered the recently used resource represented by @info. an application name. Use g_free() to free it. a #GtkRecentInfo Checks whether two #GtkRecentInfo-struct point to the same resource. %TRUE if both #GtkRecentInfo-struct point to the same resource, %FALSE otherwise a #GtkRecentInfo a #GtkRecentInfo Increases the reference count of @recent_info by one. the recent info object with its reference count increased by one a #GtkRecentInfo Decreases the reference count of @info by one. If the reference count reaches zero, @info is deallocated, and the memory freed. a #GtkRecentInfo #GtkRecentManager 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 #GtkRecentManager acts like a database of all the recently used files. You can create new #GtkRecentManager objects, but it is more efficient to use the default manager created by GTK+. Adding a new recently used file is as simple as: |[<!-- language="C" --> GtkRecentManager *manager; manager = gtk_recent_manager_get_default (); gtk_recent_manager_add_item (manager, file_uri); ]| The #GtkRecentManager 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 gtk_recent_manager_lookup_item(): |[<!-- language="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 gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo-structs. A #GtkRecentManager is the model used to populate the contents of one, or more #GtkRecentChooser implementations. Note that the maximum age of the recently used files list is controllable through the #GtkSettings:gtk-recent-files-max-age property. Recently used files are supported since GTK+ 2.10. Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A #GtkRecentManager object monitors the recently used resources list, and emits the “changed” signal each time something inside the list changes. #GtkRecentManager objects are expensive: be sure to create them only when needed. You should use gtk_recent_manager_get_default() instead. A newly created #GtkRecentManager object Gets a unique instance of #GtkRecentManager, that you can share in your application without caring about memory management. A unique #GtkRecentManager. Do not ref or unref it. Adds a new resource, pointed by @uri, into the recently used resources list, using the metadata specified inside the #GtkRecentData-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 #GtkRecentData-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 #GtkRecentData-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. %TRUE if the new item was successfully added to the recently used resources list, %FALSE otherwise a #GtkRecentManager a valid URI metadata of the resource 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 gtk_recent_manager_add_full(). See gtk_recent_manager_add_full() if you want to explicitly define the metadata for the resource pointed by @uri. %TRUE if the new item was successfully added to the recently used resources list a #GtkRecentManager a valid URI Gets the list of recently used resources. a list of newly allocated #GtkRecentInfo objects. Use gtk_recent_info_unref() on each item inside the list, and then free the list itself using g_list_free(). a #GtkRecentManager Checks whether there is a recently used resource registered with @uri inside the recent manager. %TRUE if the resource was found, %FALSE otherwise a #GtkRecentManager a URI Searches for a URI inside the recently used resources list, and returns a #GtkRecentInfo-struct containing informations about the resource like its MIME type, or its display name. a #GtkRecentInfo-struct containing information about the resource pointed by @uri, or %NULL if the URI was not registered in the recently used resources list. Free with gtk_recent_info_unref(). a #GtkRecentManager a URI 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. %TRUE on success a #GtkRecentManager the URI of a recently used resource the new URI of the recently used resource, or %NULL to remove the item pointed by @uri in the list Purges every item from the recently used resources list. the number of items that have been removed from the recently used resources list a #GtkRecentManager Removes a resource pointed by @uri from the recently used resources list handled by a recent manager. %TRUE if the item pointed by @uri has been successfully removed by the recently used resources list, and %FALSE otherwise a #GtkRecentManager the URI of the item you wish to remove The full path to the file to be used to store and read the recently used resources list The size of the recently used resources list. Emitted when the current recently used resources manager changes its contents, either by calling gtk_recent_manager_add_item() or by another application. #GtkRecentManagerClass contains only private data. Error codes for #GtkRecentManager operations the URI specified does not exists in the recently used resources list. the URI specified is not valid. the supplied string is not UTF-8 encoded. no application has registered the specified item. failure while reading the recently used resources file. failure while writing the recently used resources file. unspecified error. Used to specify the sorting method to be applyed to the recently used resource list. Do not sort the returned list of recently used resources. Sort the returned list with the most recently used items first. Sort the returned list with the least recently used items first. Sort the returned list using a custom sorting function passed using gtk_recent_chooser_set_sort_func(). Describes a region within a widget. Region has an even number within a set. Region has an odd number within a set. Region is the first one within a set. Region is the last one within a set. Region is the only one within a set. Region is part of a sorted area. Indicated the relief to be drawn around a #GtkButton. Draw a normal relief. A half relief. Deprecated in 3.14, does the same as @GTK_RELIEF_NORMAL No relief. Represents a request of a screen object in a given orientation. These are primarily used in container implementations when allocating a natural size for children calling. See gtk_distribute_natural_allocation(). A client pointer The minimum size needed for allocation in a given orientation The natural size for allocation in a given orientation A #GtkRequisition-struct represents the desired size of a widget. See [GtkWidget’s geometry management section][geometry-management] for more information. the widget’s desired width the widget’s desired height Allocates a new #GtkRequisition-struct and initializes its elements to zero. a new empty #GtkRequisition. The newly allocated #GtkRequisition should be freed with gtk_requisition_free(). Copies a #GtkRequisition. a copy of @requisition a #GtkRequisition Frees a #GtkRequisition. a #GtkRequisition Pass resize request to the parent Queue resizes on this widget Resize immediately. Deprecated. Predefined values for use as response ids in gtk_dialog_add_button(). All predefined values are negative; GTK+ leaves values of 0 or greater for application-defined response ids. Returned if an action widget has no response id, or if the dialog gets programmatically hidden or destroyed Generic response id, not used by GTK+ dialogs Generic response id, not used by GTK+ dialogs Returned if the dialog is deleted Returned by OK buttons in GTK+ dialogs Returned by Cancel buttons in GTK+ dialogs Returned by Close buttons in GTK+ dialogs Returned by Yes buttons in GTK+ dialogs Returned by No buttons in GTK+ dialogs Returned by Apply buttons in GTK+ dialogs Returned by Help buttons in GTK+ dialogs The GtkRevealer widget is a container which animates the transition of its child from invisible to visible. The style of transition can be controlled with gtk_revealer_set_transition_type(). These animations respect the #GtkSettings:gtk-enable-animations setting. # CSS nodes GtkRevealer has a single CSS node with name revealer. The GtkRevealer widget was added in GTK+ 3.10. Creates a new #GtkRevealer. a newly created #GtkRevealer Returns whether the child is fully revealed, in other words whether the transition to the revealed state is completed. %TRUE if the child is fully revealed a #GtkRevealer Returns whether the child is currently revealed. See gtk_revealer_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 gtk_revealer_get_child_revealed(). %TRUE if the child is revealed. a #GtkRevealer Returns the amount of time (in milliseconds) that transitions will take. the transition duration a #GtkRevealer Gets the type of animation that will be used for transitions in @revealer. the current transition type of @revealer a #GtkRevealer Tells the #GtkRevealer to reveal or conceal its child. The transition will be animated with the current transition type of @revealer. a #GtkRevealer %TRUE to reveal the child Sets the duration that transitions will take. a #GtkRevealer the new duration, in milliseconds Sets the type of animation that will be used for transitions in @revealer. Available types include various kinds of fades and slides. a #GtkRevealer the new transition type The parent class. These enumeration values describe the possible transitions when the child of a #GtkRevealer widget is shown or hidden. No transition Fade in Slide in from the left Slide in from the right Slide in from the bottom Slide in from the top The “About” item.  Use named icon &quot;help-about&quot; or the label &quot;_About&quot;. The “Add” item and icon. Use named icon &quot;list-add&quot; or the label &quot;_Add&quot;. The “Apply” item and icon. Do not use an icon. Use label &quot;_Apply&quot;. The “Bold” item and icon. Use named icon &quot;format-text-bold&quot;. The “Cancel” item and icon. Do not use an icon. Use label &quot;_Cancel&quot;. The “Caps Lock Warning” icon. Use named icon &quot;dialog-warning-symbolic&quot;. The “CD-Rom” item and icon. Use named icon &quot;media-optical&quot;. The “Clear” item and icon. Use named icon &quot;edit-clear&quot;. The “Close” item and icon. Use named icon &quot;window-close&quot; or the label &quot;_Close&quot;. The “Color Picker” item and icon. The “Connect” icon. The “Convert” item and icon. The “Copy” item and icon. Use the named icon &quot;edit-copy&quot; or the label &quot;_Copy&quot;. The “Cut” item and icon. Use the named icon &quot;edit-cut&quot; or the label &quot;Cu_t&quot;. The “Delete” item and icon. Use the named icon &quot;edit-delete&quot; or the label &quot;_Delete&quot;. The “Authentication” item and icon. Use named icon &quot;dialog-password&quot;. The “Error” item and icon. Use named icon &quot;dialog-error&quot;. The “Information” item and icon. Use named icon &quot;dialog-information&quot;. The “Question” item and icon. Use named icon &quot;dialog-question&quot;. The “Warning” item and icon. Use named icon &quot;dialog-warning&quot;. The “Directory” icon. Use named icon &quot;folder&quot;. The “Discard” item. The “Disconnect” icon. The “Drag-And-Drop” icon. The “Drag-And-Drop multiple” icon. The “Edit” item and icon. The “Execute” item and icon. Use named icon &quot;system-run&quot;. The “File” item and icon. Since 3.0, this item has a label, before it only had an icon. Use named icon &quot;text-x-generic&quot;. The “Find” item and icon. Use named icon &quot;edit-find&quot;. The “Find and Replace” item and icon. Use named icon &quot;edit-find-replace&quot;. The “Floppy” item and icon. The “Fullscreen” item and icon. Use named icon &quot;view-fullscreen&quot;. The “Bottom” item and icon. Use named icon &quot;go-bottom&quot;. The “First” item and icon. The icon has an RTL variant. Use named icon &quot;go-first&quot;. The “Last” item and icon. The icon has an RTL variant. Use named icon &quot;go-last&quot;. The “Top” item and icon. Use named icon &quot;go-top&quot;. The “Back” item and icon. The icon has an RTL variant. Use named icon &quot;go-previous&quot;. The “Down” item and icon. Use named icon &quot;go-down&quot;. The “Forward” item and icon. The icon has an RTL variant. Use named icon &quot;go-next&quot;. The “Up” item and icon. Use named icon &quot;go-up&quot;. The “Harddisk” item and icon. Use named icon &quot;drive-harddisk&quot;. The “Help” item and icon. Use named icon &quot;help-browser&quot;. The “Home” item and icon. Use named icon &quot;go-home&quot;. The “Indent” item and icon. The icon has an RTL variant. Use named icon &quot;format-indent-more&quot;. The “Index” item and icon. The “Info” item and icon. Use named icon &quot;dialog-information&quot;. The “Italic” item and icon. Use named icon &quot;format-text-italic&quot;. The “Jump to” item and icon. The icon has an RTL variant. Use named icon &quot;go-jump&quot;. The “Center” item and icon. Use named icon &quot;format-justify-center&quot;. The “Fill” item and icon. Use named icon &quot;format-justify-fill&quot;. The “Left” item and icon. Use named icon &quot;format-justify-left&quot;. The “Right” item and icon. Use named icon &quot;format-justify-right&quot;. The “Leave Fullscreen” item and icon. Use named icon &quot;view-restore&quot;. The “Media Forward” item and icon. The icon has an RTL variant. Use named icon &quot;media-seek-forward&quot; or the label &quot;_Forward&quot;. The “Media Next” item and icon. The icon has an RTL variant. Use named icon &quot;media-skip-forward&quot; or the label &quot;_Next&quot;. The “Media Pause” item and icon. Use named icon &quot;media-playback-pause&quot; or the label &quot;P_ause&quot;. The “Media Play” item and icon. The icon has an RTL variant. Use named icon &quot;media-playback-start&quot; or the label &quot;_Play&quot;. The “Media Previous” item and icon. The icon has an RTL variant. Use named icon &quot;media-skip-backward&quot; or the label &quot;Pre_vious&quot;. The “Media Record” item and icon. Use named icon &quot;media-record&quot; or the label &quot;_Record&quot;. The “Media Rewind” item and icon. The icon has an RTL variant. Use named icon &quot;media-seek-backward&quot; or the label &quot;R_ewind&quot;. The “Media Stop” item and icon. Use named icon &quot;media-playback-stop&quot; or the label &quot;_Stop&quot;. The “Missing image” icon. Use named icon &quot;image-missing&quot;. The “Network” item and icon. Use named icon &quot;network-workgroup&quot;. The “New” item and icon. Use named icon &quot;document-new&quot; or the label &quot;_New&quot;. The “No” item and icon. The “OK” item and icon. Do not use an icon. Use label &quot;_OK&quot;. The “Open” item and icon. Use named icon &quot;document-open&quot; or the label &quot;_Open&quot;. The “Landscape Orientation” item and icon. The “Portrait Orientation” item and icon. The “Reverse Landscape Orientation” item and icon. The “Reverse Portrait Orientation” item and icon. The “Page Setup” item and icon. Use named icon &quot;document-page-setup&quot; or the label &quot;Page Set_up&quot;. The “Paste” item and icon. Use named icon &quot;edit-paste&quot; or the label &quot;_Paste&quot;. The “Preferences” item and icon. Use named icon &quot;preferences-system&quot; or the label &quot;_Preferences&quot;. The “Print” item and icon. Use named icon &quot;document-print&quot; or the label &quot;_Print&quot;. The “Print Error” icon. Use named icon &quot;printer-error&quot;. The “Print Paused” icon. The “Print Preview” item and icon. Use label &quot;Pre_view&quot;. The “Print Report” icon. The “Print Warning” icon. The “Properties” item and icon. Use named icon &quot;document-properties&quot; or the label &quot;_Properties&quot;. The “Quit” item and icon. Use named icon &quot;application-exit&quot; or the label &quot;_Quit&quot;. The “Redo” item and icon. The icon has an RTL variant. Use named icon &quot;edit-redo&quot; or the label &quot;_Redo&quot;. The “Refresh” item and icon. Use named icon &quot;view-refresh&quot; or the label &quot;_Refresh&quot;. The “Remove” item and icon. Use named icon &quot;list-remove&quot; or the label &quot;_Remove&quot;. The “Revert” item and icon. The icon has an RTL variant. Use named icon &quot;document-revert&quot; or the label &quot;_Revert&quot;. The “Save” item and icon. Use named icon &quot;document-save&quot; or the label &quot;_Save&quot;. The “Save As” item and icon. Use named icon &quot;document-save-as&quot; or the label &quot;Save _As&quot;. The “Select All” item and icon. Use named icon &quot;edit-select-all&quot; or the label &quot;Select _All&quot;. The “Color” item and icon. The “Font” item and icon. The “Ascending” item and icon. Use named icon &quot;view-sort-ascending&quot;. The “Descending” item and icon. Use named icon &quot;view-sort-descending&quot;. The “Spell Check” item and icon. Use named icon &quot;tools-check-spelling&quot;. The “Stop” item and icon. Use named icon &quot;process-stop&quot; or the label &quot;_Stop&quot;. The “Strikethrough” item and icon. Use named icon &quot;format-text-strikethrough&quot; or the label &quot;_Strikethrough&quot;. The “Undelete” item and icon. The icon has an RTL variant. The “Underline” item and icon. Use named icon &quot;format-text-underline&quot; or the label &quot;_Underline&quot;. The “Undo” item and icon. The icon has an RTL variant. Use named icon &quot;edit-undo&quot; or the label &quot;_Undo&quot;. The “Unindent” item and icon. The icon has an RTL variant. Use named icon &quot;format-indent-less&quot;. The “Yes” item and icon. The “Zoom 100%” item and icon. Use named icon &quot;zoom-original&quot; or the label &quot;_Normal Size&quot;. The “Zoom to Fit” item and icon. Use named icon &quot;zoom-fit-best&quot; or the label &quot;Best _Fit&quot;. The “Zoom In” item and icon. Use named icon &quot;zoom-in&quot; or the label &quot;Zoom _In&quot;. The “Zoom Out” item and icon. Use named icon &quot;zoom-out&quot; or the label &quot;Zoom _Out&quot;. a #GtkStyle. A CSS class to match an accelerator. Refer to individual widget documentation for used style classes. A CSS class used when rendering an arrow element. Refer to individual widget documentation for used style classes. A CSS class to match the window background. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the bottom of a widget. Refer to individual widget documentation for used style classes. A CSS class to match buttons. Refer to individual widget documentation for used style classes. A CSS class to match calendars. Refer to individual widget documentation for used style classes. A CSS class to match content rendered in cell views. Refer to individual widget documentation for used style classes. A CSS class to match check boxes. Refer to individual widget documentation for used style classes. A CSS class to match combobox entries. Refer to individual widget documentation for used style classes. A CSS class to match context menus. Refer to individual widget documentation for used style classes. A CSS class that gets added to windows which have client-side decorations. Refer to individual widget documentation for used style classes. A CSS class used when rendering a drag handle for text selection. Refer to individual widget documentation for used style classes. A CSS class to match the default widget. Refer to individual widget documentation for used style classes. A CSS class used when an action (usually a button) is one that is expected to remove or destroy something visible to the user. Refer to individual widget documentation for used style classes. A CSS class to match dimmed labels. Refer to individual widget documentation for used style classes. A CSS class for a drag-and-drop indicator. Refer to individual widget documentation for used style classes. A CSS class defining a dock area. Refer to individual widget documentation for used style classes. A CSS class to match text entries. Refer to individual widget documentation for used style classes. A CSS class for an area displaying an error message, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class defining an expander, such as those in treeviews. Refer to individual widget documentation for used style classes. A CSS class that is added when widgets that usually have a frame or border (like buttons or entries) should appear without it. Refer to individual widget documentation for used style classes. A CSS class defining a frame delimiting content, such as #GtkFrame or the scrolled window frame around the scrollable area. Refer to individual widget documentation for used style classes. A CSS class defining a resize grip. Refer to individual widget documentation for used style classes. A CSS class to match a header element. Refer to individual widget documentation for used style classes. A CSS class defining a highlighted area, such as headings in assistants and calendars. Refer to individual widget documentation for used style classes. A CSS class for horizontally layered widgets. Refer to individual widget documentation for used style classes. A CSS class defining an image, such as the icon in an entry. Refer to individual widget documentation for used style classes. A CSS class for an area displaying an informational message, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class to match inline toolbars. Refer to individual widget documentation for used style classes. A CSS class used when rendering a drag handle for the insertion cursor position. Refer to individual widget documentation for used style classes. A CSS class to match labels. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the left of a widget. Refer to individual widget documentation for used style classes. A CSS class used when rendering a level indicator, such as a battery charge level, or a password strength. Refer to individual widget documentation for used style classes. A CSS class to match a linked area, such as a box containing buttons belonging to the same control. Refer to individual widget documentation for used style classes. A CSS class to match lists. Refer to individual widget documentation for used style classes. A CSS class to match list rows. Refer to individual widget documentation for used style classes. A CSS class defining marks in a widget, such as in scales. Refer to individual widget documentation for used style classes. A CSS class to match menus. Refer to individual widget documentation for used style classes. A CSS class to menubars. Refer to individual widget documentation for used style classes. A CSS class to match menu items. Refer to individual widget documentation for used style classes. A CSS class that is added to message dialogs. Refer to individual widget documentation for used style classes. A CSS class that is added to text view that should use a monospace font. Refer to individual widget documentation for used style classes. A CSS class used when an element needs the user attention, for instance a button in a stack switcher corresponding to a hidden page that changed state. Refer to individual widget documentation for used style classes. A CSS class defining a notebook. Refer to individual widget documentation for used style classes. A CSS class used when rendering an OSD (On Screen Display) element, on top of another container. Refer to individual widget documentation for used style classes. A CSS class that is added on the visual hints that happen when scrolling is attempted past the limits of a scrollable area. Refer to individual widget documentation for used style classes. A CSS class for a pane separator, such as those in #GtkPaned. Refer to individual widget documentation for used style classes. A CSS class that is added to areas that should look like paper. This is used in print previews and themes are encouraged to style it as black text on white background. Refer to individual widget documentation for used style classes. A CSS class that matches popovers. Refer to individual widget documentation for used style classes. A CSS class that is added to the toplevel windows used for menus. Refer to individual widget documentation for used style classes. A CSS class to match primary toolbars. Refer to individual widget documentation for used style classes. A CSS class to use when rendering activity as a progressbar. Refer to individual widget documentation for used style classes. A CSS class to use when rendering a pulse in an indeterminate progress bar. Refer to individual widget documentation for used style classes. A CSS class for an area displaying a question to the user, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class to match radio buttons. Refer to individual widget documentation for used style classes. A CSS class to match a raised control, such as a raised button on a toolbar. Refer to individual widget documentation for used style classes. A CSS class used to indicate a read-only state. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the right of a widget. Refer to individual widget documentation for used style classes. A CSS class to match the rubberband selection rectangle. Refer to individual widget documentation for used style classes. A CSS class to match scale widgets. Refer to individual widget documentation for used style classes. A CSS class to match scale widgets with marks attached, all the marks are above for horizontal #GtkScale. left for vertical #GtkScale. Refer to individual widget documentation for used style classes. A CSS class to match scale widgets with marks attached, all the marks are below for horizontal #GtkScale, right for vertical #GtkScale. Refer to individual widget documentation for used style classes. A CSS class to match scrollbars. Refer to individual widget documentation for used style classes. A CSS class to match the junction area between an horizontal and vertical scrollbar, when they’re both shown. Refer to individual widget documentation for used style classes. A CSS class for a separator. Refer to individual widget documentation for used style classes. A CSS class defining a sidebar, such as the left side in a file chooser. Refer to individual widget documentation for used style classes. A CSS class to match sliders. Refer to individual widget documentation for used style classes. A CSS class defining an spinbutton. Refer to individual widget documentation for used style classes. A CSS class to use when rendering activity as a “spinner”. Refer to individual widget documentation for used style classes. A CSS class to match statusbars. Refer to individual widget documentation for used style classes. A CSS class used for the subtitle label in a titlebar in a toplevel window. Refer to individual widget documentation for used style classes. A CSS class used when an action (usually a button) is the primary suggested action in a specific context. Refer to individual widget documentation for used style classes. A CSS class used for the title label in a titlebar in a toplevel window. Refer to individual widget documentation for used style classes. A CSS class used when rendering a titlebar in a toplevel window. Refer to individual widget documentation for used style classes. A CSS class to match toolbars. Refer to individual widget documentation for used style classes. A CSS class to match tooltip windows. Refer to individual widget documentation for used style classes. A CSS class to indicate an area at the top of a widget. Refer to individual widget documentation for used style classes. A CSS class for touch selection popups on entries and text views. Refer to individual widget documentation for used style classes. A CSS class to match troughs, as in scrollbars and progressbars. Refer to individual widget documentation for used style classes. A CSS class that is added on the visual hints that happen where content is 'scrolled off' and can be made visible by scrolling. Refer to individual widget documentation for used style classes. A CSS class for vertically layered widgets. Refer to individual widget documentation for used style classes. A CSS class defining a view, such as iconviews or treeviews. Refer to individual widget documentation for used style classes. A CSS class for an area displaying a warning message, such as those in infobars. Refer to individual widget documentation for used style classes. A CSS class to indicate that a UI element should be 'wide'. Used by #GtkPaned. Refer to individual widget documentation for used style classes. A property holding the background color of rendered elements as a #GdkRGBA. A property holding the element’s background as a #cairo_pattern_t. A property holding the element’s border color as a #GdkRGBA. A property holding the rendered element’s border radius in pixels as a #gint. A property holding the element’s border style as a #GtkBorderStyle. A property holding the rendered element’s border width in pixels as a #GtkBorder. The border is the intermediary spacing property of the padding/border/margin series. gtk_render_frame() uses this property to find out the frame line width, so #GtkWidgets rendering frames may need to add up this padding when requesting size A property holding the foreground color of rendered elements as a #GdkRGBA. A property holding the font properties used when rendering text as a #PangoFontDescription. A property holding the rendered element’s margin as a #GtkBorder. The margin is defined as the spacing between the border of the element and its surrounding elements. It is external to #GtkWidget's size allocations, and the most external spacing property of the padding/border/margin series. A property holding the rendered element’s padding as a #GtkBorder. The padding is defined as the spacing between the inner part of the element border and its child. It’s the innermost spacing property of the padding/border/margin series. A priority that can be used when adding a #GtkStyleProvider for application-specific style information. The priority used for default style information that is used in the absence of themes. Note that this is not very useful for providing default styling for custom style classes - themes are likely to override styling provided at this priority with catch-all `* {...}` rules. The priority used for style information provided via #GtkSettings. This priority is higher than #GTK_STYLE_PROVIDER_PRIORITY_THEME to let settings override themes. The priority used for style information provided by themes. The priority used for the style information from `XDG_CONFIG_HOME/gtk-3.0/gtk.css`. You should not use priorities higher than this, to give the user the last word. A widget region name to define a treeview column. Don't use regions. A widget region name to define a treeview column header. Don't use regions. A widget region name to define a treeview row. Don't use regions. A widget region name to define a notebook tab. Don't use regions. A GtkScale 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, #GtkRange, in addition to the methods for GtkScale itself. To set the value of a scale, you would normally use gtk_range_set_value(). To detect changes to the value, you would normally use the #GtkRange::value-changed signal. Note that using the same upper and lower bounds for the #GtkScale (through the #GtkRange 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). # GtkScale as GtkBuildable GtkScale supports a custom <marks> element, which can contain multiple <mark> elements. The “value” and “position” attributes have the same meaning as gtk_scale_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 |[<!-- language="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 ]| GtkScale 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 gtk_scale_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 gtk_range_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 #GtkScale:draw-value), there is subnode with name value. Creates a new #GtkScale. a new #GtkScale the scale’s orientation. the #GtkAdjustment which sets the range of the scale, or %NULL to create a new adjustment. 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 gtk_scale_set_digits() to correct it. a new #GtkScale the scale’s orientation. minimum value maximum value step increment (tick size) used with keyboard shortcuts Obtains the coordinates where the scale will draw the #PangoLayout representing the text in the scale. Remember when using the #PangoLayout function you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. If the #GtkScale:draw-value property is %FALSE, the return values are undefined. a #GtkScale location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL 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 %NULL, text is shown next to the tick mark. To remove marks from a scale, use gtk_scale_clear_marks(). a #GtkScale the value at which the mark is placed, must be between the lower and upper limits of the scales’ adjustment where to draw the mark. For a horizontal scale, #GTK_POS_TOP and %GTK_POS_LEFT are drawn above the scale, anything else below. For a vertical scale, #GTK_POS_LEFT and %GTK_POS_TOP are drawn to the left of the scale, anything else to the right. Text to be shown at the mark, using [Pango markup][PangoMarkupFormat], or %NULL Removes any marks that have been added with gtk_scale_add_mark(). a #GtkScale Gets the number of decimal places that are displayed in the value. the number of decimal places that are displayed a #GtkScale Returns whether the current value is displayed as a string next to the slider. whether the current value is displayed as a string a #GtkScale Returns whether the scale has an origin. %TRUE if the scale has an origin. a #GtkScale Gets the #PangoLayout used to display the scale. The returned object is owned by the scale so does not need to be freed by the caller. the #PangoLayout for this scale, or %NULL if the #GtkScale:draw-value property is %FALSE. A #GtkScale Obtains the coordinates where the scale will draw the #PangoLayout representing the text in the scale. Remember when using the #PangoLayout function you need to convert to and from pixels using PANGO_PIXELS() or #PANGO_SCALE. If the #GtkScale:draw-value property is %FALSE, the return values are undefined. a #GtkScale location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Gets the position in which the current value is displayed. the position in which the current value is displayed a #GtkScale 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 #GtkScale:draw-value is %TRUE when the value changes. If you want to enforce rounding the value when #GtkScale:draw-value is %FALSE, you can set #GtkRange:round-digits instead. Note that rounding to a small number of digits can interfere with the smooth autoscrolling that is built into #GtkScale. As an alternative, you can use the #GtkScale::format-value signal to format the displayed value yourself. a #GtkScale the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00, etc Specifies whether the current value is displayed as a string next to the slider. a #GtkScale %TRUE to draw the value If #GtkScale: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. a #GtkScale %TRUE if the scale has an origin Sets the position in which the current value is displayed. a #GtkScale the position in which the current value is displayed 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 #GtkScale:digits property. Here's an example signal handler which displays a value 1.0 as with "-->1.0<--". |[<!-- language="C" --> static gchar* format_value_callback (GtkScale *scale, gdouble value) { return g_strdup_printf ("-->\%0.*g<--", gtk_scale_get_digits (scale), value); } ]| allocated string representing @value the value to format #GtkScaleButton 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 #GtkVolumeButton subclass that is tailored for this use case. # CSS nodes GtkScaleButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .scale style class. The popup widget that contains the scale has a .scale-popup style class. Creates a #GtkScaleButton, with a range between @min and @max, with a stepping of @step. a new #GtkScaleButton a stock icon size (#GtkIconSize) the minimum value of the scale (usually 0) the maximum value of the scale (usually 100) the stepping of value when a scroll-wheel event, or up/down arrow event occurs (usually 2) a %NULL-terminated array of icon names, or %NULL if you want to set the list later with gtk_scale_button_set_icons() Gets the #GtkAdjustment associated with the #GtkScaleButton’s scale. See gtk_range_get_adjustment() for details. the adjustment associated with the scale a #GtkScaleButton Retrieves the minus button of the #GtkScaleButton. the minus button of the #GtkScaleButton as a #GtkButton a #GtkScaleButton Retrieves the plus button of the #GtkScaleButton. the plus button of the #GtkScaleButton as a #GtkButton a #GtkScaleButton Retrieves the popup of the #GtkScaleButton. the popup of the #GtkScaleButton a #GtkScaleButton Gets the current value of the scale button. current value of the scale button a #GtkScaleButton Sets the #GtkAdjustment to be used as a model for the #GtkScaleButton’s scale. See gtk_range_set_adjustment() for details. a #GtkScaleButton a #GtkAdjustment Sets the icons to be used by the scale button. For details, see the #GtkScaleButton:icons property. a #GtkScaleButton a %NULL-terminated array of icon names 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 #GtkScaleButton::value-changed signal if the value changes. a #GtkScaleButton new value of the scale button 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 #GtkScaleButton reflects the current value of the scale better for the users. The ::popdown signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popdown the scale widget. The default binding for this signal is Escape. The ::popup signal is a [keybinding signal][GtkBindingSignal] which gets emitted to popup the scale widget. The default bindings for this signal are Space, Enter and Return. The ::value-changed signal is emitted when the value field has changed. the new value a #GtkScale location to store X offset of layout, or %NULL location to store Y offset of layout, or %NULL Scroll in steps. Scroll by pages. Scroll to ends. Scroll in horizontal steps. Scroll by horizontal pages. Scroll to the horizontal ends. Scrolling types. No scrolling. Jump to new location. Step backward. Step forward. Page backward. Page forward. Step up. Step down. Page up. Page down. Step to the left. Step to the right. Page to the left. Page to the right. Scroll to start. Scroll to end. #GtkScrollable is an interface that is implemented by widgets with native scrolling ability. To implement this interface you should override the #GtkScrollable:hadjustment and #GtkScrollable: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’ #GtkAdjustment:lower, #GtkAdjustment:upper, #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and #GtkAdjustment:page-size properties and connect to the #GtkAdjustment::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 #GtkWidgetClass.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 #GtkAdjustment::value-changed signal, the scrollable widget should scroll its contents. 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. %TRUE if @border has been set a #GtkScrollable return location for the results 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. %TRUE if @border has been set a #GtkScrollable return location for the results Retrieves the #GtkAdjustment used for horizontal scrolling. horizontal #GtkAdjustment. a #GtkScrollable Gets the horizontal #GtkScrollablePolicy. The horizontal #GtkScrollablePolicy. a #GtkScrollable Retrieves the #GtkAdjustment used for vertical scrolling. vertical #GtkAdjustment. a #GtkScrollable Gets the vertical #GtkScrollablePolicy. The vertical #GtkScrollablePolicy. a #GtkScrollable Sets the horizontal adjustment of the #GtkScrollable. a #GtkScrollable a #GtkAdjustment Sets the #GtkScrollablePolicy to determine whether horizontal scrolling should start below the minimum width or below the natural width. a #GtkScrollable the horizontal #GtkScrollablePolicy Sets the vertical adjustment of the #GtkScrollable. a #GtkScrollable a #GtkAdjustment Sets the #GtkScrollablePolicy to determine whether vertical scrolling should start below the minimum height or below the natural height. a #GtkScrollable the vertical #GtkScrollablePolicy Horizontal #GtkAdjustment of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines whether horizontal scrolling should start once the scrollable widget is allocated less than its minimum width or less than its natural width. Verical #GtkAdjustment of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines whether vertical scrolling should start once the scrollable widget is allocated less than its minimum height or less than its natural height. %TRUE if @border has been set a #GtkScrollable return location for the results Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation. Scrollable adjustments are based on the minimum size Scrollable adjustments are based on the natural size The #GtkScrollbar widget is a horizontal or vertical scrollbar, depending on the value of the #GtkOrientable:orientation property. Its position and movement are controlled by the adjustment that is passed to or created by gtk_scrollbar_new(). See #GtkAdjustment for more details. The #GtkAdjustment:value field sets the position of the thumb and must be between #GtkAdjustment:lower and #GtkAdjustment:upper - #GtkAdjustment:page-size. The #GtkAdjustment:page-size represents the size of the visible scrollable area. The fields #GtkAdjustment:step-increment and #GtkAdjustment:page-increment fields are added to or subtracted from the #GtkAdjustment: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 |[<!-- language="plain" --> scrollbar[.fine-tune] ╰── contents ├── [button.up] ├── [button.down] ├── trough │ ╰── slider ├── [button.up] ╰── [button.down] ]| GtkScrollbar 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 #GtkScrolledWindow include the positional classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering). Creates a new scrollbar with the given orientation. the new #GtkScrollbar. the scrollbar’s orientation. the #GtkAdjustment to use, or %NULL to create a new adjustment. GtkScrolledWindow 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 #GtkScrollable interface, are added directly. For other types of widget, the class #GtkViewport acts as an adaptor, giving scrollability to other widgets. GtkScrolledWindow’s implementation of gtk_container_add() intelligently accounts for whether or not the added child is a #GtkScrollable. If it isn’t, #GtkScrolledWindow wraps the child in a #GtkViewport and adds that for you. Therefore, you can just add any child widget and not worry about the details. If gtk_container_add() has added a #GtkViewport for you, you can remove both your added child widget from the #GtkViewport, and the #GtkViewport from the GtkScrolledWindow, like this: |[<!-- language="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 #GtkScrolledWindow:policy is GTK_POLICY_NEVER or GTK_POLICY_EXTERNAL, GtkScrolledWindow adds internal #GtkScrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the #GtkScrolledWindow:hadjustment and #GtkScrolledWindow:vadjustment that are associated with the GtkScrolledWindow. See the docs on #GtkScrollbar 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 GtkScrolledWindow 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 #GtkScrollbar and for example a #GtkGrid. # Touch support GtkScrolledWindow 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 #GtkScrolledWindow:kinetic-scrolling property if it is undesired. GtkScrolledWindow also displays visual 'overshoot' indication when the content is pulled beyond the end, and this situation can be captured with the #GtkScrolledWindow::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 #GtkScrolledWindow:overlay-scrolling property. # CSS nodes GtkScrolledWindow 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. GtkScrolledWindow 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. 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 %NULL for the adjustments, which will cause the scrolled window to create them for you. a new scrolled window horizontal adjustment vertical adjustment Used to add children without native scrolling capabilities. This is simply a convenience function; it is equivalent to adding the unscrollable child to a viewport, then adding the viewport to the scrolled window. If a child has native scrolling, use gtk_container_add() instead of this function. The viewport scrolls the child by moving its #GdkWindow, and takes the size of the child to be the size of its toplevel #GdkWindow. This will be very wrong for most widgets that support native scrolling; for example, if you add a widget such as #GtkTreeView with a viewport, the whole widget will scroll, including the column headings. Thus, widgets with native scrolling support should not be used with the #GtkViewport proxy. A widget supports scrolling natively if it implements the #GtkScrollable interface. gtk_container_add() will automatically add a #GtkViewport if the child doesn’t implement #GtkScrollable. a #GtkScrolledWindow the widget you want to scroll Return whether button presses are captured during kinetic scrolling. See gtk_scrolled_window_set_capture_button_press(). %TRUE if button presses are captured during kinetic scrolling a #GtkScrolledWindow Returns the horizontal scrollbar’s adjustment, used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality. the horizontal #GtkAdjustment a #GtkScrolledWindow Returns the horizontal scrollbar of @scrolled_window. the horizontal scrollbar of the scrolled window. a #GtkScrolledWindow Returns the specified kinetic scrolling behavior. the scrolling behavior flags. a #GtkScrolledWindow Returns the maximum content height set. the maximum content height, or -1 a #GtkScrolledWindow Returns the maximum content width set. the maximum content width, or -1 a #GtkScrolledWindow Gets the minimal content height of @scrolled_window, or -1 if not set. the minimal content height a #GtkScrolledWindow Gets the minimum content width of @scrolled_window, or -1 if not set. the minimum content width a #GtkScrolledWindow Returns whether overlay scrolling is enabled for this scrolled window. %TRUE if overlay scrolling is enabled a #GtkScrolledWindow Gets the placement of the contents with respect to the scrollbars for the scrolled window. See gtk_scrolled_window_set_placement(). the current placement value. See also gtk_scrolled_window_set_placement() and gtk_scrolled_window_unset_placement(). a #GtkScrolledWindow Retrieves the current policy values for the horizontal and vertical scrollbars. See gtk_scrolled_window_set_policy(). a #GtkScrolledWindow location to store the policy for the horizontal scrollbar, or %NULL location to store the policy for the vertical scrollbar, or %NULL Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height. whether natural height propagation is enabled. a #GtkScrolledWindow Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width. whether natural width propagation is enabled. a #GtkScrolledWindow Gets the shadow type of the scrolled window. See gtk_scrolled_window_set_shadow_type(). the current shadow type a #GtkScrolledWindow Returns the vertical scrollbar’s adjustment, used to connect the vertical scrollbar to the child widget’s vertical scroll functionality. the vertical #GtkAdjustment a #GtkScrolledWindow Returns the vertical scrollbar of @scrolled_window. the vertical scrollbar of the scrolled window. a #GtkScrolledWindow Changes the behaviour of @scrolled_window 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 #GtkWidget::button-press-event. If they don't, and handle additionally handle #GtkWidget::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. a #GtkScrolledWindow %TRUE to capture button presses Sets the #GtkAdjustment for the horizontal scrollbar. a #GtkScrolledWindow the #GtkAdjustment to use, or %NULL to create a new one Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. a #GtkScrolledWindow %TRUE to enable kinetic scrolling Sets the maximum height that @scrolled_window should keep visible. The @scrolled_window 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 #GtkScrolledWindow:min-content-height. a #GtkScrolledWindow the maximum content height Sets the maximum width that @scrolled_window should keep visible. The @scrolled_window 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 #GtkScrolledWindow:min-content-width. a #GtkScrolledWindow the maximum content width Sets the minimum height that @scrolled_window 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 #GtkScrolledWindow:max-content-height. a #GtkScrolledWindow the minimal content height Sets the minimum width that @scrolled_window 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 #GtkScrolledWindow:max-content-width. a #GtkScrolledWindow the minimal content width Enables or disables overlay scrolling for this scrolled window. a #GtkScrolledWindow whether to enable overlay scrolling Sets the placement of the contents with respect to the scrollbars for the scrolled window. The default is %GTK_CORNER_TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in #GtkCornerType are %GTK_CORNER_TOP_RIGHT, %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT. See also gtk_scrolled_window_get_placement() and gtk_scrolled_window_unset_placement(). a #GtkScrolledWindow position of the child window Sets the scrollbar policy for the horizontal and vertical scrollbars. The policy determines when the scrollbar should appear; it is a value from the #GtkPolicyType enumeration. If %GTK_POLICY_ALWAYS, the scrollbar is always present; if %GTK_POLICY_NEVER, the scrollbar is never present; if %GTK_POLICY_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). a #GtkScrolledWindow policy for horizontal bar policy for vertical bar Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. a #GtkScrolledWindow whether to propagate natural height Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. a #GtkScrolledWindow whether to propagate natural width Changes the type of shadow drawn around the contents of @scrolled_window. a #GtkScrolledWindow kind of shadow to draw around scrolled window contents Sets the #GtkAdjustment for the vertical scrollbar. a #GtkScrolledWindow the #GtkAdjustment to use, or %NULL to create a new one 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 %GTK_CORNER_TOP_LEFT. See also gtk_scrolled_window_set_placement() and gtk_scrolled_window_get_placement(). a #GtkScrolledWindow Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. The maximum content height of @scrolled_window, or -1 if not set. The maximum content width of @scrolled_window, or -1 if not set. The minimum content height of @scrolled_window, or -1 if not set. The minimum content width of @scrolled_window, or -1 if not set. 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 #GtkSettings::gtk-overlay-scrolling setting. 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. 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. Whether "window-placement" should be used to determine the location of the contents with respect to the scrollbars. This value is ignored and #GtkScrolledWindow:window-placement value is always honored. 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 #GtkScrolledWindow::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. edge side that was hit 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 #GtkScrolledWindow::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. edge side that was reached The ::move-focus-out signal is a [keybinding signal][GtkBindingSignal] which gets emitted when focus is moved away from the scrolled window by a keybinding. The #GtkWidget::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. either %GTK_DIR_TAB_FORWARD or %GTK_DIR_TAB_BACKWARD The ::scroll-child signal is a [keybinding signal][GtkBindingSignal] 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. a #GtkScrollType describing how much to scroll whether the keybinding scrolls the child horizontally or not The parent class. #GtkSearchBar 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 gtk_search_bar_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 gtk_search_bar_connect_entry(). The following example shows you how to create a more complex search entry. # CSS nodes GtkSearchBar 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) Creates a #GtkSearchBar. You will need to tell it about which widget is going to be your text entry using gtk_search_bar_connect_entry(). a new #GtkSearchBar Connects the #GtkEntry 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). a #GtkSearchBar a #GtkEntry Returns whether the search mode is on or off. whether search mode is toggled on a #GtkSearchBar Returns whether the close button is shown. whether the close button is shown a #GtkSearchBar 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 gtk_search_bar_connect_entry(), this function will return immediately with a warning. ## Showing the search bar on key presses |[<!-- language="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); } ]| %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. a #GtkSearchBar a #GdkEvent containing key press events Switches the search mode on or off. a #GtkSearchBar the new state of the search mode 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. a #GtkSearchBar whether the close button will be shown or not The parent class. #GtkSearchEntry is a subclass of #GtkEntry 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, #GtkSearchEntry emits the #GtkSearchEntry::search-changed signal which can be used instead of the #GtkEditable::changed signal. The #GtkSearchEntry::previous-match, #GtkSearchEntry::next-match and #GtkSearchEntry::stop-search signals can be used to implement moving between search results and ending the search. Often, GtkSearchEntry will be fed events by means of being placed inside a #GtkSearchBar. If that is not the case, you can use gtk_search_entry_handle_event() to pass events. Creates a #GtkSearchEntry, with a find icon when the search field is empty, and a clear icon when it isn't. a new #GtkSearchEntry 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 #GtkSearchBar, it is preferable to call gtk_search_bar_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. %GDK_EVENT_STOP if the key press event resulted in a search beginning or continuing, %GDK_EVENT_PROPAGATE otherwise. a #GtkSearchEntry a key event The ::next-match signal is a [keybinding signal][GtkBindingSignal] 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. The ::previous-match signal is a [keybinding signal][GtkBindingSignal] 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. The #GtkSearchEntry::search-changed signal is emitted with a short delay of 150 milliseconds after the last change to the entry text. The ::stop-search signal is a [keybinding signal][GtkBindingSignal] 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. Makes a copy of a #GtkSelectionData-struct and its data. a pointer to a copy of @data. a pointer to a #GtkSelectionData-struct. Frees a #GtkSelectionData-struct returned from gtk_selection_data_copy(). a pointer to a #GtkSelectionData-struct. Retrieves the raw data of the selection. the raw data of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the data type of the selection. the data type of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the raw data of the selection along with its length. the raw data of the selection a pointer to a #GtkSelectionData-struct. return location for length of the data segment Retrieves the display of the selection. the display of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the format of the selection. the format of the selection. a pointer to a #GtkSelectionData-struct. Retrieves the length of the raw data of the selection. the length of the data of the selection. a pointer to a #GtkSelectionData-struct. Gets the contents of the selection data as a #GdkPixbuf. if the selection data contained a recognized image type and it could be converted to a #GdkPixbuf, a newly allocated pixbuf is returned, otherwise %NULL. If the result is non-%NULL it must be freed with g_object_unref(). a #GtkSelectionData Retrieves the selection #GdkAtom of the selection data. the selection #GdkAtom of the selection data. a pointer to a #GtkSelectionData-struct. Retrieves the target of the selection. the target of the selection. a pointer to a #GtkSelectionData-struct. Gets the contents of @selection_data 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. %TRUE if @selection_data contains a valid array of targets, otherwise %FALSE. a #GtkSelectionData object location to store an array of targets. The result stored here must be freed with g_free(). location to store number of items in @targets. Gets the contents of the selection data as a UTF-8 string. 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 %NULL. If the result is non-%NULL it must be freed with g_free(). a #GtkSelectionData Gets the contents of the selection data as array of URIs. if the selection data contains a list of URIs, a newly allocated %NULL-terminated string array containing the URIs, otherwise %NULL. If the result is non-%NULL it must be freed with g_strfreev(). a #GtkSelectionData Stores new data into a #GtkSelectionData object. Should only be called from a selection handler callback. Zero-terminates the stored data. a pointer to a #GtkSelectionData-struct. the type of selection data format (number of bits in a unit) pointer to the data (will be copied) length of the data Sets the contents of the selection from a #GdkPixbuf The pixbuf is converted to the form determined by @selection_data->target. %TRUE if the selection was successfully set, otherwise %FALSE. a #GtkSelectionData a #GdkPixbuf Sets the contents of the selection from a UTF-8 encoded string. The string is converted to the form determined by @selection_data->target. %TRUE if the selection was successfully set, otherwise %FALSE. a #GtkSelectionData a UTF-8 string the length of @str, or -1 if @str is nul-terminated. Sets the contents of the selection from a list of URIs. The string is converted to the form determined by @selection_data->target. %TRUE if the selection was successfully set, otherwise %FALSE. a #GtkSelectionData a %NULL-terminated array of strings holding URIs Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide a #GdkPixbuf. %TRUE if @selection_data holds a list of targets, and a suitable target for images is included, otherwise %FALSE. a #GtkSelectionData object whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide rich text. %TRUE if @selection_data holds a list of targets, and a suitable target for rich text is included, otherwise %FALSE. a #GtkSelectionData object a #GtkTextBuffer Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide text. %TRUE if @selection_data holds a list of targets, and a suitable target for text is included, otherwise %FALSE. a #GtkSelectionData object Given a #GtkSelectionData object holding a list of targets, determines if any of the targets in @targets can be used to provide a list or URIs. %TRUE if @selection_data holds a list of targets, and a suitable target for URI lists is included, otherwise %FALSE. a #GtkSelectionData object Used to control what selections users are allowed to make. No selection is possible. Zero or one element may be selected. 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 %GTK_SELECTION_BROWSE. What is really enforced is that the user can’t deselect a currently selected element except by selecting another element. 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. Determines how GTK+ handles the sensitivity of stepper arrows at the end of range widgets. The arrow is made insensitive if the thumb is at the end The arrow is always sensitive The arrow is always insensitive GtkSeparator is a horizontal or vertical separator widget, depending on the value of the #GtkOrientable: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 GtkSeparator has a single CSS node with name separator. The node gets one of the .horizontal or .vertical style classes. Creates a new #GtkSeparator with the given orientation. a new #GtkSeparator. the separator’s orientation. The #GtkSeparatorMenuItem 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 GtkSeparatorMenuItem has a single CSS node with name separator. Creates a new #GtkSeparatorMenuItem. a new #GtkSeparatorMenuItem. The parent class. A #GtkSeparatorToolItem is a #GtkToolItem that separates groups of other #GtkToolItems. Depending on the theme, a #GtkSeparatorToolItem will often look like a vertical line on horizontally docked toolbars. If the #GtkToolbar child property “expand” is %TRUE and the property #GtkSeparatorToolItem:draw is %FALSE, a #GtkSeparatorToolItem will act as a “spring” that forces other items to the ends of the toolbar. Use gtk_separator_tool_item_new() to create a new #GtkSeparatorToolItem. # CSS nodes GtkSeparatorToolItem has a single CSS node with name separator. Create a new #GtkSeparatorToolItem the new #GtkSeparatorToolItem Returns whether @item is drawn as a line, or just blank. See gtk_separator_tool_item_set_draw(). %TRUE if @item is drawn as a line, or just blank. a #GtkSeparatorToolItem Whether @item is drawn as a vertical line, or just blank. Setting this to %FALSE along with gtk_tool_item_set_expand() is useful to create an item that forces following items to the end of the toolbar. a #GtkSeparatorToolItem whether @item is drawn as a vertical line The parent class. GtkSettings 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 #GKeyFile), 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 GtkSettings object with g_object_set(). This should be restricted to special cases though; GtkSettings 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: |[<!-- language="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 GtkSettings instance per screen. It can be obtained with gtk_settings_get_for_screen(), but in many cases, it is more convenient to use gtk_widget_get_settings(). gtk_settings_get_default() returns the GtkSettings instance for the default screen. Gets the #GtkSettings object for the default GDK screen, creating it if necessary. See gtk_settings_get_for_screen(). a #GtkSettings object. If there is no default screen, then returns %NULL. Gets the #GtkSettings object for @screen, creating it if necessary. a #GtkSettings object. a #GdkScreen. This function is not useful outside GTK+. This function is not useful outside GTK+. Undoes the effect of calling g_object_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. a #GtkSettings object the name of the setting to reset Use g_object_set() instead. Use g_object_set() instead. Use g_object_set() instead. Use g_object_set() instead. Holds a hash table representation of the #GtkSettings:gtk-color-scheme setting, mapping color names to #GdkColors. Will always return an empty hash table. 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. 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...). Whether mnemonics should be automatically shown and hidden when the user presses the mnemonic activator. This setting is ignored Whether images should be shown on buttons This setting is deprecated. Application developers control whether a button should show an icon or not, on a per-button basis. If a #GtkButton should show an icon, use the #GtkButton:always-show-image property of #GtkButton, and pack a #GtkImage inside the #GtkButton Whether menu accelerators can be changed by pressing a key over the menu item. This setting is ignored. Palette to use in the deprecated color selector. Only used by the deprecated color selector widget. A palette of named colors for use in themes. The format of the string is |[ name1: color1 name2: color2 ... ]| Color names must be acceptable as identifiers in the [gtkrc][gtk3-Resource-Files] syntax, and color specifications must be in the format accepted by gdk_color_parse(). Note that due to the way the color tables from different sources are merged, color specifications will be converted to hexadecimal form when getting this property. Starting with GTK+ 2.12, the entries can alternatively be separated by ';' instead of newlines: |[ name1: color1; name2: color2; ... ]| Color scheme support was dropped and is no longer supported. You can still set this property, but it will be ignored. Whether the cursor should blink. Also see the #GtkSettings:gtk-cursor-blink-timeout setting, which allows more flexible control over cursor blinking. 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 #GtkSettings:gtk-cursor-blink to %FALSE. 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 #GtkHeaderBar:decoration-layout property. 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 GtkDialog directly, or message dialogs. Whether menu items should have visible accelerators which can be activated. 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. 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. Whether labels and menu items should have visible mnemonics which can be activated. This setting can still be used for application overrides, but will be ignored in the future Whether a middle click on a mouse should paste the 'PRIMARY' clipboard content at the cursor location. Whether tooltips should be shown on widgets. This setting is ignored. 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. When %TRUE, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using gdk_window_beep(), the windowing system may offer ways to configure the error bell in many ways, such as flashing the window or similar visual effects. Name of a icon theme to fall back to. This setting is ignored. Name of the GtkFileChooser backend to use by default. This setting is ignored. #GtkFileChooser uses GIO by default. The default font to use. GTK+ uses the family name and size from this string. A list of icon sizes. The list is separated by colons, and item has the form: `size-name` = `width` , `height` E.g. "gtk-menu=16,16:gtk-button=20,20:gtk-dialog=48,48". GTK+ itself use the following named icon sizes: gtk-menu, gtk-button, gtk-small-toolbar, gtk-large-toolbar, gtk-dnd, gtk-dialog. Applications can register their own named icon sizes with gtk_icon_size_register(). This setting is ignored. 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 #GtkIMContext. How to draw the input method preedit string. This setting is ignored. How to draw the input method statusbar. This setting is ignored. When %TRUE, keyboard navigation should be able to reach all widgets by using the cursor keys only. Tab, Shift etc. keys can't be expected to be present on the used input device. Generally, the behavior for touchscreen input should be performed dynamically based on gdk_event_get_source_device(). 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. When %TRUE, some widgets will wrap around when doing keyboard navigation, such as menus, menubars and notebooks. This setting is ignored. The time for a button or touch press to be considered a "long press". Keybinding to activate the menu bar. This setting can still be used for application overrides, but will be ignored in the future Delay before the submenus of a menu bar appear. This setting is ignored. Whether images should be shown in menu items This setting is deprecated. Application developers control whether or not a #GtkMenuItem should have an icon or not, on a per widget basis. Either use a #GtkMenuItem with a #GtkBox containing a #GtkImage and a #GtkAccelLabel, or describe your menus using a #GMenu XML description The time before hiding a submenu when the pointer is moving towards the submenu. This setting is ignored. Minimum time the pointer must stay over a menu item before the submenu appear. This setting is ignored. Whether scrolled windows may use overlayed scrolling indicators. If this is set to %FALSE, scrolled windows will have permanent scrollbars. If the value of this setting is %TRUE, clicking the primary button in a #GtkRange 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. 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". 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 gtk_print_settings_to_file(). The preview application is responsible for removing the pdf file and the print settings file when it is done. Whether GTK+ should keep track of items inside the recently used resources list. If set to %FALSE, the list will always be empty. The number of recently used files that should be displayed by default by #GtkRecentChooser implementations and by the #GtkFileChooser. A value of -1 means every recently used file stored. This setting is ignored 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. Where the contents of scrolled windows are located with respect to the scrollbars, if not overridden by the scrolled window's own placement. This setting is ignored. This setting is ignored. This setting is ignored. 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. This setting is ignored. This setting is ignored. This setting is ignored. 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. 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. 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. The size of icons in default toolbars. This setting is ignored. The size of icons in default toolbars. This setting is ignored. Amount of time, in milliseconds, after which the browse mode will be disabled. See #GtkSettings:gtk-tooltip-browse-timeout for more information about browse mode. This setting is ignored. Controls the time after which tooltips will appear when browse mode is enabled, in milliseconds. Browse mode is enabled when the mouse pointer moves off an object where a tooltip was currently being displayed. If the mouse pointer hits another object before the browse mode timeout expires (see #GtkSettings:gtk-tooltip-browse-mode-timeout), it will take the amount of milliseconds specified by this setting to popup the tooltip for the new object. This setting is ignored. Time, in milliseconds, after which a tooltip could appear if the cursor is hovering on top of a widget. This setting is ignored. When %TRUE, there are no motion notify events delivered on this screen, and widgets can't use the pointer hovering them for any essential functionality. Generally, the behavior for touchscreen input should be performed dynamically based on gdk_event_get_source_device(). Whether 'focus rectangles' should be always visible, never visible, or hidden until the user starts to use the keyboard. This setting is ignored Origin should be something like “filename:linenumber” for rc files, or e.g. “XProperty” for other sources. Valid types are LONG, DOUBLE and STRING corresponding to the token parsed, or a GSTRING holding an unparsed statement Used to change the appearance of an outline typically provided by a #GtkFrame. Note that many themes do not differentiate the appearance of the various shadow types: Either their is no visible shadow (@GTK_SHADOW_NONE), or there is (any other value). No outline. The outline is bevelled inwards. The outline is bevelled outwards like a button. The outline has a sunken 3d appearance. The outline has a raised 3d appearance. #GtkShortcutLabel is a widget that represents a single keyboard shortcut or gesture in the user interface. Creates a new #GtkShortcutLabel with @accelerator set. a newly-allocated #GtkShortcutLabel the initial accelerator Retrieves the current accelerator of @self. the current accelerator. a #GtkShortcutLabel Retrieves the text that is displayed when no accelerator is set. the current text displayed when no accelerator is set. a #GtkShortcutLabel Sets the accelerator to be displayed by @self. a #GtkShortcutLabel the new accelerator Sets the text to be displayed by @self when no accelerator is set. a #GtkShortcutLabel the text to be displayed when no accelerator is set The accelerator that @self displays. See #GtkShortcutsShortcut:accelerator for the accepted syntax. The text that is displayed when no accelerator is set. GtkShortcutType specifies the kind of shortcut that is being described. More values may be added to this enumeration over time. The shortcut is a keyboard accelerator. The #GtkShortcutsShortcut:accelerator property will be used. The shortcut is a pinch gesture. GTK+ provides an icon and subtitle. The shortcut is a stretch gesture. GTK+ provides an icon and subtitle. The shortcut is a clockwise rotation gesture. GTK+ provides an icon and subtitle. The shortcut is a counterclockwise rotation gesture. GTK+ provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK+ provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK+ provides an icon and subtitle. The shortcut is a gesture. The #GtkShortcutsShortcut:icon property will be used. A GtkShortcutsGroup 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 #GtkShortcutsWindow. 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. A rough measure for the number of lines in this group. This is used internally by GTK+, and is not useful for applications. The title for this group of shortcuts. 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. An optional view that the shortcuts in this group are relevant for. The group will be hidden if the #GtkShortcutsWindow:view-name property does not match the view of this group. Set this to %NULL to make the group always visible. A GtkShortcutsSection 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 #GtkShortcutsSection:section-name and a #GtkShortcutsSection:title that can be shown in the section selector of the GtkShortcutsWindow. The #GtkShortcutsSection: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 #GtkShortcutsWindow. 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. A unique name to identify this section among the sections added to the GtkShortcutsWindow. Setting the #GtkShortcutsWindow:section-name property to this string will make this section shown in the GtkShortcutsWindow. The string to show in the section selector of the GtkShortcutsWindow 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. A view name to filter the groups in this section by. See #GtkShortcutsGroup:view. Applications are expected to use the #GtkShortcutsWindow:view-name property for this purpose. A GtkShortcutsShortcut represents a single keyboard shortcut or gesture with a short text. This widget is only meant to be used with #GtkShortcutsWindow. The size group for the accelerator portion of this shortcut. This is used internally by GTK+, and must not be modified by applications. The accelerator(s) represented by this object. This property is used if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_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. A detailed action name. If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR, then GTK+ will use the accelerators that are associated with the action via gtk_application_set_accels_for_action(), and setting #GtkShortcutsShortcut::accelerator is not necessary. The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to #GTK_TEXT_DIR_NONE. An icon to represent the shortcut or gesture. This property is used if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_GESTURE. For the other predefined gesture types, GTK+ provides an icon on its own. %TRUE if an icon has been set. The type of shortcut that is represented. 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. %TRUE if a subtitle has been set. 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. The size group for the textual portion of this shortcut. This is used internally by GTK+, and must not be modified by applications. A GtkShortcutsWindow 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 GtkShortcutsWindow is with GtkBuilder, by populating a #GtkShortcutsWindow with one or more #GtkShortcutsSection objects, which contain #GtkShortcutsGroups that in turn contain objects of class #GtkShortcutsShortcut. # A simple example:  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:  This example shows a #GtkShortcutsWindow 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:  This example shows a #GtkShortcutsWindow 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). The name of the section to show. This should be the section-name of one of the #GtkShortcutsSection objects that are in this shortcuts window. The view name by which to filter the contents. This should correspond to the #GtkShortcutsGroup:view property of some of the #GtkShortcutsGroup objects that are inside this shortcuts window. Set this to %NULL to show all groups. The ::close signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to close the window. The default binding for this signal is the Escape key. The ::search signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user uses a keybinding to start a search. The default binding for this signal is Control-F. #GtkSizeGroup 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 #GtkGrid widget. In detail, the size requested for each widget in a #GtkSizeGroup 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 gtk_size_group_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 #GtkSizeGroup 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 %GTK_FILL flag. #GtkSizeGroup objects are referenced by each widget in the size group, so once you have added all widgets to a #GtkSizeGroup, you can drop the initial reference to the size group with g_object_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 %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_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 %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_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 %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_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 #GtkLabel:width-chars for instance. Widgets with static sizes as well as widgets that grow (such as ellipsizing text) need no such considerations. # GtkSizeGroup as GtkBuildable 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 GtkSizeGroup: |[ <object class="GtkSizeGroup"> <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property> <widgets> <widget name="radio1"/> <widget name="radio2"/> </widgets> </object> ]| Create a new #GtkSizeGroup. a newly created #GtkSizeGroup the mode for the new size group. Adds a widget to a #GtkSizeGroup. 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 gtk_size_group_set_mode(). When the widget is destroyed or no longer referenced elsewhere, it will be removed from the size group. a #GtkSizeGroup the #GtkWidget to add Returns if invisible widgets are ignored when calculating the size. 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 #GtkStack instead to hide widgets while still having their size taken into account. %TRUE if invisible widgets are ignored. a #GtkSizeGroup Gets the current mode of the size group. See gtk_size_group_set_mode(). the current mode of the size group. a #GtkSizeGroup Returns the list of widgets associated with @size_group. a #GSList of widgets. The list is owned by GTK+ and should not be modified. a #GtkSizeGroup Removes a widget from a #GtkSizeGroup. a #GtkSizeGroup the #GtkWidget to remove Sets whether unmapped widgets should be ignored when calculating the size. 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 #GtkStack instead to hide widgets while still having their size taken into account. a #GtkSizeGroup whether unmapped widgets should be ignored when calculating the size Sets the #GtkSizeGroupMode 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 (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition in both directions (%GTK_SIZE_GROUP_BOTH). a #GtkSizeGroup the mode to set for the size group. If %TRUE, unmapped widgets are ignored when determining the size of the group. 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 #GtkStack instead to hide widgets while still having their size taken into account. The mode of the size group determines the directions in which the size group affects the requested sizes of its component widgets. group has no effect group affects horizontal requisition group affects vertical requisition group affects both horizontal and vertical requisition Specifies a preference for height-for-width or width-for-height geometry management. Prefer height-for-width geometry management Prefer width-for-height geometry management Don’t trade height-for-width or width-for-height Together with #GtkPlug, #GtkSocket 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 #GtkSocket widget and passes that widget’s window ID to the other process, which then creates a #GtkPlug with that window ID. Any widgets contained in the #GtkPlug then will appear inside the first application’s window. The socket’s window ID is obtained by using gtk_socket_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. |[<!-- language="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 gtk_socket_get_plug_window(). If it returns a non-%NULL 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 #GtkSocket::plug-removed signal. The communication between a #GtkSocket and a #GtkPlug 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 #GtkPlug and #GtkSocket 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 #GtkPlug and #GtkSocket, you need to include the `gtk/gtkx.h` header. Create a new empty #GtkSocket. the new #GtkSocket. Adds an XEMBED client, such as a #GtkPlug, to the #GtkSocket. The client may be in the same process or in a different process. To embed a #GtkPlug in a #GtkSocket, you can either create the #GtkPlug with `gtk_plug_new (0)`, call gtk_plug_get_id() to get the window ID of the plug, and then pass that to the gtk_socket_add_id(), or you can call gtk_socket_get_id() to get the window ID for the socket, and call gtk_plug_new() passing in that ID. The #GtkSocket must have already be added into a toplevel window before you can make this call. a #GtkSocket the Window of a client participating in the XEMBED protocol. Gets the window ID of a #GtkSocket widget, which can then be used to create a client embedded inside the socket, for instance with gtk_plug_new(). The #GtkSocket must have already be added into a toplevel window before you can make this call. the window ID for the socket a #GtkSocket. Retrieves the window of the plug. Use this to check if the plug has been created inside of the socket. the window of the plug if available, or %NULL a #GtkSocket. This signal is emitted when a client is successfully added to the socket. This signal is emitted when a client is removed from the socket. The default action is to destroy the #GtkSocket widget, so if you want to reuse it you must add a signal handler that returns %TRUE. %TRUE to stop other handlers from being invoked. Determines the direction of a sort. Sorting is in ascending order. Sorting is in descending order. A #GtkSpinButton 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 #GtkEntry, GtkSpinButton 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 GtkSpinButton are through an adjustment. See the #GtkAdjustment section for more details about an adjustment's properties. Note that GtkSpinButton 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 #GtkEntry:width-chars and #GtkEntry:max-width-chars poperties to the desired number of characters to display in the entry. # CSS nodes |[<!-- language="plain" --> spinbutton.horizontal ├── undershoot.left ├── undershoot.right ├── entry │ ╰── ... ├── button.down ╰── button.up ]| |[<!-- language="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 GtkEntry 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 GtkSpinButton to get an integer |[<!-- language="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 GtkSpinButton to get a floating point value |[<!-- language="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); } ]| Creates a new #GtkSpinButton. The new spin button as a #GtkWidget the #GtkAdjustment object that this spin button should use, or %NULL 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 the number of decimal places to display This is a convenience constructor that allows creation of a numeric #GtkSpinButton 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 gtk_spin_button_set_digits() to correct it. The new spin button as a #GtkWidget Minimum allowable value Maximum allowable value Increment added or subtracted by spinning the widget Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly. a #GtkSpinButton a #GtkAdjustment to replace the spin button’s existing adjustment, or %NULL to leave its current adjustment unchanged the new climb rate the number of decimal places to display in the spin button Get the adjustment associated with a #GtkSpinButton the #GtkAdjustment of @spin_button a #GtkSpinButton Fetches the precision of @spin_button. See gtk_spin_button_set_digits(). the current precision a #GtkSpinButton Gets the current step and page the increments used by @spin_button. See gtk_spin_button_set_increments(). a #GtkSpinButton location to store step increment, or %NULL location to store page increment, or %NULL Returns whether non-numeric text can be typed into the spin button. See gtk_spin_button_set_numeric(). %TRUE if only numeric text can be entered a #GtkSpinButton Gets the range allowed for @spin_button. See gtk_spin_button_set_range(). a #GtkSpinButton location to store minimum allowed value, or %NULL location to store maximum allowed value, or %NULL Returns whether the values are corrected to the nearest step. See gtk_spin_button_set_snap_to_ticks(). %TRUE if values are snapped to the nearest step a #GtkSpinButton Gets the update behavior of a spin button. See gtk_spin_button_set_update_policy(). the current update policy a #GtkSpinButton Get the value in the @spin_button. the value of @spin_button a #GtkSpinButton Get the value @spin_button represented as an integer. the value of @spin_button a #GtkSpinButton 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 gtk_spin_button_set_wrap(). %TRUE if the spin button wraps around a #GtkSpinButton Replaces the #GtkAdjustment associated with @spin_button. a #GtkSpinButton a #GtkAdjustment to replace the existing adjustment Set the precision to be displayed by @spin_button. Up to 20 digit precision is allowed. a #GtkSpinButton the number of digits after the decimal point to be displayed for the spin button’s value Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button’s arrows are activated. a #GtkSpinButton increment applied for a button 1 press. increment applied for a button 2 press. Sets the flag that determines if non-numeric text can be typed into the spin button. a #GtkSpinButton flag indicating if only numeric entry is allowed Sets the minimum and maximum allowable values for @spin_button. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. a #GtkSpinButton minimum allowable value maximum allowable value 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. a #GtkSpinButton a flag indicating if invalid values should be corrected 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. a #GtkSpinButton a #GtkSpinButtonUpdatePolicy value Sets the value of @spin_button. a #GtkSpinButton the new value 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. a #GtkSpinButton a flag indicating if wrapping behavior is performed Increment or decrement a spin button’s value in a specified direction by a specified amount. a #GtkSpinButton a #GtkSpinType indicating the direction to spin step increment to apply in the specified direction Manually force an update of the spin button. a #GtkSpinButton The ::change-value signal is a [keybinding signal][GtkBindingSignal] 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. a #GtkScrollType to specify the speed and amount of change 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 gtk_entry_get_text() to retrieve the text of the entry and set @new_value to the new value. The default conversion uses g_strtod(). %TRUE for a successful conversion, %FALSE if the input was not handled, and %GTK_INPUT_ERROR if the conversion failed. return location for the new value The ::output signal can be used to change to formatting of the value that is displayed in the spin buttons entry. |[<!-- language="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; } ]| %TRUE if the value has been displayed The ::value-changed signal is emitted when the value represented by @spinbutton changes. Also see the #GtkSpinButton::output signal. The ::wrapped signal is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa. The spin button update policy determines whether the spin button displays values even if they are outside the bounds of its adjustment. See gtk_spin_button_set_update_policy(). When refreshing your #GtkSpinButton, the value is always displayed When refreshing your #GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's adjustment The values of the GtkSpinType enumeration are used to specify the change to make in gtk_spin_button_spin(). Increment by the adjustments step increment. Decrement by the adjustments step increment. Increment by the adjustments page increment. Decrement by the adjustments page increment. Go to the adjustments lower bound. Go to the adjustments upper bound. Change by a specified amount. A GtkSpinner widget displays an icon-size spinning animation. It is often used as an alternative to a #GtkProgressBar for displaying indefinite activity, instead of actual progress. To start the animation, use gtk_spinner_start(), to stop it use gtk_spinner_stop(). # CSS nodes GtkSpinner has a single CSS node with the name spinner. When the animation is active, the :checked pseudoclass is added to this node. Returns a new spinner widget. Not yet started. a new #GtkSpinner Starts the animation of the spinner. a #GtkSpinner Stops the animation of the spinner. a #GtkSpinner The GtkStack widget is a container which only shows one of its children at a time. In contrast to GtkNotebook, GtkStack does not provide a means for users to change the visible child. Instead, the #GtkStackSwitcher widget can be used with GtkStack to provide this functionality. Transitions between pages can be animated as slides or fades. This can be controlled with gtk_stack_set_transition_type(). These animations respect the #GtkSettings:gtk-enable-animations setting. The GtkStack widget was added in GTK+ 3.10. # CSS nodes GtkStack has a single CSS node named stack. Creates a new #GtkStack container. a new #GtkStack Adds a child to @stack. The child is identified by the @name. a #GtkStack the widget to add the name for @child Adds a child to @stack. The child is identified by the @name. The @title will be used by #GtkStackSwitcher to represent @child in a tab bar, so it should be short. a #GtkStack the widget to add the name for @child a human-readable title for @child Finds the child of the #GtkStack with the name given as the argument. Returns %NULL if there is no child with this name. the requested child of the #GtkStack a #GtkStack the name of the child to find Gets whether @stack is horizontally homogeneous. See gtk_stack_set_hhomogeneous(). whether @stack is horizontally homogeneous. a #GtkStack Gets whether @stack is homogeneous. See gtk_stack_set_homogeneous(). whether @stack is homogeneous. a #GtkStack Returns wether the #GtkStack is set up to interpolate between the sizes of children on page switch. %TRUE if child sizes are interpolated A #GtkStack Returns the amount of time (in milliseconds) that transitions between pages in @stack will take. the transition duration a #GtkStack Returns whether the @stack is currently in a transition from one page to another. %TRUE if the transition is currently running, %FALSE otherwise. a #GtkStack Gets the type of animation that will be used for transitions between pages in @stack. the current transition type of @stack a #GtkStack Gets whether @stack is vertically homogeneous. See gtk_stack_set_vhomogeneous(). whether @stack is vertically homogeneous. a #GtkStack Gets the currently visible child of @stack, or %NULL if there are no visible children. the visible child of the #GtkStack a #GtkStack Returns the name of the currently visible child of @stack, or %NULL if there is no visible child. the name of the visible child of the #GtkStack a #GtkStack Sets the #GtkStack to be horizontally homogeneous or not. If it is homogeneous, the #GtkStack will request the same width for all its children. If it isn't, the stack may change width when a different child becomes visible. a #GtkStack %TRUE to make @stack horizontally homogeneous Sets the #GtkStack to be homogeneous or not. If it is homogeneous, the #GtkStack 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 #GtkStack:hhomogeneous and #GtkStack:vhomogeneous. a #GtkStack %TRUE to make @stack homogeneous Sets whether or not @stack will interpolate its size when changing the visible child. If the #GtkStack:interpolate-size property is set to %TRUE, @stack 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. A #GtkStack the new value Sets the duration that transitions between pages in @stack will take. a #GtkStack the new duration, in milliseconds Sets the type of animation that will be used for transitions between pages in @stack. 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. a #GtkStack the new transition type Sets the #GtkStack to be vertically homogeneous or not. If it is homogeneous, the #GtkStack will request the same height for all its children. If it isn't, the stack may change height when a different child becomes visible. a #GtkStack %TRUE to make @stack vertically homogeneous Makes @child the visible child of @stack. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the @child widget has to be visible itself (see gtk_widget_show()) in order to become the visible child of @stack. a #GtkStack a child of @stack Makes the child with the given name visible. Note that the child widget has to be visible itself (see gtk_widget_show()) in order to become the visible child of @stack. a #GtkStack the name of the child to make visible the transition type to use 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 @stack. Note that the child widget has to be visible itself (see gtk_widget_show()) in order to become the visible child of @stack. a #GtkStack the name of the child to make visible %TRUE if the stack allocates the same width for all children. %TRUE if the stack allocates the same height for all children. A GtkStackSidebar enables you to quickly and easily provide a consistent "sidebar" object for your user interface. In order to use a GtkStackSidebar, you simply use a GtkStack to organize your UI flow, and add the sidebar to your sidebar area. You can use gtk_stack_sidebar_set_stack() to connect the #GtkStackSidebar to the #GtkStack. # CSS nodes GtkStackSidebar has a single CSS node with name stacksidebar and style class .sidebar. When circumstances require it, GtkStackSidebar adds the .needs-attention style class to the widgets representing the stack pages. Creates a new sidebar. the new #GtkStackSidebar Retrieves the stack. See gtk_stack_sidebar_set_stack(). the associated #GtkStack or %NULL if none has been set explicitly a #GtkStackSidebar Set the #GtkStack associated with this #GtkStackSidebar. The sidebar widget will automatically update according to the order (packing) and items within the given #GtkStack. a #GtkStackSidebar a #GtkStack The GtkStackSwitcher widget acts as a controller for a #GtkStack; 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 #GtkStack; the button visibility in a #GtkStackSwitcher widget is controlled by the visibility of the child in the #GtkStack. It is possible to associate multiple #GtkStackSwitcher widgets with the same #GtkStack widget. The GtkStackSwitcher widget was added in 3.10. # CSS nodes GtkStackSwitcher has a single CSS node named stackswitcher and style class .stack-switcher. When circumstances require it, GtkStackSwitcher adds the .needs-attention style class to the widgets representing the stack pages. Create a new #GtkStackSwitcher. a new #GtkStackSwitcher. Retrieves the stack. See gtk_stack_switcher_set_stack(). the stack, or %NULL if none has been set explicitly. a #GtkStackSwitcher Sets the stack to control. a #GtkStackSwitcher a #GtkStack Use the "icon-size" property to change the size of the image displayed when a #GtkStackSwitcher is displaying icons. These enumeration values describe the possible transitions between pages in a #GtkStack widget. New values may be added to this enumeration over time. No transition A cross-fade Slide from left to right Slide from right to left Slide from bottom up Slide from top down Slide from left or right according to the children order Slide from top down or bottom up according to the order Cover the old page by sliding up. Since 3.12 Cover the old page by sliding down. Since: 3.12 Cover the old page by sliding to the left. Since: 3.12 Cover the old page by sliding to the right. Since: 3.12 Uncover the new page by sliding up. Since 3.12 Uncover the new page by sliding down. Since: 3.12 Uncover the new page by sliding to the left. Since: 3.12 Uncover the new page by sliding to the right. Since: 3.12 Cover the old page sliding up or uncover the new page sliding down, according to order. Since: 3.12 Cover the old page sliding down or uncover the new page sliding up, according to order. Since: 3.14 Cover the old page sliding left or uncover the new page sliding right, according to order. Since: 3.14 Cover the old page sliding right or uncover the new page sliding left, according to order. Since: 3.14 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. State during normal operation. Widget is active. Widget has a mouse pointer over it. Widget is selected. Widget is insensitive. Widget is inconsistent. Widget has the keyboard focus. Widget is in a background toplevel window. Widget is in left-to-right text direction. Since 3.8 Widget is in right-to-left text direction. Since 3.8 Widget is a link. Since 3.12 The location the widget points to has already been visited. Since 3.12 Widget is checked. Since 3.14 Widget is highlighted as a drop target for DND. Since 3.20 This type indicates the current state of a widget; the state determines how the widget is drawn. The #GtkStateType enumeration is also used to identify different colors in a #GtkStyle for drawing, so states can be used for subparts of a widget as well as entire widgets. All APIs that are using this enumeration have been deprecated in favor of alternatives using #GtkStateFlags. State during normal operation. State of a currently active widget, such as a depressed button. State indicating that the mouse pointer is over the widget and the widget will respond to mouse clicks. State of a selected item, such the selected row in a list. State indicating that the widget is unresponsive to user actions. The widget is inconsistent, such as checkbuttons or radiobuttons that aren’t either set to %TRUE nor %FALSE, or buttons requiring the user attention. The widget has the keyboard focus. The “system tray” or notification area is normally used for transient icons that indicate some special state. For example, a system tray icon might appear to tell the user that they have new mail, or have an incoming instant message, or something along those lines. The basic idea is that creating an icon in the notification area is less annoying than popping up a dialog. A #GtkStatusIcon object can be used to display an icon in a “system tray”. The icon can have a tooltip, and the user can interact with it by activating it or popping up a context menu. It is very important to notice that status icons depend on the existence of a notification area being available to the user; you should not use status icons as the only way to convey critical information regarding your application, as the notification area may not exist on the user's environment, or may have been removed. You should always check that a status icon has been embedded into a notification area by using gtk_status_icon_is_embedded(), and gracefully recover if the function returns %FALSE. On X11, the implementation follows the [FreeDesktop System Tray Specification](http://www.freedesktop.org/wiki/Specifications/systemtray-spec). Implementations of the “tray” side of this specification can be found e.g. in the GNOME 2 and KDE panel applications. Note that a GtkStatusIcon is not a widget, but just a #GObject. Making it a widget would be impractical, since the system tray on Windows doesn’t allow to embed arbitrary widgets. GtkStatusIcon has been deprecated in 3.14. You should consider using notifications or more modern platform-specific APIs instead. GLib provides the #GNotification API which works well with #GtkApplication on multiple platforms and environments, and should be the preferred mechanism to notify the users of transient status updates. See this [HowDoI](https://wiki.gnome.org/HowDoI/GNotification) for code examples. Creates an empty status icon object. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon Creates a status icon displaying the file @filename. The image will be scaled down to fit in the available space in the notification area, if necessary. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a filename Creates a status icon displaying a #GIcon. If the icon is a themed icon, it will be updated when the theme changes. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a #GIcon Creates a status icon displaying an icon from the current icon theme. If the current icon theme is changed, the icon will be updated appropriately. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon an icon name Creates a status icon displaying @pixbuf. The image will be scaled down to fit in the available space in the notification area, if necessary. Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a #GdkPixbuf Creates a status icon displaying a stock icon. Sample stock icon names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. You can register your own stock icon names, see gtk_icon_factory_add_default() and gtk_icon_factory_add(). Use #GNotification and #GtkApplication to provide status notifications a new #GtkStatusIcon a stock icon id Menu positioning function to use with gtk_menu_popup() to position @menu aligned to the status icon @user_data. Use #GNotification and #GtkApplication to provide status notifications; notifications do not have menus, but can have buttons, and actions associated with each button the #GtkMenu return location for the x position return location for the y position whether the first menu item should be offset (pushed in) to be aligned with the menu popup position (only useful for GtkOptionMenu). the status icon to position the menu on Obtains information about the location of the status icon on screen. This information can be used to e.g. position popups like notification bubbles. See gtk_status_icon_position_menu() for a more convenient alternative for positioning menus. Note that some platforms do not allow GTK+ to provide this information, and even on platforms that do allow it, the information is not reliable unless the status icon is embedded in a notification area, see gtk_status_icon_is_embedded(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as the platform is responsible for the presentation of notifications %TRUE if the location information has been filled in a #GtkStatusIcon return location for the screen, or %NULL if the information is not needed return location for the area occupied by the status icon, or %NULL return location for the orientation of the panel in which the status icon is embedded, or %NULL. A panel at the top or bottom of the screen is horizontal, a panel at the left or right is vertical. Retrieves the #GIcon being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see gtk_status_icon_get_storage_type()). The caller of this function does not own a reference to the returned #GIcon. If this function fails, @icon is left unchanged; Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the displayed icon, or %NULL if the image is empty a #GtkStatusIcon Returns the current value of the has-tooltip property. See #GtkStatusIcon:has-tooltip for more information. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function current value of has-tooltip on @status_icon. a #GtkStatusIcon Gets the name of the icon being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see gtk_status_icon_get_storage_type()). The returned string is owned by the #GtkStatusIcon and should not be freed or modified. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function name of the displayed icon, or %NULL if the image is empty. a #GtkStatusIcon Gets the #GdkPixbuf being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PIXBUF (see gtk_status_icon_get_storage_type()). The caller of this function does not own a reference to the returned pixbuf. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the displayed pixbuf, or %NULL if the image is empty. a #GtkStatusIcon Returns the #GdkScreen associated with @status_icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as notifications are managed by the platform a #GdkScreen. a #GtkStatusIcon Gets the size in pixels that is available for the image. Stock icons and named icons adapt their size automatically if the size of the notification area changes. For other storage types, the size-changed signal can be used to react to size changes. Note that the returned size is only meaningful while the status icon is embedded (see gtk_status_icon_is_embedded()). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as the representation of a notification is left to the platform the size that is available for the image a #GtkStatusIcon Gets the id of the stock icon being displayed by the #GtkStatusIcon. The storage type of the status icon must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_STOCK (see gtk_status_icon_get_storage_type()). The returned string is owned by the #GtkStatusIcon and should not be freed or modified. Use gtk_status_icon_get_icon_name() instead. stock id of the displayed stock icon, or %NULL if the image is empty. a #GtkStatusIcon Gets the type of representation being used by the #GtkStatusIcon to store image data. If the #GtkStatusIcon has no image data, the return value will be %GTK_IMAGE_EMPTY. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, and #GNotification only supports #GIcon instances the image representation being used a #GtkStatusIcon Gets the title of this tray icon. See gtk_status_icon_set_title(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the title of the status icon a #GtkStatusIcon Gets the contents of the tooltip for @status_icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkStatusIcon Gets the contents of the tooltip for @status_icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkStatusIcon Returns whether the status icon is visible or not. Note that being visible does not guarantee that the user can actually see the icon, see also gtk_status_icon_is_embedded(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function %TRUE if the status icon is visible a #GtkStatusIcon This function is only useful on the X11/freedesktop.org platform. It returns a window ID for the widget in the underlying status icon implementation. This is useful for the Galago notification service, which can send a window ID in the protocol in order for the server to position notification windows pointing to a status icon reliably. This function is not intended for other use cases which are more likely to be met by one of the non-X11 specific methods, such as gtk_status_icon_position_menu(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function An 32 bit unsigned integer identifier for the underlying X11 Window a #GtkStatusIcon Returns whether the status icon is embedded in a notification area. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function %TRUE if the status icon is embedded in a notification area. a #GtkStatusIcon Makes @status_icon display the file @filename. See gtk_status_icon_new_from_file() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon a filename Makes @status_icon display the #GIcon. See gtk_status_icon_new_from_gicon() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon a GIcon Makes @status_icon display the icon named @icon_name from the current icon theme. See gtk_status_icon_new_from_icon_name() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon an icon name Makes @status_icon display @pixbuf. See gtk_status_icon_new_from_pixbuf() for details. Use #GNotification and #GtkApplication to provide status notifications; you can use g_notification_set_icon() to associate a #GIcon with a notification a #GtkStatusIcon a #GdkPixbuf or %NULL Makes @status_icon display the stock icon with the id @stock_id. See gtk_status_icon_new_from_stock() for details. Use gtk_status_icon_set_from_icon_name() instead. a #GtkStatusIcon a stock icon id Sets the has-tooltip property on @status_icon to @has_tooltip. See #GtkStatusIcon:has-tooltip for more information. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, but notifications can display an arbitrary amount of text using g_notification_set_body() a #GtkStatusIcon whether or not @status_icon has a tooltip Sets the name of this tray icon. This should be a string identifying this icon. It is may be used for sorting the icons in the tray and will not be shown to the user. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as notifications are associated with a unique application identifier by #GApplication a #GtkStatusIcon the name Sets the #GdkScreen where @status_icon is displayed; if the icon is already mapped, it will be unmapped, and then remapped on the new screen. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as GTK typically only has one #GdkScreen and notifications are managed by the platform a #GtkStatusIcon a #GdkScreen Sets the title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon. Use #GNotification and #GtkApplication to provide status notifications; you should use g_notification_set_title() and g_notification_set_body() to present text inside your notification a #GtkStatusIcon the title 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 #GtkStatusIcon:has-tooltip to %TRUE and of the default handler for the #GtkStatusIcon::query-tooltip signal. See also the #GtkStatusIcon:tooltip-markup property and gtk_tooltip_set_markup(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function a #GtkStatusIcon the contents of the tooltip for @status_icon, or %NULL Sets @text as the contents of the tooltip. This function will take care of setting #GtkStatusIcon:has-tooltip to %TRUE and of the default handler for the #GtkStatusIcon::query-tooltip signal. See also the #GtkStatusIcon:tooltip-text property and gtk_tooltip_set_text(). Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function a #GtkStatusIcon the contents of the tooltip for @status_icon Shows or hides a status icon. Use #GNotification and #GtkApplication to provide status notifications; there is no direct replacement for this function, as notifications are managed by the platform a #GtkStatusIcon %TRUE to show the status icon, %FALSE to hide it %TRUE if the statusicon is embedded in a notification area. The #GIcon displayed in the #GtkStatusIcon. For themed icons, the image will be updated automatically if the theme changes. Enables or disables the emission of #GtkStatusIcon::query-tooltip on @status_icon. A value of %TRUE indicates that @status_icon can have a tooltip, in this case the status icon will be queried using #GtkStatusIcon::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 windows of this status icon to include leave-notify and motion-notify events. This will not be undone when the property is set to %FALSE again. Whether this property is respected is platform dependent. For plain text tooltips, use #GtkStatusIcon:tooltip-text in preference. The orientation of the tray in which the statusicon is embedded. Use #GtkStatusIcon:icon-name instead. The title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon. Sets the text of tooltip to be the given string, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_tooltip_set_markup(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL. #GtkStatusIcon:has-tooltip will automatically be set to %TRUE and the default handler for the #GtkStatusIcon::query-tooltip signal will take care of displaying the tooltip. On some platforms, embedded markup will be ignored. Sets the text of tooltip to be the given string. Also see gtk_tooltip_set_text(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL. #GtkStatusIcon:has-tooltip will automatically be set to %TRUE and the default handler for the #GtkStatusIcon::query-tooltip signal will take care of displaying the tooltip. Note that some platforms have limitations on the length of tooltips that they allow on status icons, e.g. Windows only shows the first 64 characters. Gets emitted when the user activates the status icon. If and how status icons can activated is platform-dependent. Unlike most G_SIGNAL_ACTION signals, this signal is meant to be used by applications and should be wrapped by language bindings. The ::button-press-event signal will be emitted when a button (typically from a mouse) is pressed. Whether this event is emitted is platform-dependent. Use the ::activate and ::popup-menu signals in preference. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal The ::button-release-event signal will be emitted when a button (typically from a mouse) is released. Whether this event is emitted is platform-dependent. Use the ::activate and ::popup-menu signals in preference. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal Gets emitted when the user brings up the context menu of the status icon. Whether status icons can have context menus and how these are activated is platform-dependent. The @button and @activate_time parameters should be passed as the last to arguments to gtk_menu_popup(). Unlike most G_SIGNAL_ACTION signals, this signal is meant to be used by applications and should be wrapped by language bindings. the button that was pressed, or 0 if the signal is not emitted in response to a button press event the timestamp of the event that triggered the signal emission Emitted when the hover timeout has expired with the cursor hovering above @status_icon; or emitted when @status_icon got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @status_icon. 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. Whether this signal is emitted is platform-dependent. For plain text tooltips, use #GtkStatusIcon:tooltip-text in preference. %TRUE if @tooltip should be shown right now, %FALSE otherwise. the x coordinate of the cursor position where the request has been emitted, relative to @status_icon the y coordinate of the cursor position where the request has been emitted, relative to @status_icon %TRUE if the tooltip was trigged using the keyboard a #GtkTooltip 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. Whether this event is emitted is platform-dependent. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventScroll which triggered this signal Gets emitted when the size available for the image changes, e.g. because the notification area got resized. %TRUE if the icon was updated for the new size. Otherwise, GTK+ will scale the icon as necessary. the new size A #GtkStatusbar is usually placed along the bottom of an application's main #GtkWindow. 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 gtk_statusbar_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 gtk_statusbar_new(). Messages are added to the bar’s stack with gtk_statusbar_push(). The message at the top of the stack can be removed using gtk_statusbar_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 gtk_statusbar_remove(). # CSS node GtkStatusbar has a single CSS node with name statusbar. Creates a new #GtkStatusbar ready for messages. the new #GtkStatusbar Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI. an integer id a #GtkStatusbar textual description of what context the new message is being used in Retrieves the box containing the label widget. a #GtkBox a #GtkStatusbar Removes the first message in the #GtkStatusbar’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. a #GtkStatusbar a context identifier Pushes a new message onto a statusbar’s stack. a message id that can be used with gtk_statusbar_remove(). a #GtkStatusbar the message’s context id, as returned by gtk_statusbar_get_context_id() the message to add to the statusbar Forces the removal of a message from a statusbar’s stack. The exact @context_id and @message_id must be specified. a #GtkStatusbar a context identifier a message identifier, as returned by gtk_statusbar_push() Forces the removal of all messages from a statusbar's stack with the exact @context_id. a #GtkStatusbar a context identifier Is emitted whenever a new message is popped off a statusbar's stack. the context id of the relevant message/statusbar the message that was just popped Is emitted whenever a new message gets pushed onto a statusbar's stack. the context id of the relevant message/statusbar the message that was pushed Identifier. User visible label. Modifier type for keyboard accelerator Keyboard accelerator Translation domain of the menu or toolbar item Copies a stock item, mostly useful for language bindings and not in applications. a new #GtkStockItem a #GtkStockItem Frees a stock item allocated on the heap, such as one returned by gtk_stock_item_copy(). Also frees the fields inside the stock item, if they are not %NULL. a #GtkStockItem A #GtkStyle object encapsulates the information that provides the look and feel for a widget. > In GTK+ 3.0, GtkStyle has been deprecated and replaced by > #GtkStyleContext. Each #GtkWidget has an associated #GtkStyle object that is used when rendering that widget. Also, a #GtkStyle holds information for the five possible widget states though not every widget supports all five states; see #GtkStateType. Usually the #GtkStyle for a widget is the same as the default style that is set by GTK+ and modified the theme engine. Usually applications should not need to use or modify the #GtkStyle of their widgets. Creates a new #GtkStyle. Use #GtkStyleContext a new #GtkStyle. Renders the icon specified by @source at the given @size according to the given parameters and returns the result in a pixbuf. Use gtk_render_icon_pixbuf() instead a newly-created #GdkPixbuf containing the rendered icon a #GtkStyle the #GtkIconSource specifying the icon to render a text direction a state the size to render the icon at (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the widget a style detail Sets the background of @window to the background color or pixmap specified by @style for the given state. Use gtk_style_context_set_background() instead a #GtkStyle a #GdkWindow a state Use #GtkStyleContext instead Attaches a style to a window; this process allocates the colors and creates the GC’s for the style - it specializes it to a particular visual. The process may involve the creation of a new style if the style has already been attached to a window with a different style and visual. Since this function may return a new object, you have to use it in the following way: `style = gtk_style_attach (style, window)` Use gtk_widget_style_attach() instead Either @style, or a newly-created #GtkStyle. If the style is newly created, the style parameter will be unref'ed, and the new style will have a reference count belonging to the caller. a #GtkStyle. a #GdkWindow. Creates a copy of the passed in #GtkStyle object. Use #GtkStyleContext instead a copy of @style a #GtkStyle Detaches a style from a window. If the style is not attached to any windows anymore, it is unrealized. See gtk_style_attach(). Use #GtkStyleContext instead a #GtkStyle Gets the values of a multiple style properties for @widget_type from @style. a #GtkStyle the #GType of a descendant of #GtkWidget the name of the first style property to get pairs of property names and locations to return the property values, starting with the location for @first_property_name, terminated by %NULL. Queries the value of a style property corresponding to a widget class is in the given style. a #GtkStyle the #GType of a descendant of #GtkWidget the name of the style property to get a #GValue where the value of the property being queried will be stored Non-vararg variant of gtk_style_get(). Used primarily by language bindings. a #GtkStyle the #GType of a descendant of #GtkWidget the name of the first style property to get a va_list of pairs of property names and locations to return the property values, starting with the location for @first_property_name. Returns whether @style has an associated #GtkStyleContext. %TRUE if @style has a #GtkStyleContext a #GtkStyle Looks up @color_name in the style’s logical color mappings, filling in @color and returning %TRUE if found, otherwise returning %FALSE. Do not cache the found mapping, because it depends on the #GtkStyle and might change when a theme switch occurs. Use gtk_style_context_lookup_color() instead %TRUE if the mapping was found. a #GtkStyle the name of the logical color to look up the #GdkColor to fill in Looks up @stock_id in the icon factories associated with @style and the default icon factory, returning an icon set if found, otherwise %NULL. Use gtk_style_context_lookup_icon_set() instead icon set of @stock_id a #GtkStyle an icon name Renders the icon specified by @source at the given @size according to the given parameters and returns the result in a pixbuf. Use gtk_render_icon_pixbuf() instead a newly-created #GdkPixbuf containing the rendered icon a #GtkStyle the #GtkIconSource specifying the icon to render a text direction a state the size to render the icon at (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the widget a style detail Sets the background of @window to the background color or pixmap specified by @style for the given state. Use gtk_style_context_set_background() instead a #GtkStyle a #GdkWindow a state Set of foreground #GdkColor Set of background #GdkColor Set of light #GdkColor Set of dark #GdkColor Set of mid #GdkColor Set of text #GdkColor Set of base #GdkColor Color halfway between text/base #GdkColor to use for black #GdkColor to use for white #PangoFontDescription Thickness in X direction Thickness in Y direction Set of background #cairo_pattern_t Emitted when the style has been initialized for a particular visual. Connecting to this signal is probably seldom useful since most of the time applications and widgets only deal with styles that have been already realized. Emitted when the aspects of the style specific to a particular visual is being cleaned up. A connection to this signal can be useful if a widget wants to cache objects as object data on #GtkStyle. This signal provides a convenient place to free such cached objects. The parent class. a #GtkStyle a #GdkWindow a state a newly-created #GdkPixbuf containing the rendered icon a #GtkStyle the #GtkIconSource specifying the icon to render a text direction a state the size to render the icon at (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale. the widget a style detail #GtkStyleContext is an object that stores styling information affecting a widget defined by #GtkWidgetPath. In order to construct the final style information, #GtkStyleContext queries information from all attached #GtkStyleProviders. Style providers can be either attached explicitly to the context through gtk_style_context_add_provider(), or to the screen through gtk_style_context_add_provider_for_screen(). The resulting style is a combination of all providers’ information in priority order. For GTK+ widgets, any #GtkStyleContext returned by gtk_widget_get_style_context() will already have a #GtkWidgetPath, a #GdkScreen 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 gtk_style_context_set_path() and possibly gtk_style_context_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 #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a #GtkCssProvider or a custom object implementing the #GtkStyleProvider 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 #GtkStyleProvider 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. Creates a standalone #GtkStyleContext, this style context won’t be attached to any widget, so you may want to call gtk_style_context_set_path() yourself. This function is only useful when using the theming layer separated from GTK+, if you are using #GtkStyleContext to theme #GtkWidgets, use gtk_widget_get_style_context() in order to get a style context ready to theme the widget. A newly created #GtkStyleContext. 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 #GtkSettings available. Note: If both priorities are the same, A #GtkStyleProvider added through gtk_style_context_add_provider() takes precedence over another added through this function. a #GdkScreen a #GtkStyleProvider 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 Removes @provider from the global style providers list in @screen. a #GdkScreen a #GtkStyleProvider This function recomputes the styles for all widgets under a particular #GdkScreen. 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 #GtkSettings object. a #GdkScreen Adds a style class to @context, so posterior calls to gtk_style_context_get() or any of the gtk_render_*() functions will make use of this new class for styling. In the CSS file format, a #GtkEntry defining a “search” class, would be matched by: |[ <!-- language="CSS" --> entry.search { ... } ]| While any widget defining a “search” class would be matched by: |[ <!-- language="CSS" --> .search { ... } ]| a #GtkStyleContext class name to use in styling Adds a style provider to @context, to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which @context belongs. If you want to affect the style of all widgets, use gtk_style_context_add_provider_for_screen(). Note: If both priorities are the same, a #GtkStyleProvider added through this function takes precedence over another added through gtk_style_context_add_provider_for_screen(). a #GtkStyleContext a #GtkStyleProvider 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 Adds a region to @context, so posterior calls to gtk_style_context_get() or any of the gtk_render_*() functions will make use of this new region for styling. In the CSS file format, a #GtkTreeView defining a “row” region, would be matched by: |[ <!-- language="CSS" --> treeview row { ... } ]| Pseudo-classes are used for matching @flags, so the two following rules: |[ <!-- language="CSS" --> treeview row:nth-child(even) { ... } treeview row:nth-child(odd) { ... } ]| would apply to even and odd rows, respectively. Region names must only contain lowercase letters and “-”, starting always with a lowercase letter. a #GtkStyleContext region name to use in styling flags that apply to the region Stops all running animations for @region_id and all animatable regions underneath. A %NULL @region_id will stop all ongoing animations in @context, when dealing with a #GtkStyleContext obtained through gtk_widget_get_style_context(), this is normally done for you in all circumstances you would expect all widget to be stopped, so this should be only used in complex widgets with different animatable regions. This function does nothing. a #GtkStyleContext animatable region to stop, or %NULL. See gtk_style_context_push_animatable_region() Retrieves several style property values from @context for a given state. See gtk_style_context_get_property() for details. a #GtkStyleContext state to retrieve the property values for property name /return value pairs, followed by %NULL 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 gtk_style_context_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. Use gtk_render_background() instead. a #GtkStyleContext state to retrieve the color for return value for the background color Gets the border for a given state as a #GtkBorder. See gtk_style_context_get_property() and #GTK_STYLE_PROPERTY_BORDER_WIDTH for details. a #GtkStyleContext state to retrieve the border for return value for the border settings Gets the border color for a given state. Use gtk_render_frame() instead. a #GtkStyleContext state to retrieve the color for return value for the border color Gets the foreground color for a given state. See gtk_style_context_get_property() and #GTK_STYLE_PROPERTY_COLOR for details. a #GtkStyleContext state to retrieve the color for return value for the foreground color Returns the widget direction used for rendering. Use gtk_style_context_get_state() and check for #GTK_STATE_FLAG_DIR_LTR and #GTK_STATE_FLAG_DIR_RTL instead. the widget direction a #GtkStyleContext Returns the font description for a given state. The returned object is const and will remain valid until the #GtkStyleContext::changed signal happens. Use gtk_style_context_get() for "font" or subproperties instead. the #PangoFontDescription for the given state. This object is owned by GTK+ and should not be freed. a #GtkStyleContext state to retrieve the font for Returns the #GdkFrameClock to which @context is attached. a #GdkFrameClock, or %NULL if @context does not have an attached frame clock. a #GtkStyleContext Returns the sides where rendered elements connect visually with others. the junction sides a #GtkStyleContext Gets the margin for a given state as a #GtkBorder. See gtk_style_property_get() and #GTK_STYLE_PROPERTY_MARGIN for details. a #GtkStyleContext state to retrieve the border for return value for the margin settings Gets the padding for a given state as a #GtkBorder. See gtk_style_context_get() and #GTK_STYLE_PROPERTY_PADDING for details. a #GtkStyleContext state to retrieve the padding for return value for the padding settings Gets the parent context set via gtk_style_context_set_parent(). See that function for details. the parent context or %NULL a #GtkStyleContext Returns the widget path used for style matching. A #GtkWidgetPath a #GtkStyleContext Gets a style property from @context 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 #GValue. 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 @context is not recommended unless the style context has been saved with gtk_style_context_save(). When @value is no longer needed, g_value_unset() must be called to free any allocated memory. a #GtkStyleContext style property name state to retrieve the property value for return location for the style property value Returns the scale used for assets. the scale a #GtkStyleContext Returns the #GdkScreen to which @context is attached. a #GdkScreen. a #GtkStyleContext Queries the location in the CSS where @property was defined for the current @context. Note that the state to be queried is taken from gtk_style_context_get_state(). If the location is not available, %NULL 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 %NULL. %NULL or the section where a value for @property was defined a #GtkStyleContext style property name Returns the state used for style matching. This method should only be used to retrieve the #GtkStateFlags to pass to #GtkStyleContext methods, like gtk_style_context_get_padding(). If you need to retrieve the current state of a #GtkWidget, use gtk_widget_get_state_flags(). the state flags a #GtkStyleContext Retrieves several widget style properties from @context according to the current style. a #GtkStyleContext property name /return value pairs, followed by %NULL Gets the value for a widget style property. When @value is no longer needed, g_value_unset() must be called to free any allocated memory. a #GtkStyleContext the name of the widget style property Return location for the property value Retrieves several widget style properties from @context according to the current style. a #GtkStyleContext va_list of property name/return location pairs, followed by %NULL Retrieves several style property values from @context for a given state. See gtk_style_context_get_property() for details. a #GtkStyleContext state to retrieve the property values for va_list of property name/return location pairs, followed by %NULL Returns %TRUE if @context currently has defined the given class name. %TRUE if @context has @class_name defined a #GtkStyleContext a class name Returns %TRUE if @context has the region defined. If @flags_return is not %NULL, it is set to the flags affecting the region. %TRUE if region is defined a #GtkStyleContext a region name return location for region flags Invalidates @context style information, so it will be reconstructed again. It is useful if you modify the @context and need the new information immediately. Style contexts are invalidated automatically. a #GtkStyleContext. Returns the list of classes currently defined in @context. a #GList of strings with the currently defined classes. The contents of the list are owned by GTK+, but you must free the list itself with g_list_free() when you are done with it. a #GtkStyleContext Returns the list of regions currently defined in @context. a #GList of strings with the currently defined regions. The contents of the list are owned by GTK+, but you must free the list itself with g_list_free() when you are done with it. a #GtkStyleContext Looks up and resolves a color name in the @context color map. %TRUE if @color_name was found and resolved, %FALSE otherwise a #GtkStyleContext color name to lookup Return location for the looked up color Looks up @stock_id in the icon factories associated to @context and the default icon factory, returning an icon set if found, otherwise %NULL. Use gtk_icon_theme_lookup_icon() instead. The looked up %GtkIconSet, or %NULL a #GtkStyleContext an icon name Notifies a state change on @context, so if the current style makes use of transition animations, one will be started so all rendered elements under @region_id are animated for state @state being set to value @state_value. The @window parameter is used in order to invalidate the rendered area as the animation runs, so make sure it is the same window that is being rendered on by the gtk_render_*() functions. If @region_id is %NULL, all rendered elements using @context will be affected by this state transition. As a practical example, a #GtkButton notifying a state transition on the prelight state: |[ <!-- language="C" --> gtk_style_context_notify_state_change (context, gtk_widget_get_window (widget), NULL, GTK_STATE_PRELIGHT, button->in_button); ]| Can be handled in the CSS file like this: |[ <!-- language="CSS" --> button { background-color: #f00 } button:hover { background-color: #fff; transition: 200ms linear } ]| This combination will animate the button background from red to white if a pointer enters the button, and back to red if the pointer leaves the button. Note that @state is used when finding the transition parameters, which is why the style places the transition under the :hover pseudo-class. This function does nothing. a #GtkStyleContext a #GdkWindow animatable region to notify on, or %NULL. See gtk_style_context_push_animatable_region() state to trigger transition for %TRUE if @state is the state we are changing to, %FALSE if we are changing away from it Pops an animatable region from @context. See gtk_style_context_push_animatable_region(). This function does nothing. a #GtkStyleContext Pushes an animatable region, so all further gtk_render_*() calls between this call and the following gtk_style_context_pop_animatable_region() will potentially show transition animations for this region if gtk_style_context_notify_state_change() is called for a given state, and the current theme/style defines transition animations for state changes. The @region_id used must be unique in @context so the themes can uniquely identify rendered elements subject to a state transition. This function does nothing. a #GtkStyleContext unique identifier for the animatable region Removes @class_name from @context. a #GtkStyleContext class name to remove Removes @provider from the style providers list in @context. a #GtkStyleContext a #GtkStyleProvider Removes a region from @context. a #GtkStyleContext region name to unset Restores @context state to a previous stage. See gtk_style_context_save(). a #GtkStyleContext Saves the @context state, so temporary modifications done through gtk_style_context_add_class(), gtk_style_context_remove_class(), gtk_style_context_set_state(), etc. can quickly be reverted in one go through gtk_style_context_restore(). The matching call to gtk_style_context_restore() must be done before GTK returns to the main loop. a #GtkStyleContext This function is analogous to gdk_window_scroll(), and should be called together with it so the invalidation areas for any ongoing animation are scrolled together with it. This function does nothing. a #GtkStyleContext a #GdkWindow used previously in gtk_style_context_notify_state_change() Amount to scroll in the X axis Amount to scroll in the Y axis Sets the background of @window to the background pattern or color specified in @context for its current state. Use gtk_render_background() instead. Note that clients still using this function are now responsible for calling this function again whenever @context is invalidated. a #GtkStyleContext a #GdkWindow Sets the reading direction for rendering purposes. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. Use gtk_style_context_set_state() with #GTK_STATE_FLAG_DIR_LTR and #GTK_STATE_FLAG_DIR_RTL instead. a #GtkStyleContext the new direction. Attaches @context to the given frame clock. The frame clock is used for the timing of animations. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. a #GdkFrameClock a #GdkFrameClock 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. a #GtkStyleContext sides where rendered elements are visually connected to other elements Sets the parent style context for @context. The parent style context is used to implement [inheritance](http://www.w3.org/TR/css3-cascade/#inheritance) of properties. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), the parent will be set for you. a #GtkStyleContext the new parent or %NULL Sets the #GtkWidgetPath used for style matching. As a consequence, the style will be regenerated to match the new given path. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. a #GtkStyleContext a #GtkWidgetPath Sets the scale to use when getting image assets for the style. a #GtkStyleContext scale Attaches @context to the given screen. The screen is used to add style information from “global” style providers, such as the screen’s #GtkSettings instance. If you are using a #GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself. a #GtkStyleContext a #GdkScreen Sets the state to be used for style matching. a #GtkStyleContext state to represent Returns %TRUE if there is a transition animation running for the current region (see gtk_style_context_push_animatable_region()). If @progress is not %NULL, the animation progress will be returned there, 0.0 means the state is closest to being unset, while 1.0 means it’s closest to being set. This means transition animation will run from 0 to 1 when @state is being set and from 1 to 0 when it’s being unset. This function always returns %FALSE %TRUE if there is a running transition animation for @state. a #GtkStyleContext a widget state return location for the transition progress 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 @context. 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. a newly allocated string representing @context a #GtkStyleContext Flags that determine what to print Sets or gets the style context’s parent. See gtk_style_context_set_parent() for details. The ::changed signal is emitted when there is a change in the #GtkStyleContext. For a #GtkStyleContext returned by gtk_widget_get_style_context(), the #GtkWidget::style-updated signal/vfunc might be more convenient to use. This signal is useful when using the theming layer standalone. Flags that modify the behavior of gtk_style_context_to_string(). New values may be added to this enumeration. Print the entire tree of CSS nodes starting at the style context's node Show the values of the CSS properties for each node GtkStyleProperties provides the storage for style information that is used by #GtkStyleContext and other #GtkStyleProvider implementations. Before style properties can be stored in GtkStyleProperties, they must be registered with gtk_style_properties_register_property(). Unless you are writing a #GtkStyleProvider implementation, you are unlikely to use this API directly, as gtk_style_context_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 #GtkThemingEngine instead. #GtkStyleProperties has been deprecated in GTK 3.16. The CSS machinery does not use it anymore and all users of this object have been deprecated. Returns a newly created #GtkStyleProperties #GtkStyleProperties are deprecated. a new #GtkStyleProperties Returns %TRUE if a property has been registered, if @pspec or @parse_func are not %NULL, the #GParamSpec and parsing function will be respectively returned. This code could only look up custom properties and those are deprecated. %TRUE if the property is registered, %FALSE otherwise property name to look up return location for the parse function return location for the #GParamSpec Registers a property so it can be used in the CSS file format. This function is the low-level equivalent of gtk_theming_engine_register_property(), if you are implementing a theming engine, you want to use that function instead. Code should use the default properties provided by CSS. parsing function to use, or %NULL the #GParamSpec for the new property Clears all style information from @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties Retrieves several style property values from @props for a given state. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to retrieve the property values for property name /return value pairs, followed by %NULL Gets a style property from @props for the given state. When done with @value, g_value_unset() needs to be called to free any allocated memory. #GtkStyleProperties are deprecated. %TRUE if the property exists in @props, %FALSE otherwise a #GtkStyleProperties style property name state to retrieve the property value for return location for the style property value. Retrieves several style property values from @props for a given state. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to retrieve the property values for va_list of property name/return location pairs, followed by %NULL Returns the symbolic color that is mapped to @name. #GtkSymbolicColor is deprecated. The mapped color a #GtkStyleProperties color name to lookup Maps @color so it can be referenced by @name. See gtk_style_properties_lookup_color() #GtkSymbolicColor is deprecated. a #GtkStyleProperties color name #GtkSymbolicColor to map @name to Merges into @props 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. #GtkStyleProperties are deprecated. a #GtkStyleProperties a second #GtkStyleProperties whether to replace values or not Sets several style properties on @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to set the values for property name/value pairs, followed by %NULL Sets a styling property in @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties styling property to set state to set the value for new value for the property Sets several style properties on @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties state to set the values for va_list of property name/value pairs, followed by %NULL Unsets a style property in @props. #GtkStyleProperties are deprecated. a #GtkStyleProperties property to unset state to unset GtkStyleProvider is an interface used to provide style information to a #GtkStyleContext. See gtk_style_context_add_provider() and gtk_style_context_add_provider_for_screen(). Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none is defined. Will always return %NULL for all GTK-provided style providers. The icon factory to use for @path, or %NULL a #GtkStyleProvider #GtkWidgetPath to query Returns the style settings affecting a widget defined by @path, or %NULL if @provider doesn’t contemplate styling @path. Will always return %NULL for all GTK-provided style providers as the interface cannot correctly work the way CSS is specified. a #GtkStyleProperties containing the style settings affecting @path a #GtkStyleProvider #GtkWidgetPath to query Looks up a widget style property as defined by @provider for the widget represented by @path. %TRUE if the property was found and has a value, %FALSE otherwise a #GtkStyleProvider #GtkWidgetPath to query state to query the style property for The #GParamSpec to query return location for the property value Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none is defined. Will always return %NULL for all GTK-provided style providers. The icon factory to use for @path, or %NULL a #GtkStyleProvider #GtkWidgetPath to query Returns the style settings affecting a widget defined by @path, or %NULL if @provider doesn’t contemplate styling @path. Will always return %NULL for all GTK-provided style providers as the interface cannot correctly work the way CSS is specified. a #GtkStyleProperties containing the style settings affecting @path a #GtkStyleProvider #GtkWidgetPath to query Looks up a widget style property as defined by @provider for the widget represented by @path. %TRUE if the property was found and has a value, %FALSE otherwise a #GtkStyleProvider #GtkWidgetPath to query state to query the style property for The #GParamSpec to query return location for the property value a #GtkStyleProperties containing the style settings affecting @path a #GtkStyleProvider #GtkWidgetPath to query %TRUE if the property was found and has a value, %FALSE otherwise a #GtkStyleProvider #GtkWidgetPath to query state to query the style property for The #GParamSpec to query return location for the property value The icon factory to use for @path, or %NULL a #GtkStyleProvider #GtkWidgetPath to query #GtkSwitch 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. GtkSwitch can also handle situations where the underlying state changes with a delay. See #GtkSwitch::state-set for details. # CSS nodes |[<!-- language="plain" --> switch ╰── slider ]| GtkSwitch has two css nodes, the main node with the name switch and a subnode named slider. Neither of them is using any style classes. Creates a new #GtkSwitch widget. the newly created #GtkSwitch instance Gets whether the #GtkSwitch is in its “on” or “off” state. %TRUE if the #GtkSwitch is active, and %FALSE otherwise a #GtkSwitch Gets the underlying state of the #GtkSwitch. the underlying state a #GtkSwitch Changes the state of @sw to the desired one. a #GtkSwitch %TRUE if @sw should be active, and %FALSE otherwise Sets the underlying state of the #GtkSwitch. Normally, this is the same as #GtkSwitch:active, unless the switch is set up for delayed state changes. This function is typically called from a #GtkSwitch::state-set signal handler. See #GtkSwitch::state-set for details. a #GtkSwitch the new state Whether the #GtkSwitch widget is in its on or off state. The backend state that is controlled by the switch. See #GtkSwitch::state-set for details. The ::activate signal on GtkSwitch 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. The ::state-set signal on GtkSwitch 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 #GtkSwitch:active property. To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call gtk_switch_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 #GtkSwitch:active property is represented by the position of the switch. %TRUE to stop the signal emission the new state of the switch The parent class. GtkSymbolicColor is a boxed type that represents a symbolic color. It is the result of parsing a [color expression][gtkcssprovider-symbolic-colors]. To obtain the color represented by a GtkSymbolicColor, it has to be resolved with gtk_symbolic_color_resolve(), which replaces all symbolic color references by the colors they refer to (in a given context) and evaluates mix, shade and other expressions, resulting in a #GdkRGBA value. It is not normally necessary to deal directly with #GtkSymbolicColors, since they are mostly used behind the scenes by #GtkStyleContext and #GtkCssProvider. #GtkSymbolicColor is deprecated. Symbolic colors are considered an implementation detail of GTK+. Creates a symbolic color by modifying the relative alpha value of @color. A factor < 1.0 would resolve to a more transparent color, while > 1.0 would resolve to a more opaque color. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor another #GtkSymbolicColor factor to apply to @color alpha Creates a symbolic color pointing to a literal color. #GtkSymbolicColor is deprecated. a newly created #GtkSymbolicColor a #GdkRGBA Creates a symbolic color defined as a mix of another two colors. a mix factor of 0 would resolve to @color1, while a factor of 1 would resolve to @color2. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor color to mix another color to mix mix factor Creates a symbolic color pointing to an unresolved named color. See gtk_style_context_lookup_color() and gtk_style_properties_lookup_color(). #GtkSymbolicColor is deprecated. a newly created #GtkSymbolicColor color name Creates a symbolic color defined as a shade of another color. A factor > 1.0 would resolve to a brighter color, while < 1.0 would resolve to a darker color. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor another #GtkSymbolicColor shading factor to apply to @color Creates a symbolic color based on the current win32 theme. Note that while this call is available on all platforms the actual value returned is not reliable on non-win32 platforms. #GtkSymbolicColor is deprecated. A newly created #GtkSymbolicColor The theme class to pull color from The color id Increases the reference count of @color #GtkSymbolicColor is deprecated. the same @color a #GtkSymbolicColor If @color is resolvable, @resolved_color will be filled in with the resolved color, and %TRUE will be returned. Generally, if @color can’t be resolved, it is due to it being defined on top of a named color that doesn’t exist in @props. When @props is %NULL, resolving of named colors will fail, so if your @color is or references such a color, this function will return %FALSE. #GtkSymbolicColor is deprecated. %TRUE if the color has been resolved a #GtkSymbolicColor #GtkStyleProperties to use when resolving named colors, or %NULL return location for the resolved color Converts the given @color to a string representation. This is useful both for debugging and for serialization of strings. The format of the string may change between different versions of GTK, but it is guaranteed that the GTK css parser is able to read the string and create the same symbolic color from it. #GtkSymbolicColor is deprecated. a new string representing @color color to convert to a string Decreases the reference count of @color, freeing its memory if the reference count reaches 0. #GtkSymbolicColor is deprecated. a #GtkSymbolicColor The priority at which the text view validates onscreen lines in an idle job in the background. The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a #GtkTreeSortable use the default sort function. See also gtk_tree_sortable_set_sort_column_id() The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a #GtkTreeSortable use no sorting. See also gtk_tree_sortable_set_sort_column_id() The #GtkTable functions allow the programmer to arrange widgets in rows and columns, making it easy to align many widgets next to each other, horizontally and vertically. Tables are created with a call to gtk_table_new(), the size of which can later be changed with gtk_table_resize(). Widgets can be added to a table using gtk_table_attach() or the more convenient (but slightly less flexible) gtk_table_attach_defaults(). To alter the space next to a specific row, use gtk_table_set_row_spacing(), and for a column, gtk_table_set_col_spacing(). The gaps between all rows or columns can be changed by calling gtk_table_set_row_spacings() or gtk_table_set_col_spacings() respectively. Note that spacing is added between the children, while padding added by gtk_table_attach() is added on either side of the widget it belongs to. gtk_table_set_homogeneous(), can be used to set whether all cells in the table will resize themselves to the size of the largest widget in the table. > #GtkTable has been deprecated. Use #GtkGrid instead. It provides the same > capabilities as GtkTable for arranging widgets in a rectangular grid, but > does support height-for-width geometry management. Used to create a new table widget. An initial size must be given by specifying how many rows and columns the table should have, although this can be changed later with gtk_table_resize(). @rows and @columns must both be in the range 1 .. 65535. For historical reasons, 0 is accepted as well and is silently interpreted as 1. Use gtk_grid_new(). A pointer to the newly created table widget. The number of rows the new table should have. The number of columns the new table should have. If set to %TRUE, all table cells are resized to the size of the cell containing the largest widget. Adds a widget to a table. The number of “cells” that a widget will occupy is specified by @left_attach, @right_attach, @top_attach and @bottom_attach. These each represent the leftmost, rightmost, uppermost and lowest column and row numbers of the table. (Columns and rows are indexed from zero). To make a button occupy the lower right cell of a 2x2 table, use |[ gtk_table_attach (table, button, 1, 2, // left, right attach 1, 2, // top, bottom attach xoptions, yoptions, xpadding, ypadding); ]| If you want to make the button span the entire bottom row, use @left_attach == 0 and @right_attach = 2 instead. Use gtk_grid_attach() with #GtkGrid. Note that the attach arguments differ between those two functions. The #GtkTable to add a new widget to. The widget to add. the column number to attach the left side of a child widget to. the column number to attach the right side of a child widget to. the row number to attach the top of a child widget to. the row number to attach the bottom of a child widget to. Used to specify the properties of the child widget when the table is resized. The same as xoptions, except this field determines behaviour of vertical resizing. An integer value specifying the padding on the left and right of the widget being added to the table. The amount of padding above and below the child widget. As there are many options associated with gtk_table_attach(), this convenience function provides the programmer with a means to add children to a table with identical padding and expansion options. The values used for the #GtkAttachOptions are `GTK_EXPAND | GTK_FILL`, and the padding is set to 0. Use gtk_grid_attach() with #GtkGrid. Note that the attach arguments differ between those two functions. The table to add a new child widget to. The child widget to add. The column number to attach the left side of the child widget to. The column number to attach the right side of the child widget to. The row number to attach the top of the child widget to. The row number to attach the bottom of the child widget to. Gets the amount of space between column @col, and column @col + 1. See gtk_table_set_col_spacing(). #GtkGrid does not offer a replacement for this functionality. the column spacing a #GtkTable a column in the table, 0 indicates the first column Gets the default column spacing for the table. This is the spacing that will be used for newly added columns. (See gtk_table_set_col_spacings()) Use gtk_grid_get_column_spacing() with #GtkGrid. the default column spacing a #GtkTable Gets the default row spacing for the table. This is the spacing that will be used for newly added rows. (See gtk_table_set_row_spacings()) Use gtk_grid_get_row_spacing() with #GtkGrid. the default row spacing a #GtkTable Returns whether the table cells are all constrained to the same width and height. (See gtk_table_set_homogeneous ()) Use gtk_grid_get_row_homogeneous() and gtk_grid_get_column_homogeneous() with #GtkGrid. %TRUE if the cells are all constrained to the same size a #GtkTable Gets the amount of space between row @row, and row @row + 1. See gtk_table_set_row_spacing(). #GtkGrid does not offer a replacement for this functionality. the row spacing a #GtkTable a row in the table, 0 indicates the first row Gets the number of rows and columns in the table. #GtkGrid does not expose the number of columns and rows. a #GtkTable return location for the number of rows, or %NULL return location for the number of columns, or %NULL If you need to change a table’s size after it has been created, this function allows you to do so. #GtkGrid resizes automatically. The #GtkTable you wish to change the size of. The new number of rows. The new number of columns. Alters the amount of space between a given table column and the following column. Use gtk_widget_set_margin_start() and gtk_widget_set_margin_end() on the widgets contained in the row if you need this functionality. #GtkGrid does not support per-row spacing. a #GtkTable. the column whose spacing should be changed. number of pixels that the spacing should take up. Sets the space between every column in @table equal to @spacing. Use gtk_grid_set_column_spacing() with #GtkGrid. a #GtkTable. the number of pixels of space to place between every column in the table. Changes the homogenous property of table cells, ie. whether all cells are an equal size or not. Use gtk_grid_set_row_homogeneous() and gtk_grid_set_column_homogeneous() with #GtkGrid. The #GtkTable you wish to set the homogeneous properties of. Set to %TRUE to ensure all table cells are the same size. Set to %FALSE if this is not your desired behaviour. Changes the space between a given table row and the subsequent row. Use gtk_widget_set_margin_top() and gtk_widget_set_margin_bottom() on the widgets contained in the row if you need this functionality. #GtkGrid does not support per-row spacing. a #GtkTable containing the row whose properties you wish to change. row number whose spacing will be changed. number of pixels that the spacing should take up. Sets the space between every row in @table equal to @spacing. Use gtk_grid_set_row_spacing() with #GtkGrid. a #GtkTable. the number of pixels of space to place between every row in the table. A #GtkTargetEntry 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. a string representation of the target type #GtkTargetFlags for DND an application-assigned integer ID which will get passed as a parameter to e.g the #GtkWidget::selection-get signal. It allows the application to identify the target type without extensive string compares. Makes a new #GtkTargetEntry. a pointer to a new #GtkTargetEntry. Free with gtk_target_entry_free() String identifier for target Set of flags, see #GtkTargetFlags an ID that will be passed back to the application Makes a copy of a #GtkTargetEntry and its data. a pointer to a copy of @data. Free with gtk_target_entry_free() a pointer to a #GtkTargetEntry Frees a #GtkTargetEntry returned from gtk_target_entry_new() or gtk_target_entry_copy(). a pointer to a #GtkTargetEntry. The #GtkTargetFlags enumeration is used to specify constraints on a #GtkTargetEntry. If this is set, the target will only be selected for drags within a single application. If this is set, the target will only be selected for drags within a single widget. If this is set, the target will not be selected for drags within a single application. If this is set, the target will not be selected for drags withing a single widget. A #GtkTargetList-struct is a reference counted list of #GtkTargetPair and should be treated as opaque. Creates a new #GtkTargetList from an array of #GtkTargetEntry. the new #GtkTargetList. Pointer to an array of #GtkTargetEntry number of entries in @targets. Appends another target to a #GtkTargetList. a #GtkTargetList the interned atom representing the target the flags for this target an ID that will be passed back to the application Appends the image targets supported by #GtkSelectionData to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application whether to add only targets for which GTK+ knows how to convert a pixbuf into the format Appends the rich text targets registered with gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_deserialize_format() to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application if %TRUE, then deserializable rich text formats will be added, serializable formats otherwise. a #GtkTextBuffer. Prepends a table of #GtkTargetEntry to a target list. a #GtkTargetList the table of #GtkTargetEntry number of targets in the table Appends the text targets supported by #GtkSelectionData to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application Appends the URI targets supported by #GtkSelectionData to the target list. All targets are added with the same @info. a #GtkTargetList an ID that will be passed back to the application Looks up a given target in a #GtkTargetList. %TRUE if the target was found, otherwise %FALSE a #GtkTargetList an interned atom representing the target to search for a pointer to the location to store application info for target, or %NULL Increases the reference count of a #GtkTargetList by one. the passed in #GtkTargetList. a #GtkTargetList Removes a target from a target list. a #GtkTargetList the interned atom representing the target Decreases the reference count of a #GtkTargetList by one. If the resulting reference count is zero, frees the list. a #GtkTargetList A #GtkTargetPair is used to represent the same information as a table of #GtkTargetEntry, but in an efficient form. #GdkAtom representation of the target type #GtkTargetFlags for DND an application-assigned integer ID which will get passed as a parameter to e.g the #GtkWidget::selection-get signal. It allows the application to identify the target type without extensive string compares. A #GtkTearoffMenuItem is a special #GtkMenuItem which is used to tear off and reattach its menu. When its menu is shown normally, the #GtkTearoffMenuItem is drawn as a dotted line indicating that the menu can be torn off. Activating it causes its menu to be torn off and displayed in its own window as a tearoff menu. When its menu is shown as a tearoff menu, the #GtkTearoffMenuItem is drawn as a dotted line which has a left pointing arrow graphic indicating that the tearoff menu can be reattached. Activating it will erase the tearoff menu window. > #GtkTearoffMenuItem is deprecated and should not be used in newly > written code. Menus are not meant to be torn around. Creates a new #GtkTearoffMenuItem. #GtkTearoffMenuItem is deprecated and should not be used in newly written code. a new #GtkTearoffMenuItem. The parent class. Background #GdkColor. Foreground #GdkColor. Super/subscript rise, can be negative. #PangoUnderline Strikethrough style Whether to use background-related values; this is irrelevant for the values struct when in a tag, but is used for the composite values struct; it’s true if any of the tags being composited had background stuff set. This are only used when we are actually laying out and rendering a paragraph; not when a #GtkTextAppearance is part of a #GtkTextAttributes. This are only used when we are actually laying out and rendering a paragraph; not when a #GtkTextAppearance is part of a #GtkTextAttributes. Using #GtkTextAttributes directly should rarely be necessary. It’s primarily useful with gtk_text_iter_get_attributes(). As with most GTK+ structs, the fields in this struct should only be read, never modified directly. #GtkTextAppearance for text. #GtkJustification for text. #GtkTextDirection for text. #PangoFontDescription for text. Font scale factor. Width of the left margin in pixels. Width of the right margin in pixels. Amount to indent the paragraph, in pixels. Pixels of blank space above paragraphs. Pixels of blank space below paragraphs. Pixels of blank space between wrapped lines in a paragraph. Custom #PangoTabArray for this text. #GtkWrapMode for text. #PangoLanguage for text. Hide the text. Background is fit to full line height rather than baseline +/- ascent/descent (font height). Can edit this text. Whether to disable font fallback. Extra space to insert between graphemes, in Pango units Creates a #GtkTextAttributes, which describes a set of properties on some text. a new #GtkTextAttributes, free with gtk_text_attributes_unref(). Copies @src and returns a new #GtkTextAttributes. a copy of @src, free with gtk_text_attributes_unref() a #GtkTextAttributes to be copied Copies the values from @src to @dest so that @dest has the same values as @src. Frees existing values in @dest. a #GtkTextAttributes another #GtkTextAttributes Increments the reference count on @values. the #GtkTextAttributes that were passed in a #GtkTextAttributes Decrements the reference count on @values, freeing the structure if the reference count reaches 0. a #GtkTextAttributes 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. Creates a new text buffer. a new text buffer a tag table, or %NULL to create a new one Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a #GtkTextBuffer a #GtkTextTag one bound of range to be tagged other bound of range to be tagged Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. #GtkTextBuffer maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_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 gtk_text_buffer_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. a #GtkTextBuffer Should be paired with a call to gtk_text_buffer_begin_user_action(). See that function for a full explanation. a #GtkTextBuffer 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 gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). Consider gtk_text_buffer_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. a #GtkTextBuffer location to insert the anchor a #GtkTextChildAnchor 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 gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). a #GtkTextBuffer location to insert the pixbuf a #GdkPixbuf 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. a #GtkTextBuffer a #GtkTextTag one bound of range to be untagged other bound of range to be untagged Adds the mark at position @where. The mark must not be added to another buffer, and if its name is not %NULL then there must not be another mark in the buffer with the same name. Emits the #GtkTextBuffer::mark-set signal as notification of the mark's initial placement. a #GtkTextBuffer the mark to add location to place mark Adds @clipboard to the list of clipboards in which the selection contents of @buffer are available. In most cases, @clipboard will be the #GtkClipboard of type %GDK_SELECTION_PRIMARY for a view of @buffer. a #GtkTextBuffer a #GtkClipboard Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a #GtkTextBuffer a #GtkTextTag one bound of range to be tagged other bound of range to be tagged Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a #GtkTextTag, then calls gtk_text_buffer_apply_tag(). a #GtkTextBuffer name of a named #GtkTextTag one bound of range to be tagged other bound of range to be tagged 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. %TRUE if the buffer was modified a #GtkTextBuffer a position in @buffer whether the deletion is caused by user interaction whether the buffer is editable by default Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. #GtkTextBuffer maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_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 gtk_text_buffer_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. a #GtkTextBuffer Copies the currently-selected text to a clipboard. a #GtkTextBuffer the #GtkClipboard object to copy to This is a convenience function which simply creates a child anchor with gtk_text_child_anchor_new() and inserts it into the buffer with gtk_text_buffer_insert_child_anchor(). The new anchor is owned by the buffer; no reference count is returned to the caller of gtk_text_buffer_create_child_anchor(). the created child anchor a #GtkTextBuffer location in the buffer Creates a mark at position @where. If @mark_name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using gtk_text_buffer_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 #GtkTextMark, 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 #GtkTextBuffer::mark-set signal as notification of the mark's initial placement. the new #GtkTextMark object a #GtkTextBuffer name for mark, or %NULL location to place mark whether the mark has left gravity Creates a tag and adds it to the tag table for @buffer. Equivalent to calling gtk_text_tag_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 %NULL, the tag is anonymous. If @tag_name is non-%NULL, 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 g_object_set(). a new tag a #GtkTextBuffer name of the new tag, or %NULL name of first property to set, or %NULL %NULL-terminated list of property names and values Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. a #GtkTextBuffer the #GtkClipboard object to cut to default editability of the buffer Deletes text between @start and @end. The order of @start and @end is not actually relevant; gtk_text_buffer_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. a #GtkTextBuffer a position in @buffer another position in @buffer Deletes all editable text in the given range. Calls gtk_text_buffer_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. whether some text was actually deleted a #GtkTextBuffer start of range to delete end of range whether the buffer is editable by default 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 g_object_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 gtk_text_buffer_add_mark(). Use gtk_text_mark_get_deleted() to find out if a mark has been removed from its buffer. The #GtkTextBuffer::mark-deleted signal will be emitted as notification after the mark is deleted. a #GtkTextBuffer a #GtkTextMark in @buffer Deletes the mark named @name; the mark must exist. See gtk_text_buffer_delete_mark() for details. a #GtkTextBuffer name of a mark in @buffer 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). whether there was a non-empty selection to delete a #GtkTextBuffer whether the deletion is caused by user interaction whether the buffer is editable by default This function deserializes rich text in format @format and inserts it at @iter. @formats to be used must be registered using gtk_text_buffer_register_deserialize_format() or gtk_text_buffer_register_deserialize_tagset() beforehand. %TRUE on success, %FALSE otherwise. the #GtkTextBuffer @format is registered with the #GtkTextBuffer to deserialize into the rich text format to use for deserializing insertion point for the deserialized text data to deserialize length of @data This functions returns the value set with gtk_text_buffer_deserialize_set_can_create_tags() whether deserializing this format may create tags a #GtkTextBuffer a #GdkAtom representing a registered rich text format 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 gtk_text_buffer_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. a #GtkTextBuffer a #GdkAtom representing a registered rich text format whether deserializing this format may create tags Should be paired with a call to gtk_text_buffer_begin_user_action(). See that function for a full explanation. a #GtkTextBuffer Retrieves the first and last iterators in the buffer, i.e. the entire buffer lies within the range [@start,@end). a #GtkTextBuffer iterator to initialize with first position in the buffer iterator to initialize with the end iterator 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. number of characters in the buffer a #GtkTextBuffer 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 #GtkTextBufferTargetInfo enum, using gtk_target_list_add_rich_text_targets() and gtk_target_list_add_text_targets(). the #GtkTargetList a #GtkTextBuffer This function returns the rich text deserialize formats registered with @buffer using gtk_text_buffer_register_deserialize_format() or gtk_text_buffer_register_deserialize_tagset() an array of #GdkAtoms representing the registered formats. a #GtkTextBuffer return location for the number of formats Initializes @iter with the “end iterator,” one past the last valid character in the text buffer. If dereferenced with gtk_text_iter_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 gtk_text_buffer_get_start_iter() to get character position 0) to the end iterator. a #GtkTextBuffer iterator to initialize Indicates whether the buffer has some text currently selected. %TRUE if the there is text selected a #GtkTextBuffer Returns the mark that represents the cursor (insertion point). Equivalent to calling gtk_text_buffer_get_mark() to get the mark named “insert”, but very slightly more efficient, and involves less typing. insertion point mark a #GtkTextBuffer Obtains the location of @anchor within @buffer. a #GtkTextBuffer an iterator to be initialized a child anchor that appears in @buffer Initializes @iter to the start of the given line. If @line_number is greater than the number of lines in the @buffer, the end iterator is returned. a #GtkTextBuffer iterator to initialize line number counting from 0 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 @buffer, 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. a #GtkTextBuffer iterator to initialize line number counting from 0 byte index from start of line 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 @buffer, 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. a #GtkTextBuffer iterator to initialize line number counting from 0 char offset from start of line Initializes @iter with the current position of @mark. a #GtkTextBuffer iterator to initialize a #GtkTextMark in @buffer 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. a #GtkTextBuffer iterator to initialize char offset from start of buffer, counting from 0, or -1 Obtains the number of lines in the buffer. This value is cached, so the function is very fast. number of lines in the buffer a #GtkTextBuffer Returns the mark named @name in buffer @buffer, or %NULL if no such mark exists in the buffer. a #GtkTextMark, or %NULL a #GtkTextBuffer a mark name Indicates whether the buffer has been modified since the last call to gtk_text_buffer_set_modified() set the modification flag to %FALSE. Used for example to enable a “save” function in a text editor. %TRUE if the buffer has been modified a #GtkTextBuffer 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 #GtkTextBufferTargetInfo enum, using gtk_target_list_add_rich_text_targets() and gtk_target_list_add_text_targets(). the #GtkTargetList a #GtkTextBuffer Returns the mark that represents the selection bound. Equivalent to calling gtk_text_buffer_get_mark() to get the mark named “selection_bound”, but very slightly more efficient, and involves less typing. The currently-selected text in @buffer 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. gtk_text_buffer_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. selection bound mark a #GtkTextBuffer 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. whether the selection has nonzero length a #GtkTextBuffer a #GtkTextBuffer iterator to initialize with selection start iterator to initialize with selection end This function returns the rich text serialize formats registered with @buffer using gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_serialize_tagset() an array of #GdkAtoms representing the registered formats. a #GtkTextBuffer return location for the number of formats 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 gtk_text_buffer_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. an allocated UTF-8 string a #GtkTextBuffer start of a range end of a range whether to include invisible text Initialized @iter with the first position in the text buffer. This is the same as using gtk_text_buffer_get_iter_at_offset() to get the iter at character offset 0. a #GtkTextBuffer iterator to initialize Get the #GtkTextTagTable associated with this buffer. the buffer’s tag table a #GtkTextBuffer 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 gtk_text_buffer_get_slice(). an allocated UTF-8 string a #GtkTextBuffer start of a range end of a range whether to include invisible text 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. a #GtkTextBuffer a position in the buffer text in UTF-8 format length of text in bytes, or -1 Simply calls gtk_text_buffer_insert(), using the current cursor position as the insertion point. a #GtkTextBuffer text in UTF-8 format length of text, in bytes 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 gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). Consider gtk_text_buffer_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. a #GtkTextBuffer location to insert the anchor a #GtkTextChildAnchor Like gtk_text_buffer_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 gtk_text_view_get_editable() is appropriate here. whether text was actually inserted a #GtkTextBuffer a position in @buffer some UTF-8 text length of text in bytes, or -1 default editability of buffer Calls gtk_text_buffer_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 gtk_text_view_get_editable() is appropriate here. whether text was actually inserted a #GtkTextBuffer text in UTF-8 format length of text in bytes, or -1 default editability of buffer 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 #GtkTextBuffer::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. a #GtkTextBuffer location to insert the markup a nul-terminated UTF-8 string containing [Pango markup][PangoMarkupFormat] length of @markup in bytes, or -1 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 gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). a #GtkTextBuffer location to insert the pixbuf a #GdkPixbuf 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 @buffer, the two buffers must share the same tag table. Implemented via emissions of the insert_text and apply_tag signals, so expect those. a #GtkTextBuffer a position in @buffer a position in a #GtkTextBuffer another position in the same buffer as @start Same as gtk_text_buffer_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 gtk_text_view_get_editable() is appropriate here. whether an insertion was possible at @iter a #GtkTextBuffer a position in @buffer a position in a #GtkTextBuffer another position in the same buffer as @start default editability of the buffer Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. The last tag specified must be %NULL to terminate the list. Equivalent to calling gtk_text_buffer_insert(), then gtk_text_buffer_apply_tag() on the inserted text; gtk_text_buffer_insert_with_tags() is just a convenience function. a #GtkTextBuffer an iterator in @buffer UTF-8 text length of @text, or -1 first tag to apply to @text %NULL-terminated list of tags to apply Same as gtk_text_buffer_insert_with_tags(), but allows you to pass in tag names instead of tag objects. a #GtkTextBuffer position in @buffer UTF-8 text length of @text, or -1 name of a tag to apply to @text more tag names Moves @mark to the new location @where. Emits the #GtkTextBuffer::mark-set signal as notification of the move. a #GtkTextBuffer a #GtkTextMark new location for @mark in @buffer Moves the mark named @name (which must exist) to location @where. See gtk_text_buffer_move_mark() for details. a #GtkTextBuffer name of a mark new location for mark Pastes the contents of a clipboard. If @override_location is %NULL, 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. a #GtkTextBuffer the #GtkClipboard to paste from location to insert pasted text, or %NULL whether the buffer is editable by default This function moves the “insert” and “selection_bound” marks simultaneously. If you move them to the same place in two steps with gtk_text_buffer_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. a #GtkTextBuffer where to put the cursor This function registers a rich text deserialization @function along with its @mime_type with the passed @buffer. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer the format’s mime-type the deserialize function to register @function’s user_data a function to call when @user_data is no longer needed This function registers GTK+’s internal rich text serialization format with the passed @buffer. See gtk_text_buffer_register_serialize_tagset() for details. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer an optional tagset name, on %NULL This function registers a rich text serialization @function along with its @mime_type with the passed @buffer. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer the format’s mime-type the serialize function to register @function’s user_data a function to call when @user_data is no longer needed This function registers GTK+’s internal rich text serialization format with the passed @buffer. The internal format does not comply to any standard rich text format and only works between #GtkTextBuffer instances. It is capable of serializing all of a text buffer’s tags and embedded pixbufs. This function is just a wrapper around gtk_text_buffer_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 != %NULL here, since the %NULL tagset requires the receiving buffer to deal with with pasting of arbitrary tags. the #GdkAtom that corresponds to the newly registered format’s mime-type. a #GtkTextBuffer an optional tagset name, on %NULL 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. a #GtkTextBuffer one bound of range to be untagged other bound of range to be untagged Removes a #GtkClipboard added with gtk_text_buffer_add_selection_clipboard(). a #GtkTextBuffer a #GtkClipboard added to @buffer by gtk_text_buffer_add_selection_clipboard() 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. a #GtkTextBuffer a #GtkTextTag one bound of range to be untagged other bound of range to be untagged Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a #GtkTextTag, then calls gtk_text_buffer_remove_tag(). a #GtkTextBuffer name of a #GtkTextTag one bound of range to be untagged other bound of range to be untagged This function moves the “insert” and “selection_bound” marks simultaneously. If you move them in two steps with gtk_text_buffer_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. a #GtkTextBuffer where to put the “insert” mark where to put the “selection_bound” mark 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 gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_serialize_tagset() beforehand. the serialized data, encoded as @format the #GtkTextBuffer @format is registered with the #GtkTextBuffer to serialize the rich text format to use for serializing start of block of text to serialize end of block of test to serialize return location for the length of the serialized data 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 (@buffer, FALSE). When the buffer is modified, it will automatically toggled on the modified bit again. When the modified bit flips, the buffer emits the #GtkTextBuffer::modified-changed signal. a #GtkTextBuffer modification flag setting Deletes current contents of @buffer, and inserts @text instead. If @len is -1, @text must be nul-terminated. @text must be valid UTF-8. a #GtkTextBuffer UTF-8 text to insert length of @text in bytes This function unregisters a rich text format that was previously registered using gtk_text_buffer_register_deserialize_format() or gtk_text_buffer_register_deserialize_tagset(). a #GtkTextBuffer a #GdkAtom representing a registered rich text format. This function unregisters a rich text format that was previously registered using gtk_text_buffer_register_serialize_format() or gtk_text_buffer_register_serialize_tagset() a #GtkTextBuffer a #GdkAtom representing a registered rich text format. The list of targets this buffer supports for clipboard copying and as DND source. The position of the insert mark (as offset from the beginning of the buffer). It is useful for getting notified when the cursor moves. Whether the buffer has some text currently selected. The list of targets this buffer supports for clipboard pasting and as DND destination. The text content of the buffer. Without child widgets and images, see gtk_text_buffer_get_text() for more information. The ::apply-tag signal is emitted to apply a tag to a range of text in a #GtkTextBuffer. 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: gtk_text_buffer_apply_tag(), gtk_text_buffer_insert_with_tags(), gtk_text_buffer_insert_range(). the applied tag the start of the range the tag is applied to the end of the range the tag is applied to The ::begin-user-action signal is emitted at the beginning of a single user-visible operation on a #GtkTextBuffer. See also: gtk_text_buffer_begin_user_action(), gtk_text_buffer_insert_interactive(), gtk_text_buffer_insert_range_interactive(), gtk_text_buffer_delete_interactive(), gtk_text_buffer_backspace(), gtk_text_buffer_delete_selection(). The ::changed signal is emitted when the content of a #GtkTextBuffer has changed. The ::delete-range signal is emitted to delete a range from a #GtkTextBuffer. 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: gtk_text_buffer_delete(). the start of the range to be deleted the end of the range to be deleted The ::end-user-action signal is emitted at the end of a single user-visible operation on the #GtkTextBuffer. See also: gtk_text_buffer_end_user_action(), gtk_text_buffer_insert_interactive(), gtk_text_buffer_insert_range_interactive(), gtk_text_buffer_delete_interactive(), gtk_text_buffer_backspace(), gtk_text_buffer_delete_selection(), gtk_text_buffer_backspace(). The ::insert-child-anchor signal is emitted to insert a #GtkTextChildAnchor in a #GtkTextBuffer. 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: gtk_text_buffer_insert_child_anchor(). position to insert @anchor in @textbuffer the #GtkTextChildAnchor to be inserted The ::insert-pixbuf signal is emitted to insert a #GdkPixbuf in a #GtkTextBuffer. 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: gtk_text_buffer_insert_pixbuf(). position to insert @pixbuf in @textbuffer the #GdkPixbuf to be inserted The ::insert-text signal is emitted to insert text in a #GtkTextBuffer. 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: gtk_text_buffer_insert(), gtk_text_buffer_insert_range(). position to insert @text in @textbuffer the UTF-8 text to be inserted length of the inserted text in bytes The ::mark-deleted signal is emitted as notification after a #GtkTextMark is deleted. See also: gtk_text_buffer_delete_mark(). The mark that was deleted The ::mark-set signal is emitted as notification after a #GtkTextMark is set. See also: gtk_text_buffer_create_mark(), gtk_text_buffer_move_mark(). The location of @mark in @textbuffer The mark that is set The ::modified-changed signal is emitted when the modified bit of a #GtkTextBuffer flips. See also: gtk_text_buffer_set_modified(). 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 gtk_text_buffer_paste_clipboard() for more details. the #GtkClipboard pasted from The ::remove-tag signal is emitted to remove all occurrences of @tag from a range of text in a #GtkTextBuffer. 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: gtk_text_buffer_remove_tag(). the tag to be removed the start of the range the tag is removed from the end of the range the tag is removed from The object class structure needs to be the first. a #GtkTextBuffer location to insert the pixbuf a #GdkPixbuf a #GtkTextBuffer location to insert the anchor a #GtkTextChildAnchor a #GtkTextBuffer a #GtkTextTag one bound of range to be tagged other bound of range to be tagged a #GtkTextBuffer a #GtkTextTag one bound of range to be untagged other bound of range to be untagged a #GtkTextBuffer a #GtkTextBuffer A function that is called to deserialize rich text that has been serialized with gtk_text_buffer_serialize(), and insert it at @iter. %TRUE on success, %FALSE otherwise the #GtkTextBuffer the format is registered with the #GtkTextBuffer to deserialize into insertion point for the deserialized text data to deserialize length of @data %TRUE if deserializing may create tags user data that was specified when registering the format A function that is called to serialize the content of a text buffer. It must return the serialized form of the content. a newly-allocated array of guint8 which contains the serialized data, or %NULL if an error occurred the #GtkTextBuffer for which the format is registered the #GtkTextBuffer to serialize start of the block of text to serialize end of the block of text to serialize Return location for the length of the serialized data user data that was specified when registering the format These values are used as “info” for the targets contained in the lists returned by gtk_text_buffer_get_copy_target_list() and gtk_text_buffer_get_paste_target_list(). The values counts down from `-1` to avoid clashes with application added drag destinations which usually start at 0. Buffer contents Rich text Text A #GtkTextChildAnchor 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. Creates a new #GtkTextChildAnchor. Usually you would then insert it into a #GtkTextBuffer with gtk_text_buffer_insert_child_anchor(). To perform the creation and insertion in one step, use the convenience function gtk_text_buffer_create_child_anchor(). a new #GtkTextChildAnchor 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 g_object_ref()) if you plan to use this function — otherwise all deleted child anchors will also be finalized. %TRUE if the child anchor has been deleted from its buffer a #GtkTextChildAnchor Gets a list of all widgets anchored at this child anchor. The returned list should be freed with g_list_free(). list of widgets anchored at @anchor a #GtkTextChildAnchor Reading directions for text. No direction. Left to right text direction. Right to left text direction. Granularity types that extend the text selection. Use the #GtkTextView::extend-selection signal to customize the selection. Selects the current word. It is triggered by a double-click for example. Selects the current line. It is triggered by a triple-click for example. 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. Assigns the value of @other to @iter. This function is not useful in applications, because iterators can be assigned with `GtkTextIter i = j;`. The function is used by language bindings. a #GtkTextIter another #GtkTextIter Moves backward by one character offset. Returns %TRUE if movement was possible; if @iter was the first in the buffer (character offset 0), gtk_text_iter_backward_char() returns %FALSE for convenience when writing loops. whether movement was possible an iterator 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. whether @iter moved and is dereferenceable an iterator number of characters to move Like gtk_text_iter_forward_cursor_position(), but moves backward. %TRUE if we moved a #GtkTextIter Moves up to @count cursor positions. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Same as gtk_text_iter_forward_find_char(), but goes backward from @iter. whether a match was found a #GtkTextIter function to be called on each character user data for @pred search limit, or %NULL for none Moves @iter to the start of the previous line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore if @iter was already on line 0, but not at the start of the line, @iter 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.) whether @iter moved an iterator 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. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move backward Same as gtk_text_iter_forward_search(), but moves backward. @match_end will never be set to a #GtkTextIter located after @iter, even if there is a possible @match_start before or at @iter. whether a match was found a #GtkTextIter where the search begins search string bitmask of flags affecting the search return location for start of match, or %NULL return location for end of match, or %NULL location of last possible @match_start, or %NULL for start of buffer Moves backward to the previous sentence start; if @iter 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). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_backward_sentence_start() up to @count times, or until it returns %FALSE. If @count is negative, moves forward instead of backward. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of sentences to move Moves backward to the next toggle (on or off) of the #GtkTextTag @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles before @iter. Sets @iter to the location of the toggle, or the start of the buffer if no toggle is found. whether we found a tag toggle before @iter a #GtkTextIter a #GtkTextTag, or %NULL Moves @iter forward to the previous visible cursor position. See gtk_text_iter_backward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter Moves up to @count visible cursor positions. See gtk_text_iter_backward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Moves @iter to the start of the previous visible line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore if @iter was already on line 0, but not at the start of the line, @iter 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.) whether @iter moved an iterator 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. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move backward Moves backward to the previous visible word start. (If @iter 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). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_backward_visible_word_start() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Moves backward to the previous word start. (If @iter 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). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_backward_word_start() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. Note that if gtk_text_iter_begins_tag() returns %TRUE, it means that @iter is at the beginning of the tagged range, and that the character at @iter is inside the tagged range. In other words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_begins_tag() returns %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same parameters. Use gtk_text_iter_starts_tag() instead. whether @iter is the start of a range tagged with @tag an iterator a #GtkTextTag, or %NULL Considering the default editability of the buffer, and tags that affect editability, determines whether text inserted at @iter would be editable. If text inserted at @iter would be editable then the user should be allowed to insert text at @iter. gtk_text_buffer_insert_interactive() uses this function to decide whether insertions are allowed at a given position. whether text inserted at @iter would be editable an iterator %TRUE if text is editable by default A qsort()-style function that returns negative if @lhs is less than @rhs, positive if @lhs 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. -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal a #GtkTextIter another #GtkTextIter 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. a copy of the @iter, free with gtk_text_iter_free() an iterator Returns whether the character at @iter is within an editable region of text. Non-editable text is “locked” and can’t be changed by the user via #GtkTextView. This function is simply a convenience wrapper around gtk_text_iter_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 @iter, because for insertion you don’t want to know whether the char at @iter is inside an editable range, you want to know whether a new character inserted at @iter would be inside an editable range. Use gtk_text_iter_can_insert() to handle this case. whether @iter is inside an editable range an iterator %TRUE if text is editable by default Returns %TRUE if @iter 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. whether @iter is at the end of a line an iterator Determines whether @iter 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). %TRUE if @iter is at the end of a sentence. a #GtkTextIter Returns %TRUE if @tag is toggled off at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled off at this point. Note that if gtk_text_iter_ends_tag() returns %TRUE, it means that @iter is at the end of the tagged range, but that the character at @iter is outside the tagged range. In other words, unlike gtk_text_iter_starts_tag(), if gtk_text_iter_ends_tag() returns %TRUE, gtk_text_iter_has_tag() will return %FALSE for the same parameters. whether @iter is the end of a range tagged with @tag an iterator a #GtkTextTag, or %NULL Determines whether @iter 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). %TRUE if @iter is at the end of a word a #GtkTextIter 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 gtk_text_iter_compare(). %TRUE if the iterators point to the same place in the buffer a #GtkTextIter another #GtkTextIter Moves @iter forward by one character offset. Note that images embedded in the buffer occupy 1 character slot, so gtk_text_iter_forward_char() may actually move onto an image instead of a character, if you have images in your buffer. If @iter is the end iterator or one character before it, @iter will now point at the end iterator, and gtk_text_iter_forward_char() returns %FALSE for convenience when writing loops. whether @iter moved and is dereferenceable an iterator 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 @iter 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. whether @iter moved and is dereferenceable an iterator number of characters to move, may be negative Moves @iter 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 #PangoLogAttr-struct and pango_break() function. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter Moves up to @count cursor positions. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Advances @iter, calling @pred on each character. If @pred returns %TRUE, returns %TRUE and stops scanning. If @pred never returns %TRUE, @iter is set to @limit if @limit is non-%NULL, otherwise to the end iterator. whether a match was found a #GtkTextIter a function to be called on each character user data for @pred search limit, or %NULL for none Moves @iter 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. whether @iter can be dereferenced an iterator 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. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move forward 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 #GtkTextIter located before @iter, even if there is a possible @match_end after or at @iter. whether a match was found start of search a search string flags affecting how the search is done return location for start of match, or %NULL return location for end of match, or %NULL location of last possible @match_end, or %NULL for the end of the buffer Moves forward to the next sentence end. (If @iter 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). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_forward_sentence_end() @count times (or until gtk_text_iter_forward_sentence_end() returns %FALSE). If @count is negative, moves backward instead of forward. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of sentences to move Moves @iter forward to the “end iterator,” which points one past the last valid character in the buffer. gtk_text_iter_get_char() called on the end iterator returns 0, which is convenient for writing loops. a #GtkTextIter 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 @iter 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. %TRUE if we moved and the new location is not the end iterator a #GtkTextIter Moves forward to the next toggle (on or off) of the #GtkTextTag @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles after @iter. Sets @iter to the location of the toggle, or to the end of the buffer if no toggle is found. whether we found a tag toggle after @iter a #GtkTextIter a #GtkTextTag, or %NULL Moves @iter forward to the next visible cursor position. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter Moves up to @count visible cursor positions. See gtk_text_iter_forward_cursor_position() for details. %TRUE if we moved and the new position is dereferenceable a #GtkTextIter number of positions to move Moves @iter to the start of the next visible line. Returns %TRUE if there was a next line to move to, and %FALSE if @iter was simply moved to the end of the buffer and is now not dereferenceable, or if @iter was already at the end of the buffer. whether @iter can be dereferenced an iterator 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. whether @iter moved and is dereferenceable a #GtkTextIter number of lines to move forward Moves forward to the next visible word end. (If @iter 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). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_forward_visible_word_end() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move Moves forward to the next word end. (If @iter 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). %TRUE if @iter moved and is not the end iterator a #GtkTextIter Calls gtk_text_iter_forward_word_end() up to @count times. %TRUE if @iter moved and is not the end iterator a #GtkTextIter number of times to move 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. a dynamically-allocated iterator 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 gtk_text_view_get_default_attributes(). gtk_text_iter_get_attributes() will modify @values, applying the effects of any tags present at @iter. If any tags affected @values, the function returns %TRUE. %TRUE if @values was modified an iterator a #GtkTextAttributes to be filled in Returns the #GtkTextBuffer this iterator is associated with. the buffer an iterator Returns the number of bytes in the line containing @iter, including the paragraph delimiters. number of bytes in the line an iterator 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 gtk_text_iter_get_char() returns 0. a Unicode character, or 0 if @iter is not dereferenceable an iterator Returns the number of characters in the line containing @iter, including the paragraph delimiters. number of characters in the line an iterator If the location at @iter contains a child anchor, the anchor is returned (with no new reference count added). Otherwise, %NULL is returned. the anchor at @iter an iterator A convenience wrapper around gtk_text_iter_get_attributes(), which returns the language in effect at @iter. If no tags affecting language apply to @iter, the return value is identical to that of gtk_get_default_language(). language in effect at @iter an iterator Returns the line number containing the iterator. Lines in a #GtkTextBuffer are numbered beginning with 0 for the first line in the buffer. a line number an iterator Returns the byte index of the iterator, counting from the start of a newline-terminated line. Remember that #GtkTextBuffer encodes text in UTF-8, and that characters can require a variable number of bytes to represent. distance from start of line, in bytes an iterator 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. offset from start of line an iterator Returns a list of all #GtkTextMark 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. list of #GtkTextMark an iterator Returns the character offset of an iterator. Each character in a #GtkTextBuffer has an offset, starting with 0 for the first character in the buffer. Use gtk_text_buffer_get_iter_at_offset() to convert an offset back into an iterator. a character offset an iterator If the element at @iter is a pixbuf, the pixbuf is returned (with no new reference count added). Otherwise, %NULL is returned. the pixbuf at @iter an iterator 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. slice of text from the buffer iterator at start of a range iterator at end of a range Returns a list of tags that apply to @iter, in ascending order of priority (highest-priority tags are last). The #GtkTextTag in the list don’t have a reference added, but you have to free the list itself. list of #GtkTextTag a #GtkTextIter 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 gtk_text_iter_get_slice(). array of characters from the buffer iterator at start of a range iterator at end of a range Returns a list of #GtkTextTag 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 @iter, then some non-empty range of characters following @iter has that tag applied to it. If a tag is toggled off, then some non-empty range following @iter does not have the tag applied to it. tags toggled at this point an iterator %TRUE to get toggled-on tags Returns the number of bytes from the start of the line to the given @iter, not counting bytes that are invisible due to tags with the “invisible” flag toggled on. byte index of @iter with respect to the start of the line a #GtkTextIter Returns the offset in characters from the start of the line to the given @iter, not counting characters that are invisible due to tags with the “invisible” flag toggled on. offset in visible characters from the start of the line a #GtkTextIter Like gtk_text_iter_get_slice(), but invisible text is not included. Invisible text is usually invisible because a #GtkTextTag with the “invisible” attribute turned on has been applied to it. slice of text from the buffer iterator at start of range iterator at end of range Like gtk_text_iter_get_text(), but invisible text is not included. Invisible text is usually invisible because a #GtkTextTag with the “invisible” attribute turned on has been applied to it. string containing visible text in the range iterator at start of range iterator at end of range Returns %TRUE if @iter points to a character that is part of a range tagged with @tag. See also gtk_text_iter_starts_tag() and gtk_text_iter_ends_tag(). whether @iter is tagged with @tag an iterator a #GtkTextTag Checks whether @iter falls in the range [@start, @end). @start and @end must be in ascending order. %TRUE if @iter is in the range a #GtkTextIter start of range end of range Determines whether @iter 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). %TRUE if @iter is inside a sentence. a #GtkTextIter Determines whether the character pointed by @iter 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 gtk_text_iter_starts_word() returns %TRUE, then this function returns %TRUE too, since @iter points to the first character of the word. %TRUE if @iter is inside a word a #GtkTextIter See gtk_text_iter_forward_cursor_position() or #PangoLogAttr or pango_break() for details on what a cursor position is. %TRUE if the cursor can be placed at @iter a #GtkTextIter Returns %TRUE if @iter is the end iterator, i.e. one past the last dereferenceable iterator in the buffer. gtk_text_iter_is_end() is the most efficient way to check whether an iterator is the end iterator. whether @iter is the end iterator an iterator Returns %TRUE if @iter is the first iterator in the buffer, that is if @iter has a character offset of 0. whether @iter is the first in the buffer an iterator Swaps the value of @first and @second if @second comes before @first in the buffer. That is, ensures that @first 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 gtk_text_iter_in_range(), that expect a pre-sorted range. a #GtkTextIter another #GtkTextIter Moves iterator @iter to the start of the line @line_number. If @line_number is negative or larger than the number of lines in the buffer, moves @iter to the start of the last line in the buffer. a #GtkTextIter line number (counted from 0) Same as gtk_text_iter_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. a #GtkTextIter a byte index relative to the start of @iter’s current line Moves @iter 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, @iter moves to the start of the next line. See gtk_text_iter_set_line_index() if you have a byte index rather than a character offset. a #GtkTextIter a character offset relative to the start of @iter’s current line Sets @iter to point to @char_offset. @char_offset counts from the start of the entire text buffer, starting with 0. a #GtkTextIter a character number Like gtk_text_iter_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. a #GtkTextIter a byte index Like gtk_text_iter_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. a #GtkTextIter a character offset Returns %TRUE if @iter begins a paragraph, i.e. if gtk_text_iter_get_line_offset() would return 0. However this function is potentially more efficient than gtk_text_iter_get_line_offset() because it doesn’t have to compute the offset, it just has to see whether it’s 0. whether @iter begins a line an iterator Determines whether @iter 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). %TRUE if @iter is at the start of a sentence. a #GtkTextIter Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. Note that if gtk_text_iter_starts_tag() returns %TRUE, it means that @iter is at the beginning of the tagged range, and that the character at @iter is inside the tagged range. In other words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_starts_tag() returns %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same parameters. whether @iter is the start of a range tagged with @tag an iterator a #GtkTextTag, or %NULL Determines whether @iter 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). %TRUE if @iter is at the start of a word a #GtkTextIter This is equivalent to (gtk_text_iter_starts_tag() || gtk_text_iter_ends_tag()), i.e. it tells you whether a range with @tag applied to it begins or ends at @iter. whether @tag is toggled on or off at @iter an iterator a #GtkTextTag, or %NULL 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 #GtkTextMark is like a bookmark in a text buffer; it preserves a position in the text. You can convert the mark to an iterator using gtk_text_buffer_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 gtk_text_buffer_delete_mark(). Once deleted from the buffer, a mark is essentially useless. Marks optionally have names; these can be convenient to avoid passing the #GtkTextMark object around. Marks are typically created using the gtk_text_buffer_create_mark() function. Creates a text mark. Add it to a buffer using gtk_text_buffer_add_mark(). If @name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using gtk_text_buffer_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). new #GtkTextMark mark name or %NULL whether the mark should have left gravity Gets the buffer this mark is located inside, or %NULL if the mark is deleted. the mark’s #GtkTextBuffer a #GtkTextMark Returns %TRUE if the mark has been removed from its buffer with gtk_text_buffer_delete_mark(). See gtk_text_buffer_add_mark() for a way to add it to a buffer again. whether the mark is deleted a #GtkTextMark Determines whether the mark has left gravity. %TRUE if the mark has left gravity, %FALSE otherwise a #GtkTextMark Returns the mark name; returns NULL for anonymous marks. mark name a #GtkTextMark Returns %TRUE if the mark is visible (i.e. a cursor is displayed for it). %TRUE if visible a #GtkTextMark Sets the visibility of @mark; 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. a #GtkTextMark visibility of mark 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. The name of the mark or %NULL if the mark is anonymous. Flags affecting how a search is done. If neither #GTK_TEXT_SEARCH_VISIBLE_ONLY nor #GTK_TEXT_SEARCH_TEXT_ONLY are enabled, the match must be exact; the special 0xFFFC character will match embedded pixbufs or child widgets. Search only visible data. A search match may have invisible text interspersed. Search only text. A match may have pixbufs or child widgets mixed inside the matched range. The text will be matched regardless of what case it is in. 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 #GtkTextTagTable for a given #GtkTextBuffer before using them with that buffer. gtk_text_buffer_create_tag() is the best way to create tags. See “gtk3-demo” for numerous examples. For each property of #GtkTextTag, 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. Creates a #GtkTextTag. Configure the tag using object arguments, i.e. using g_object_set(). a new #GtkTextTag tag name, or %NULL Emits the “event” signal on the #GtkTextTag. result of signal emission (whether the event was handled) a #GtkTextTag object that received the event, such as a widget the event location where the event was received Emits the #GtkTextTagTable::tag-changed signal on the #GtkTextTagTable where the tag is included. The signal is already emitted when setting a #GtkTextTag property. This function is useful for a #GtkTextTag subclass. a #GtkTextTag. whether the change affects the #GtkTextView layout. Emits the “event” signal on the #GtkTextTag. result of signal emission (whether the event was handled) a #GtkTextTag object that received the event, such as a widget the event location where the event was received Get the tag priority. The tag’s priority. a #GtkTextTag Sets the priority of a #GtkTextTag. Valid priorities start at 0 and go to one less than gtk_text_tag_table_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 gtk_text_buffer_create_tag(), which adds the tag to the buffer’s table automatically. a #GtkTextTag the new priority 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). Background color as a #GdkColor. Use #GtkTextTag:background-rgba instead. Background color as a #GdkRGBA. Whether font fallback is enabled. When set to %TRUE, other fonts will be substituted where the current font is missing glyphs. Font description as string, e.g. \"Sans Italic 12\". Note that the initial value of this property depends on the internals of #PangoFontDescription. OpenType font features, as a string. Foreground color as a #GdkColor. Use #GtkTextTag:foreground-rgba instead. Foreground color as a #GdkRGBA. 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. 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(). Extra spacing between graphemes, in Pango units. The paragraph background color as a string. The paragraph background color as a #GdkColor. Use #GtkTextTag:paragraph-background-rgba instead. The paragraph background color as a #GdkRGBA. This property modifies the color of strikeouts. If not set, strikeouts will use the forground color. If the #GtkTextTag:strikethrough-rgba property has been set. This property modifies the color of underlines. If not set, underlines will use the forground color. If #GtkTextTag: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. If the #GtkTextTag:underline-rgba property has been set. The ::event signal is emitted when an event occurs on a region of the buffer marked with this tag. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the object the event was fired from (typically a #GtkTextView) the event which triggered the signal a #GtkTextIter pointing at the location the event occurred result of signal emission (whether the event was handled) a #GtkTextTag object that received the event, such as a widget the event location where the event was received 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 GtkBuildable The GtkTextTagTable implementation of the GtkBuildable interface supports adding tags by specifying “tag” as the “type” attribute of a <child> element. An example of a UI definition fragment specifying tags: |[ <object class="GtkTextTagTable"> <child type="tag"> <object class="GtkTextTag"/> </child> </object> ]| Creates a new #GtkTextTagTable. The table contains no tags by default. a new #GtkTextTagTable 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. %TRUE on success. a #GtkTextTagTable a #GtkTextTag Calls @func on each tag in @table, with user data @data. Note that the table may not be modified while iterating over it (you can’t add/remove tags). a #GtkTextTagTable a function to call on each tag user data Returns the size of the table (number of tags) number of tags in @table a #GtkTextTagTable Look up a named tag. The tag, or %NULL if none by that name is in the table. a #GtkTextTagTable name of a tag Remove a tag from the table. If a #GtkTextBuffer has @table 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. a #GtkTextTagTable a #GtkTextTag the added tag. the changed tag. whether the change affects the #GtkTextView layout. the removed tag. the #GtkTextTag data passed to gtk_text_tag_table_foreach() 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 |[<!-- language="plain" --> textview.view ├── border.top ├── border.left ├── text │ ╰── [selection] ├── border.right ├── border.bottom ╰── [window.popup] ]| GtkTextView 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. Creates a new #GtkTextView. If you don’t call gtk_text_view_set_buffer() before using the text view, an empty default buffer will be created for you. Get the buffer with gtk_text_view_get_buffer(). If you want to specify your own buffer, consider gtk_text_view_new_with_buffer(). a new #GtkTextView Creates a new #GtkTextView widget displaying the buffer @buffer. One buffer can be shared among many widgets. @buffer may be %NULL to create a default buffer, in which case this function is equivalent to gtk_text_view_new(). The text view adds its own reference count to the buffer; it does not take over an existing reference. a new #GtkTextView. a #GtkTextBuffer Adds a child widget in the text buffer, at the given @anchor. a #GtkTextView a #GtkWidget a #GtkTextChildAnchor in the #GtkTextBuffer for @text_view Adds a child at fixed coordinates in one of the text widget's windows. The window must have nonzero size (see gtk_text_view_set_border_window_size()). Note that the child coordinates are given relative to scrolling. When placing a child in #GTK_TEXT_WINDOW_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. a #GtkTextView a #GtkWidget which window the child should appear in X position of child in window coordinates Y position of child in window coordinates 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 #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter 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 #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter 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 gtk_text_view_set_border_window_size()). a #GtkTextView a #GtkTextWindowType, except %GTK_TEXT_WINDOW_PRIVATE buffer x coordinate buffer y coordinate window x coordinate return location or %NULL window y coordinate return location or %NULL 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 #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter 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 #GtkTextBuffer. %TRUE if @iter was moved and is not on the end iterator a #GtkTextView a #GtkTextIter Returns whether pressing the Tab key inserts a tab characters. gtk_text_view_set_accepts_tab(). %TRUE if pressing the Tab key inserts a tab character, %FALSE if pressing the Tab key moves the keyboard focus. A #GtkTextView Gets the width of the specified border window. See gtk_text_view_set_border_window_size(). width of window a #GtkTextView window to return size from Gets the bottom margin for text in the @text_view. bottom margin in pixels a #GtkTextView Returns the #GtkTextBuffer 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. a #GtkTextBuffer a #GtkTextView 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 %NULL, 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 gtk_text_view_buffer_to_window_coords() to convert these coordinates to coordinates for one of the windows in the text view. a #GtkTextView a #GtkTextIter location to store the strong cursor position (may be %NULL) location to store the weak cursor position (may be %NULL) Find out whether the cursor should be displayed. whether the insertion mark is visible a #GtkTextView 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 gtk_text_iter_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 gtk_text_attributes_unref(). a new #GtkTextAttributes a #GtkTextView Returns the default editability of the #GtkTextView. Tags in the buffer may override this setting for some ranges of text. whether text is editable by default a #GtkTextView Gets the horizontal-scrolling #GtkAdjustment. Use gtk_scrollable_get_hadjustment() pointer to the horizontal #GtkAdjustment a #GtkTextView Gets the default indentation of paragraphs in @text_view. Tags in the view’s buffer may override the default. The indentation may be negative. number of pixels of indentation a #GtkTextView Gets the value of the #GtkTextView:input-hints property. a #GtkTextView Gets the value of the #GtkTextView:input-purpose property. a #GtkTextView 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 gtk_text_view_window_to_buffer_coords(). %TRUE if the position is over text a #GtkTextView a #GtkTextIter x position, in buffer coordinates y position, in buffer coordinates 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 gtk_text_view_window_to_buffer_coords(). Note that this is different from gtk_text_view_get_iter_at_location(), which returns cursor locations, i.e. positions between characters. %TRUE if the position is over text a #GtkTextView a #GtkTextIter if non-%NULL, 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 position, in buffer coordinates y position, in buffer coordinates Gets a rectangle which roughly contains the character at @iter. The rectangle position is in buffer coordinates; use gtk_text_view_buffer_to_window_coords() to convert these coordinates to coordinates for one of the windows in the text view. a #GtkTextView a #GtkTextIter bounds of the character at @iter Gets the default justification of paragraphs in @text_view. Tags in the buffer may override the default. default justification a #GtkTextView Gets the default left margin size of paragraphs in the @text_view. Tags in the buffer may override the default. left margin in pixels a #GtkTextView Gets the #GtkTextIter at the start of the line containing the coordinate @y. @y is in buffer coordinates, convert from window coordinates with gtk_text_view_window_to_buffer_coords(). If non-%NULL, @line_top will be filled with the coordinate of the top edge of the line. a #GtkTextView a #GtkTextIter a y coordinate return location for top coordinate of the line 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 gtk_text_view_buffer_to_window_coords(). a #GtkTextView a #GtkTextIter return location for a y coordinate return location for a height Gets the value of the #GtkTextView:monospace property. %TRUE if monospace fonts are desired a #GtkTextView Returns whether the #GtkTextView is in overwrite mode or not. whether @text_view is in overwrite mode or not. a #GtkTextView Gets the default number of pixels to put above paragraphs. Adding this function with gtk_text_view_get_pixels_below_lines() is equal to the line space between each paragraph. default number of pixels above paragraphs a #GtkTextView Gets the value set by gtk_text_view_set_pixels_below_lines(). The line space is the sum of the value returned by this function and the value returned by gtk_text_view_get_pixels_above_lines(). default number of blank pixels below paragraphs a #GtkTextView Gets the value set by gtk_text_view_set_pixels_inside_wrap(). default number of pixels of blank space between wrapped lines a #GtkTextView Gets the default right margin for text in @text_view. Tags in the buffer may override the default. right margin in pixels a #GtkTextView Gets the default tabs for @text_view. Tags in the buffer may override the defaults. The returned array will be %NULL if “standard” (8-space) tabs are used. Free the return value with pango_tab_array_free(). copy of default tab array, or %NULL if “standard" tabs are used; must be freed with pango_tab_array_free(). a #GtkTextView Gets the top margin for text in the @text_view. top margin in pixels a #GtkTextView Gets the vertical-scrolling #GtkAdjustment. Use gtk_scrollable_get_vadjustment() pointer to the vertical #GtkAdjustment a #GtkTextView Fills @visible_rect with the currently-visible region of the buffer, in buffer coordinates. Convert to window coordinates with gtk_text_view_buffer_to_window_coords(). a #GtkTextView rectangle to fill Retrieves the #GdkWindow 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 %NULL and nonexistent if their width or height is 0, and are nonexistent before the widget has been realized. a #GdkWindow, or %NULL a #GtkTextView window to get Usually used to find out which window an event corresponds to. If you connect to an event signal on @text_view, this function should be called on `event->window` to see which window it was. the window type. a #GtkTextView a window type Gets the line wrapping for the view. the line wrap setting a #GtkTextView Allow the #GtkTextView 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 gtk_im_context_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 #GtkTextView. |[<!-- language="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); } ]| %TRUE if the input method handled the key event. a #GtkTextView the key event Updates the position of a child, as for gtk_text_view_add_child_in_window(). a #GtkTextView child widget already added to the text view new X position in window coordinates new Y position in window coordinates Moves a mark within the buffer so that it's located within the currently-visible text area. %TRUE if the mark moved (wasn’t already onscreen) a #GtkTextView a #GtkTextMark 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. %TRUE if @iter moved and is not on the end iterator a #GtkTextView a #GtkTextIter number of characters to move (negative moves left, positive moves right) Moves the cursor to the currently visible region of the buffer, it it isn’t there already. %TRUE if the cursor had to be moved. a #GtkTextView 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 #GtkWidget::key-press-event handler). a #GtkTextView 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. a #GtkTextView Scrolls @text_view the minimum distance such that @mark is contained within the visible area of the widget. a #GtkTextView a mark in the buffer for @text_view Scrolls @text_view 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 gtk_text_view_scroll_to_mark() which saves a point to be scrolled to after line validation. %TRUE if scrolling occurred a #GtkTextView a #GtkTextIter margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Scrolls @text_view 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. a #GtkTextView a #GtkTextMark margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area 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. A #GtkTextView %TRUE if pressing the Tab key should insert a tab character, %FALSE, if pressing the Tab key should move the keyboard focus. Sets the width of %GTK_TEXT_WINDOW_LEFT or %GTK_TEXT_WINDOW_RIGHT, or the height of %GTK_TEXT_WINDOW_TOP or %GTK_TEXT_WINDOW_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 %GTK_TEXT_WINDOW_WIDGET, %GTK_TEXT_WINDOW_TEXT, or %GTK_TEXT_WINDOW_PRIVATE. a #GtkTextView window to affect width or height of the window Sets the bottom margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a #GtkTextView bottom margin in pixels Sets @buffer as the buffer being displayed by @text_view. 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; #GtkTextView will not “adopt” it. a #GtkTextView a #GtkTextBuffer 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 #GtkSettings:gtk-keynave-use-caret settings. a #GtkTextView whether to show the insertion cursor Sets the default editability of the #GtkTextView. You can override this default setting with tags in the buffer, using the “editable” attribute of tags. a #GtkTextView whether it’s editable Sets the default indentation for paragraphs in @text_view. Tags in the buffer may override the default. a #GtkTextView indentation in pixels Sets the #GtkTextView:input-hints property, which allows input methods to fine-tune their behaviour. a #GtkTextView the hints Sets the #GtkTextView:input-purpose property which can be used by on-screen keyboards and other input methods to adjust their behaviour. a #GtkTextView the purpose Sets the default justification of text in @text_view. Tags in the view’s buffer may override the default. a #GtkTextView justification Sets the default left margin for text in @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. a #GtkTextView left margin in pixels Sets the #GtkTextView:monospace property, which indicates that the text view should use monospace fonts. a #GtkTextView %TRUE to request monospace styling Changes the #GtkTextView overwrite mode. a #GtkTextView %TRUE to turn on overwrite mode, %FALSE to turn it off Sets the default number of blank pixels above paragraphs in @text_view. Tags in the buffer for @text_view may override the defaults. a #GtkTextView pixels above paragraphs Sets the default number of pixels of blank space to put below paragraphs in @text_view. May be overridden by tags applied to @text_view’s buffer. a #GtkTextView pixels below paragraphs Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. May be overridden by tags in @text_view’s buffer. a #GtkTextView default number of pixels between wrapped lines 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. a #GtkTextView right margin in pixels Sets the default tab stops for paragraphs in @text_view. Tags in the buffer may override the default. a #GtkTextView tabs as a #PangoTabArray Sets the top margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a #GtkTextView top margin in pixels Sets the line wrapping for the view. a #GtkTextView a #GtkWrapMode Determines whether @iter is at the start of a display line. See gtk_text_view_forward_display_line() for an explanation of display lines vs. paragraphs. %TRUE if @iter begins a wrapped line a #GtkTextView a #GtkTextIter 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 gtk_text_view_set_border_window_size()). a #GtkTextView a #GtkTextWindowType except %GTK_TEXT_WINDOW_PRIVATE window x coordinate window y coordinate buffer x coordinate return location or %NULL buffer y coordinate return location or %NULL 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 #GtkWidget:margin-bottom. Which IM (input method) module should be used for this text_view. See #GtkIMContext. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings #GtkSettings:gtk-im-module property. Additional hints (beyond #GtkTextView:input-purpose) that allow input methods to fine-tune their behaviour. The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. 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 #GtkWidget:margin-left. If :populate-all is %TRUE, the #GtkTextView::populate-popup signal is also emitted for touch popups. 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 #GtkWidget:margin-right. 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 #GtkWidget:margin-top. The ::backspace signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user asks for it. The default bindings for this signal are Backspace and Shift-Backspace. The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard. The default bindings for this signal are Ctrl-c and Ctrl-Insert. The ::cut-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to cut the selection to the clipboard. The default bindings for this signal are Ctrl-x and Shift-Delete. The ::delete-from-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a text deletion. If the @type is %GTK_DELETE_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. the granularity of the deletion, as a #GtkDeleteType the number of @type units to delete The ::extend-selection signal is emitted when the selection needs to be extended at @location. %GDK_EVENT_STOP to stop other handlers from being invoked for the event. %GDK_EVENT_PROPAGATE to propagate the event further. the granularity type the location where to extend the selection where the selection should start where the selection should end The ::insert-at-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates the insertion of a fixed string at the cursor. This signal has no default bindings. the string to insert The ::insert-emoji signal is a [keybinding signal][GtkBindingSignal] which gets emitted to present the Emoji chooser for the @text_view. The default bindings for this signal are Ctrl-. and Ctrl-; The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] 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 the granularity of the move, as a #GtkMovementStep the number of @step units to move %TRUE if the move should extend the selection The ::move-viewport signal is a [keybinding signal][GtkBindingSignal] 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. the granularity of the movement, as a #GtkScrollStep the number of @step units to move The ::paste-clipboard signal is a [keybinding signal][GtkBindingSignal] 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. 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 #GtkMenu in this case. If #GtkTextView: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 #GtkToolbar. The signal handler should not make assumptions about the type of @widget, but check whether @popup is a #GtkMenu or #GtkToolbar or another kind of container. the container that is being populated 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. the current preedit string The ::select-all signal is a [keybinding signal][GtkBindingSignal] 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. %TRUE to select, %FALSE to unselect The ::set-anchor signal is a [keybinding signal][GtkBindingSignal] 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. The ::toggle-cursor-visible signal is a [keybinding signal][GtkBindingSignal] which gets emitted to toggle the #GtkTextView:cursor-visible property. The default binding for this signal is F7. The ::toggle-overwrite signal is a [keybinding signal][GtkBindingSignal] which gets emitted to toggle the overwrite mode of the text view. The default bindings for this signal is Insert. The object class structure needs to be the first Used to reference the layers of #GtkTextView for the purpose of customized drawing with the ::draw_layer vfunc. Old deprecated layer, use %GTK_TEXT_VIEW_LAYER_BELOW_TEXT instead Old deprecated layer, use %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT instead The layer rendered below the text (but above the background). Since: 3.20 The layer rendered above the text. Since: 3.20 Used to reference the parts of #GtkTextView. Invalid value, used as a marker Window that floats over scrolling areas. Scrollable text window. Left side border window. Right side border window. Top border window. Bottom border window. #GtkThemingEngine was the object used for rendering themed content in GTK+ widgets. It used to allow overriding GTK+'s default implementation of rendering functions by allowing engines to be loaded as modules. #GtkThemingEngine has been deprecated in GTK+ 3.14 and will be ignored for rendering. The advancements in CSS theming are good enough to allow themers to achieve their goals without the need to modify source code. Loads and initializes a theming engine module from the standard directories. A theming engine, or %NULL if the engine @name doesn’t exist. Theme engine name to load Registers a property so it can be used in the CSS file format, on the CSS file the property will look like "-${@name_space}-${property_name}". being ${property_name} the given to @pspec. @name_space will usually be the theme engine name. For any type a @parse_func may be provided, being this function used for turning any property value (between “:” and “;”) in CSS to the #GValue needed. For basic types there is already builtin parsing support, so %NULL may be provided for these cases. Engines must ensure property registration happens exactly once, usually GTK+ deals with theming engines as singletons, so this should be guaranteed to happen once, but bear this in mind when creating #GtkThemeEngines yourself. In order to make use of the custom registered properties in the CSS file, make sure the engine is loaded first by specifying the engine property, either in a previous rule or within the same one. |[ * { engine: someengine; -SomeEngine-custom-property: 2; } ]| Code should use the default properties provided by CSS. namespace for the property name parsing function to use, or %NULL the #GParamSpec for the new property Retrieves several style property values that apply to the currently rendered element. a #GtkThemingEngine state to retrieve values for property name /return value pairs, followed by %NULL Gets the background color for a given state. a #GtkThemingEngine state to retrieve the color for return value for the background color Gets the border for a given state as a #GtkBorder. a #GtkThemingEngine state to retrieve the border for return value for the border settings Gets the border color for a given state. a #GtkThemingEngine state to retrieve the color for return value for the border color Gets the foreground color for a given state. a #GtkThemingEngine state to retrieve the color for return value for the foreground color Returns the widget direction used for rendering. Use gtk_theming_engine_get_state() and check for #GTK_STATE_FLAG_DIR_LTR and #GTK_STATE_FLAG_DIR_RTL instead. the widget direction a #GtkThemingEngine Returns the font description for a given state. Use gtk_theming_engine_get() the #PangoFontDescription for the given state. This object is owned by GTK+ and should not be freed. a #GtkThemingEngine state to retrieve the font for Returns the widget direction used for rendering. the widget direction a #GtkThemingEngine Gets the margin for a given state as a #GtkBorder. a #GtkThemingEngine state to retrieve the border for return value for the margin settings Gets the padding for a given state as a #GtkBorder. a #GtkThemingEngine state to retrieve the padding for return value for the padding settings Returns the widget path used for style matching. A #GtkWidgetPath a #GtkThemingEngine Gets a property value as retrieved from the style settings that apply to the currently rendered element. a #GtkThemingEngine the property name state to retrieve the value for return location for the property value, you must free this memory using g_value_unset() once you are done with it. Returns the #GdkScreen to which @engine currently rendering to. a #GdkScreen, or %NULL. a #GtkThemingEngine returns the state used when rendering. the state flags a #GtkThemingEngine Retrieves several widget style properties from @engine according to the currently rendered content’s style. a #GtkThemingEngine property name /return value pairs, followed by %NULL Gets the value for a widget style property. a #GtkThemingEngine the name of the widget style property Return location for the property value, free with g_value_unset() after use. Retrieves several widget style properties from @engine according to the currently rendered content’s style. a #GtkThemingEngine va_list of property name/return location pairs, followed by %NULL Retrieves several style property values that apply to the currently rendered element. a #GtkThemingEngine state to retrieve values for va_list of property name/return location pairs, followed by %NULL Returns %TRUE if the currently rendered contents have defined the given class name. %TRUE if @engine has @class_name defined a #GtkThemingEngine class name to look up Returns %TRUE if the currently rendered contents have the region defined. If @flags_return is not %NULL, it is set to the flags affecting the region. %TRUE if region is defined a #GtkThemingEngine a region name return location for region flags Looks up and resolves a color name in the current style’s color map. %TRUE if @color_name was found and resolved, %FALSE otherwise a #GtkThemingEngine color name to lookup Return location for the looked up color Returns %TRUE if there is a transition animation running for the current region (see gtk_style_context_push_animatable_region()). If @progress is not %NULL, the animation progress will be returned there, 0.0 means the state is closest to being %FALSE, while 1.0 means it’s closest to being %TRUE. This means transition animations will run from 0 to 1 when @state is being set to %TRUE and from 1 to 0 when it’s being set to %FALSE. Always returns %FALSE %TRUE if there is a running transition animation for @state. a #GtkThemingEngine a widget state return location for the transition progress The theming engine name, this name will be used when registering custom properties, for a theming engine named "Clearlooks" registering a "glossy" custom property, it could be referenced in the CSS file as |[ -Clearlooks-glossy: true; ]| Base class for theming engines. The parent class. Callback type for adding a function to update animations. See gtk_widget_add_tick_callback(). %G_SOURCE_CONTINUE if the tick callback should continue to be called, %G_SOURCE_REMOVE if the tick callback should be removed. the widget the frame clock for the widget (same as calling gtk_widget_get_frame_clock()) user data passed to gtk_widget_add_tick_callback(). A #GtkToggleAction corresponds roughly to a #GtkCheckMenuItem. It has an “active” state specifying whether the action has been checked or not. Creates a new #GtkToggleAction object. To add the action to a #GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). a new #GtkToggleAction A unique name for the action The label displayed in menu items and on buttons, or %NULL A tooltip for the action, or %NULL The stock icon to display in widgets representing the action, or %NULL Emits the “toggled” signal on the toggle action. the action object Returns the checked state of the toggle action. the checked state of the toggle action the action object Returns whether the action should have proxies like a radio action. whether the action should have proxies like a radio action. the action object Sets the checked state on the toggle action. the action object whether the action should be checked or not Sets whether the action should have proxies like a radio action. the action object whether the action should have proxies like a radio action Emits the “toggled” signal on the toggle action. the action object Whether the toggle action should be active. Whether the proxies for this action look like radio action proxies. This is an appearance property and thus only applies if #GtkActivatable:use-action-appearance is %TRUE. Should be connected if you wish to perform an action whenever the #GtkToggleAction state is changed. the action object #GtkToggleActionEntry structs are used with gtk_action_group_add_toggle_actions() to construct toggle actions. The name of the action. The stock id for the action, or the name of an icon from the icon theme. The label for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The accelerator for the action, in the format understood by gtk_accelerator_parse(). The tooltip for the action. This field should typically be marked for translation, see gtk_action_group_set_translation_domain(). The function to call when the action is activated. The initial state of the toggle action. A #GtkToggleButton is a #GtkButton 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 gtk_toggle_button_new() or gtk_toggle_button_new_with_label(). If using the former, it is advisable to pack a widget, (such as a #GtkLabel and/or a #GtkImage), into the toggle button’s container. (See #GtkButton for more information). The state of a #GtkToggleButton can be set specifically using gtk_toggle_button_set_active(), and retrieved using gtk_toggle_button_get_active(). To simply switch the state of a toggle button, use gtk_toggle_button_toggled(). # CSS nodes GtkToggleButton has a single CSS node with name button. To differentiate it from a plain #GtkButton, it gets the .toggle style class. ## Creating two #GtkToggleButton widgets. |[<!-- language="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); } ]| Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new(). a new toggle button. Creates a new toggle button with a text label. a new toggle button. a string containing the message to be placed in the toggle button. Creates a new #GtkToggleButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in @label indicate the mnemonic for the button. a new #GtkToggleButton the text of the button, with an underscore in front of the mnemonic character Emits the #GtkToggleButton::toggled signal on the #GtkToggleButton. There is no good reason for an application ever to call this function. a #GtkToggleButton. Queries a #GtkToggleButton and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. a #gboolean value. a #GtkToggleButton. Gets the value set by gtk_toggle_button_set_inconsistent(). %TRUE if the button is displayed as inconsistent, %FALSE otherwise a #GtkToggleButton Retrieves whether the button is displayed as a separate indicator and label. See gtk_toggle_button_set_mode(). %TRUE if the togglebutton is drawn as a separate indicator and label. a #GtkToggleButton Sets the status of the toggle button. Set to %TRUE if you want the GtkToggleButton to be “pressed in”, and %FALSE to raise it. This action causes the #GtkToggleButton::toggled signal and the #GtkButton::clicked signal to be emitted. a #GtkToggleButton. %TRUE or %FALSE. 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, gtk_toggle_button_set_inconsistent() only affects visual appearance, it doesn’t affect the semantics of the button. a #GtkToggleButton %TRUE if state is inconsistent 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 #GtkStackSwitcher. This function only affects instances of classes like #GtkCheckButton and #GtkRadioButton that derive from #GtkToggleButton, not instances of #GtkToggleButton itself. a #GtkToggleButton if %TRUE, draw the button as a separate indicator and label; if %FALSE, draw the button like a normal button Emits the #GtkToggleButton::toggled signal on the #GtkToggleButton. There is no good reason for an application ever to call this function. a #GtkToggleButton. Should be connected if you wish to perform an action whenever the #GtkToggleButton's state is changed. a #GtkToggleButton. A #GtkToggleToolButton is a #GtkToolItem that contains a toggle button. Use gtk_toggle_tool_button_new() to create a new GtkToggleToolButton. # CSS nodes GtkToggleToolButton has a single CSS node with name togglebutton. Returns a new #GtkToggleToolButton a newly created #GtkToggleToolButton Creates a new #GtkToggleToolButton containing the image and text from a stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. It is an error if @stock_id is not a name of a stock item. Use gtk_toggle_tool_button_new() instead. A new #GtkToggleToolButton the name of the stock item Queries a #GtkToggleToolButton and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. %TRUE if the toggle tool button is pressed in, %FALSE if not a #GtkToggleToolButton Sets the status of the toggle tool button. Set to %TRUE if you want the GtkToggleButton to be “pressed in”, and %FALSE to raise it. This action causes the toggled signal to be emitted. a #GtkToggleToolButton whether @button should be active If the toggle tool button should be pressed in. Emitted whenever the toggle tool button changes state. The parent class. #GtkToolButtons are #GtkToolItems containing buttons. Use gtk_tool_button_new() to create a new #GtkToolButton. The label of a #GtkToolButton is determined by the properties #GtkToolButton:label-widget, #GtkToolButton:label, and #GtkToolButton:stock-id. If #GtkToolButton:label-widget is non-%NULL, then that widget is used as the label. Otherwise, if #GtkToolButton:label is non-%NULL, that string is used as the label. Otherwise, if #GtkToolButton:stock-id is non-%NULL, the label is determined by the stock item. Otherwise, the button does not have a label. The icon of a #GtkToolButton is determined by the properties #GtkToolButton:icon-widget and #GtkToolButton:stock-id. If #GtkToolButton:icon-widget is non-%NULL, then that widget is used as the icon. Otherwise, if #GtkToolButton:stock-id is non-%NULL, the icon is determined by the stock item. Otherwise, the button does not have a icon. # CSS nodes GtkToolButton has a single CSS node with name toolbutton. Creates a new #GtkToolButton using @icon_widget as contents and @label as label. A new #GtkToolButton a widget that will be used as the button contents, or %NULL a string that will be used as label, or %NULL Creates a new #GtkToolButton containing the image and text from a stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK and #GTK_STOCK_APPLY. It is an error if @stock_id is not a name of a stock item. Use gtk_tool_button_new() together with gtk_image_new_from_icon_name() instead. A new #GtkToolButton the name of the stock item Returns the name of the themed icon for the tool button, see gtk_tool_button_set_icon_name(). the icon name or %NULL if the tool button has no themed icon a #GtkToolButton Return the widget used as icon widget on @button. See gtk_tool_button_set_icon_widget(). The widget used as icon on @button, or %NULL. a #GtkToolButton Returns the label used by the tool button, or %NULL 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. The label, or %NULL a #GtkToolButton Returns the widget used as label on @button. See gtk_tool_button_set_label_widget(). The widget used as label on @button, or %NULL. a #GtkToolButton Returns the name of the stock item. See gtk_tool_button_set_stock_id(). The returned string is owned by GTK+ and must not be freed or modifed. Use gtk_tool_button_get_icon_name() instead. the name of the stock item for @button. a #GtkToolButton Returns whether underscores in the label property are used as mnemonics on menu items on the overflow menu. See gtk_tool_button_set_use_underline(). %TRUE if underscores in the label property are used as mnemonics on menu items on the overflow menu. a #GtkToolButton Sets the icon for the tool button from a named themed icon. See the docs for #GtkIconTheme for more details. The #GtkToolButton:icon-name property only has an effect if not overridden by non-%NULL #GtkToolButton:label-widget, #GtkToolButton:icon-widget and #GtkToolButton:stock-id properties. a #GtkToolButton the name of the themed icon Sets @icon as the widget used as icon on @button. If @icon_widget is %NULL the icon is determined by the #GtkToolButton:stock-id property. If the #GtkToolButton:stock-id property is also %NULL, @button will not have an icon. a #GtkToolButton the widget used as icon, or %NULL Sets @label as the label used for the tool button. The #GtkToolButton:label property only has an effect if not overridden by a non-%NULL #GtkToolButton:label-widget property. If both the #GtkToolButton:label-widget and #GtkToolButton:label properties are %NULL, the label is determined by the #GtkToolButton:stock-id property. If the #GtkToolButton:stock-id property is also %NULL, @button will not have a label. a #GtkToolButton a string that will be used as label, or %NULL. Sets @label_widget as the widget that will be used as the label for @button. If @label_widget is %NULL the #GtkToolButton:label property is used as label. If #GtkToolButton:label is also %NULL, the label in the stock item determined by the #GtkToolButton:stock-id property is used as label. If #GtkToolButton:stock-id is also %NULL, @button does not have a label. a #GtkToolButton the widget used as label, or %NULL Sets the name of the stock item. See gtk_tool_button_new_from_stock(). The stock_id property only has an effect if not overridden by non-%NULL #GtkToolButton:label-widget and #GtkToolButton:icon-widget properties. Use gtk_tool_button_set_icon_name() instead. a #GtkToolButton a name of a stock item, or %NULL 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. a #GtkToolButton whether the button label has the form “_Open” The name of the themed icon displayed on the item. This property only has an effect if not overridden by #GtkToolButton:label-widget, #GtkToolButton:icon-widget or #GtkToolButton:stock-id properties. Use #GtkToolButton:icon-name instead. This signal is emitted when the tool button is clicked with the mouse or activated with the keyboard. The parent class. #GtkToolItems are widgets that can appear on a toolbar. To create a toolbar item that contain something else than a button, use gtk_tool_item_new(). Use gtk_container_add() to add a child widget to the tool item. For toolbar items that contain buttons, see the #GtkToolButton, #GtkToggleToolButton and #GtkRadioToolButton classes. See the #GtkToolbar class for a description of the toolbar widget, and #GtkToolShell for a description of the tool shell interface. Creates a new #GtkToolItem the new #GtkToolItem Emits the signal #GtkToolItem::toolbar_reconfigured on @tool_item. #GtkToolbar and other #GtkToolShell implementations use this function to notify children, when some aspect of their configuration changes. a #GtkToolItem Returns the ellipsize mode used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out how text should be ellipsized. a #PangoEllipsizeMode indicating how text in @tool_item should be ellipsized. a #GtkToolItem Returns whether @tool_item is allocated extra space. See gtk_tool_item_set_expand(). %TRUE if @tool_item is allocated extra space. a #GtkToolItem Returns whether @tool_item is the same size as other homogeneous items. See gtk_tool_item_set_homogeneous(). %TRUE if the item is the same size as other homogeneous items. a #GtkToolItem Returns the icon size used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out what size icons they should use. a #GtkIconSize indicating the icon size used for @tool_item a #GtkToolItem Returns whether @tool_item is considered important. See gtk_tool_item_set_is_important() %TRUE if @tool_item is considered important. a #GtkToolItem Returns the orientation used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out what size icons they should use. a #GtkOrientation indicating the orientation used for @tool_item a #GtkToolItem If @menu_item_id matches the string passed to gtk_tool_item_set_proxy_menu_item() return the corresponding #GtkMenuItem. Custom subclasses of #GtkToolItem should use this function to update their menu item when the #GtkToolItem changes. That the @menu_item_ids must match ensures that a #GtkToolItem will not inadvertently change a menu item that they did not create. The #GtkMenuItem passed to gtk_tool_item_set_proxy_menu_item(), if the @menu_item_ids match. a #GtkToolItem a string used to identify the menu item Returns the relief style of @tool_item. See gtk_button_set_relief(). Custom subclasses of #GtkToolItem should call this function in the handler of the #GtkToolItem::toolbar_reconfigured signal to find out the relief style of buttons. a #GtkReliefStyle indicating the relief style used for @tool_item. a #GtkToolItem Returns the text alignment used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out how text should be aligned. a #gfloat indicating the horizontal text alignment used for @tool_item a #GtkToolItem: Returns the text orientation used for @tool_item. Custom subclasses of #GtkToolItem should call this function to find out how text should be orientated. a #GtkOrientation indicating the text orientation used for @tool_item a #GtkToolItem Returns the size group used for labels in @tool_item. Custom subclasses of #GtkToolItem should call this function and use the size group for labels. a #GtkSizeGroup a #GtkToolItem Returns the toolbar style used for @tool_item. Custom subclasses of #GtkToolItem should call this function in the handler of the GtkToolItem::toolbar_reconfigured signal to find out in what style the toolbar is displayed and change themselves accordingly Possibilities are: - %GTK_TOOLBAR_BOTH, meaning the tool item should show both an icon and a label, stacked vertically - %GTK_TOOLBAR_ICONS, meaning the toolbar shows only icons - %GTK_TOOLBAR_TEXT, meaning the tool item should only show text - %GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show both an icon and a label, arranged horizontally A #GtkToolbarStyle indicating the toolbar style used for @tool_item. a #GtkToolItem Returns whether @tool_item has a drag window. See gtk_tool_item_set_use_drag_window(). %TRUE if @tool_item uses a drag window. a #GtkToolItem Returns whether the @tool_item is visible on toolbars that are docked horizontally. %TRUE if @tool_item is visible on toolbars that are docked horizontally. a #GtkToolItem Returns whether @tool_item is visible when the toolbar is docked vertically. See gtk_tool_item_set_visible_vertical(). Whether @tool_item is visible when the toolbar is docked vertically a #GtkToolItem Calling this function signals to the toolbar that the overflow menu item for @tool_item 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 #GtkToolItem::create-menu-proxy signal. a #GtkToolItem Returns the #GtkMenuItem that was last set by gtk_tool_item_set_proxy_menu_item(), ie. the #GtkMenuItem that is going to appear in the overflow menu. The #GtkMenuItem that is going to appear in the overflow menu for @tool_item. a #GtkToolItem Sets whether @tool_item 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. a #GtkToolItem Whether @tool_item is allocated extra space Sets whether @tool_item 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. a #GtkToolItem whether @tool_item is the same size as other homogeneous items Sets whether @tool_item should be considered important. The #GtkToolButton class uses this property to determine whether to show or hide its label when the toolbar style is %GTK_TOOLBAR_BOTH_HORIZ. The result is that only tool buttons with the “is_important” property set have labels, an effect known as “priority text” a #GtkToolItem whether the tool item should be considered important Sets the #GtkMenuItem 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 gtk_tool_item_get_proxy_menu_item(). See also #GtkToolItem::create-menu-proxy. a #GtkToolItem a string used to identify @menu_item a #GtkMenuItem to use in the overflow menu, or %NULL Sets the markup text to be displayed as tooltip on the item. See gtk_widget_set_tooltip_markup(). a #GtkToolItem markup text to be used as tooltip for @tool_item Sets the text to be displayed as tooltip on the item. See gtk_widget_set_tooltip_text(). a #GtkToolItem text to be used as tooltip for @tool_item Sets whether @tool_item has a drag window. When %TRUE the toolitem can be used as a drag source through gtk_drag_source_set(). When @tool_item has a drag window it will intercept all events, even those that would otherwise be sent to a child of @tool_item. a #GtkToolItem Whether @tool_item has a drag window. Sets whether @tool_item is visible when the toolbar is docked horizontally. a #GtkToolItem Whether @tool_item is visible when in horizontal mode Sets whether @tool_item 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 @tool_item will not appear on toolbars that are docked vertically. a #GtkToolItem whether @tool_item is visible when the toolbar is in vertical mode Emits the signal #GtkToolItem::toolbar_reconfigured on @tool_item. #GtkToolbar and other #GtkToolShell implementations use this function to notify children, when some aspect of their configuration changes. a #GtkToolItem 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 gtk_tool_item_set_proxy_menu_item() with a %NULL pointer and return %TRUE to indicate that the item should not appear in the overflow menu - call gtk_tool_item_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 gtk_tool_item_rebuild_menu() to invalidate the cache and ensure that the toolbar rebuilds its overflow menu. %TRUE if the signal was handled, %FALSE if not This signal is emitted when some property of the toolbar that the item is a child of changes. For custom subclasses of #GtkToolItem, the default handler of this signal use the functions - gtk_tool_shell_get_orientation() - gtk_tool_shell_get_style() - gtk_tool_shell_get_icon_size() - gtk_tool_shell_get_relief_style() to find out what the toolbar should look like and change themselves accordingly. The parent class. a #GtkToolItem A #GtkToolItemGroup is used together with #GtkToolPalette to add #GtkToolItems to a palette like container with different categories and drag and drop support. # CSS nodes GtkToolItemGroup has a single CSS node named toolitemgroup. Creates a new tool item group with label @label. a new #GtkToolItemGroup. the label of the new group Gets whether @group is collapsed or expanded. %TRUE if @group is collapsed, %FALSE if it is expanded a GtkToolItemGroup Gets the tool item at position (x, y). the #GtkToolItem at position (x, y) a #GtkToolItemGroup the x position the y position Gets the ellipsization mode of @group. the #PangoEllipsizeMode of @group a #GtkToolItemGroup Gets the relief mode of the header button of @group. the #GtkReliefStyle a #GtkToolItemGroup Gets the position of @item in @group as index. the index of @item in @group or -1 if @item is no child of @group a #GtkToolItemGroup a #GtkToolItem Gets the label of @group. the label of @group. The label is an internal string of @group and must not be modified. Note that %NULL is returned if a custom label has been set with gtk_tool_item_group_set_label_widget() a #GtkToolItemGroup Gets the label widget of @group. See gtk_tool_item_group_set_label_widget(). the label widget of @group a #GtkToolItemGroup Gets the number of tool items in @group. the number of tool items in @group a #GtkToolItemGroup Gets the tool item at @index in group. the #GtkToolItem at index a #GtkToolItemGroup the index Inserts @item at @position in the list of children of @group. a #GtkToolItemGroup the #GtkToolItem to insert into @group the position of @item in @group, starting with 0. The position -1 means end of list. Sets whether the @group should be collapsed or expanded. a #GtkToolItemGroup whether the @group should be collapsed or expanded Sets the ellipsization mode which should be used by labels in @group. a #GtkToolItemGroup the #PangoEllipsizeMode labels in @group should use Set the button relief of the group header. See gtk_button_set_relief() for details. a #GtkToolItemGroup the #GtkReliefStyle Sets the position of @item in the list of children of @group. a #GtkToolItemGroup the #GtkToolItem to move to a new position, should be a child of @group. the new position of @item in @group, starting with 0. The position -1 means end of list. Sets the label of the tool item group. The label is displayed in the header of the group. a #GtkToolItemGroup the new human-readable label of of the group 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. a #GtkToolItemGroup the widget to be displayed in place of the usual label The parent class. A #GtkToolPalette allows you to add #GtkToolItems to a palette-like container with different categories and drag and drop support. A #GtkToolPalette is created with a call to gtk_tool_palette_new(). #GtkToolItems cannot be added directly to a #GtkToolPalette - instead they are added to a #GtkToolItemGroup which can than be added to a #GtkToolPalette. To add a #GtkToolItemGroup to a #GtkToolPalette, use gtk_container_add(). |[<!-- language="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 #GtkToolPalette is to call gtk_tool_palette_add_drag_dest() with the desired drag source @palette and the desired drag target @widget. Then gtk_tool_palette_get_drag_item() can be used to get the dragged item in the #GtkWidget::drag-data-received signal handler of the drag target. |[<!-- language="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 GtkToolPalette has a single CSS node named toolpalette. Creates a new tool palette. a new #GtkToolPalette Get the target entry for a dragged #GtkToolItemGroup. the #GtkTargetEntry for a dragged group Gets the target entry for a dragged #GtkToolItem. the #GtkTargetEntry for a dragged item. Sets @palette as drag source (see gtk_tool_palette_set_drag_source()) and sets @widget as a drag destination for drags from @palette. See gtk_drag_dest_set(). a #GtkToolPalette a #GtkWidget which should be a drag destination for @palette the flags that specify what actions GTK+ should take for drops on that widget the #GtkToolPaletteDragTargets which the widget should support the #GdkDragActions which the widget should suppport Get the dragged item from the selection. This could be a #GtkToolItem or a #GtkToolItemGroup. the dragged item in selection a #GtkToolPalette a #GtkSelectionData Gets the group at position (x, y). the #GtkToolItemGroup at position or %NULL if there is no such group a #GtkToolPalette the x position the y position Gets the item at position (x, y). See gtk_tool_palette_get_drop_group(). the #GtkToolItem at position or %NULL if there is no such item a #GtkToolPalette the x position the y position Gets whether @group is exclusive or not. See gtk_tool_palette_set_exclusive(). %TRUE if @group is exclusive a #GtkToolPalette a #GtkToolItemGroup which is a child of palette Gets whether group should be given extra space. See gtk_tool_palette_set_expand(). %TRUE if group should be given extra space, %FALSE otherwise a #GtkToolPalette a #GtkToolItemGroup which is a child of palette Gets the position of @group in @palette as index. See gtk_tool_palette_set_group_position(). the index of group or -1 if @group is not a child of @palette a #GtkToolPalette a #GtkToolItemGroup Gets the horizontal adjustment of the tool palette. Use gtk_scrollable_get_hadjustment() the horizontal adjustment of @palette a #GtkToolPalette Gets the size of icons in the tool palette. See gtk_tool_palette_set_icon_size(). the #GtkIconSize of icons in the tool palette a #GtkToolPalette Gets the style (icons, text or both) of items in the tool palette. the #GtkToolbarStyle of items in the tool palette. a #GtkToolPalette Gets the vertical adjustment of the tool palette. Use gtk_scrollable_get_vadjustment() the vertical adjustment of @palette a #GtkToolPalette 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 gtk_drag_source_set(). a #GtkToolPalette the #GtkToolPaletteDragTargets which the widget should support Sets whether the group should be exclusive or not. If an exclusive group is expanded all other groups are collapsed. a #GtkToolPalette a #GtkToolItemGroup which is a child of palette whether the group should be exclusive or not Sets whether the group should be given extra space. a #GtkToolPalette a #GtkToolItemGroup which is a child of palette whether the group should be given extra space 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. a #GtkToolPalette a #GtkToolItemGroup which is a child of palette a new index for group Sets the size of icons in the tool palette. a #GtkToolPalette the #GtkIconSize that icons in the tool palette shall have Sets the style (text, icons or both) of items in the tool palette. a #GtkToolPalette the #GtkToolbarStyle that items in the tool palette shall have Unsets the tool palette icon size set with gtk_tool_palette_set_icon_size(), so that user preferences will be used to determine the icon size. a #GtkToolPalette Unsets a toolbar style set with gtk_tool_palette_set_style(), so that user preferences will be used to determine the toolbar style. a #GtkToolPalette 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. Is %TRUE if the #GtkToolPalette:icon-size property has been set. The style of items in the tool palette. The parent class. Flags used to specify the supported drag targets. Support drag of items. Support drag of groups. The #GtkToolShell interface allows container widgets to provide additional information when embedding #GtkToolItem widgets. Retrieves the current ellipsize mode for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_ellipsize_mode() instead. the current ellipsize mode of @shell a #GtkToolShell Retrieves the current orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_orientation() instead. the current orientation of @shell a #GtkToolShell Returns the relief style of buttons on @shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_relief_style() instead. The relief style of buttons on @shell. a #GtkToolShell Retrieves whether the tool shell has text, icons, or both. Tool items must not call this function directly, but rely on gtk_tool_item_get_toolbar_style() instead. the current style of @shell a #GtkToolShell Retrieves the current text alignment for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_alignment() instead. the current text alignment of @shell a #GtkToolShell Retrieves the current text orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_orientation() instead. the current text orientation of @shell a #GtkToolShell Retrieves the current text size group for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_size_group() instead. the current text size group of @shell a #GtkToolShell 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 gtk_tool_item_rebuild_menu() instead. a #GtkToolShell Retrieves the current ellipsize mode for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_ellipsize_mode() instead. the current ellipsize mode of @shell a #GtkToolShell Retrieves the icon size for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_icon_size() instead. the current size (#GtkIconSize) for icons of @shell a #GtkToolShell Retrieves the current orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_orientation() instead. the current orientation of @shell a #GtkToolShell Returns the relief style of buttons on @shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_relief_style() instead. The relief style of buttons on @shell. a #GtkToolShell Retrieves whether the tool shell has text, icons, or both. Tool items must not call this function directly, but rely on gtk_tool_item_get_toolbar_style() instead. the current style of @shell a #GtkToolShell Retrieves the current text alignment for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_alignment() instead. the current text alignment of @shell a #GtkToolShell Retrieves the current text orientation for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_orientation() instead. the current text orientation of @shell a #GtkToolShell Retrieves the current text size group for the tool shell. Tool items must not call this function directly, but rely on gtk_tool_item_get_text_size_group() instead. the current text size group of @shell a #GtkToolShell 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 gtk_tool_item_rebuild_menu() instead. a #GtkToolShell Virtual function table for the #GtkToolShell interface. the current orientation of @shell a #GtkToolShell the current style of @shell a #GtkToolShell The relief style of buttons on @shell. a #GtkToolShell a #GtkToolShell the current text orientation of @shell a #GtkToolShell the current text alignment of @shell a #GtkToolShell the current ellipsize mode of @shell a #GtkToolShell the current text size group of @shell a #GtkToolShell A toolbar is created with a call to gtk_toolbar_new(). A toolbar can contain instances of a subclass of #GtkToolItem. To add a #GtkToolItem to the a toolbar, use gtk_toolbar_insert(). To remove an item from the toolbar use gtk_container_remove(). To add a button to the toolbar, add an instance of #GtkToolButton. Toolbar items can be visually grouped by adding instances of #GtkSeparatorToolItem to the toolbar. If the GtkToolbar child property “expand” is #TRUE and the property #GtkSeparatorToolItem: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 #GtkToolItem child that has a proxy menu item. To disable this and request enough size for all children, call gtk_toolbar_set_show_arrow() to set #GtkToolbar:show-arrow to %FALSE. Creating a context menu for the toolbar can be done by connecting to the #GtkToolbar::popup-context-menu signal. # CSS nodes GtkToolbar has a single CSS node with name toolbar. Creates a new toolbar. the newly-created toolbar. Returns the position corresponding to the indicated point on @toolbar. 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 @toolbar coordinates. The position corresponding to the point (@x, @y) on the toolbar. a #GtkToolbar x coordinate of a point on the toolbar y coordinate of a point on the toolbar Retrieves the icon size for the toolbar. See gtk_toolbar_set_icon_size(). the current icon size for the icons on the toolbar. a #GtkToolbar Returns the position of @item on the toolbar, starting from 0. It is an error if @item is not a child of the toolbar. the position of item on the toolbar. a #GtkToolbar a #GtkToolItem that is a child of @toolbar Returns the number of items on the toolbar. the number of items on the toolbar a #GtkToolbar Returns the @n'th item on @toolbar, or %NULL if the toolbar does not contain an @n'th item. The @n'th #GtkToolItem on @toolbar, or %NULL if there isn’t an @n'th item. a #GtkToolbar A position on the toolbar Returns the relief style of buttons on @toolbar. See gtk_button_set_relief(). The relief style of buttons on @toolbar. a #GtkToolbar Returns whether the toolbar has an overflow menu. See gtk_toolbar_set_show_arrow(). %TRUE if the toolbar has an overflow menu. a #GtkToolbar Retrieves whether the toolbar has text, icons, or both . See gtk_toolbar_set_style(). the current style of @toolbar a #GtkToolbar Insert a #GtkToolItem 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. a #GtkToolbar a #GtkToolItem the position of the new item Highlights @toolbar to give an idea of what it would look like if @item was added to @toolbar at the position indicated by @index_. If @item is %NULL, 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. a #GtkToolbar a #GtkToolItem, or %NULL to turn of highlighting a position on @toolbar 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. A #GtkToolbar The #GtkIconSize that stock icons in the toolbar shall have. Sets whether to show an overflow menu when @toolbar isn’t allocated enough size to show all of its items. If %TRUE, items which can’t fit in @toolbar, and which have a proxy menu item set by gtk_tool_item_set_proxy_menu_item() or #GtkToolItem::create-menu-proxy, will be available in an overflow menu, which can be opened by an added arrow button. If %FALSE, @toolbar will request enough size to fit all of its child items without any overflow. a #GtkToolbar Whether to show an overflow menu Alters the view of @toolbar to display either icons only, text only, or both. a #GtkToolbar. the new style for @toolbar. Unsets toolbar icon size set with gtk_toolbar_set_icon_size(), so that user preferences will be used to determine the icon size. a #GtkToolbar Unsets a toolbar style set with gtk_toolbar_set_style(), so that user preferences will be used to determine the toolbar style. a #GtkToolbar 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. Is %TRUE if the icon-size property has been set. A keybinding signal used internally by GTK+. This signal can't be used in application code %TRUE if the signal was handled, %FALSE if not %TRUE if the first item should be focused Emitted when the orientation of the toolbar changes. the new #GtkOrientation of the toolbar 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. return %TRUE if the signal was handled, %FALSE if not the x coordinate of the point where the menu should appear the y coordinate of the point where the menu should appear the mouse button the user pressed, or -1 Emitted when the style of the toolbar changes. the new #GtkToolbarStyle of the toolbar Whether spacers are vertical lines or just blank. Use blank spacers. Use vertical lines for spacers. Used to customize the appearance of a #GtkToolbar. 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. Buttons display only icons in the toolbar. Buttons display only text labels in the toolbar. Buttons display text and icons in the toolbar. Buttons display icons and text alongside each other, rather than vertically stacked Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text() or gtk_widget_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 #GtkTreeView row or cell, you will have to do a little more work: - Set the #GtkWidget: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 #GtkWidget::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 GtkTooltip object. This is the object that we are about to display as a tooltip, and can be manipulated in your callback using functions like gtk_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 #GtkWindow which will be used as tooltip window. This works as follows: - Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as before. Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as tooltip window. - In the #GtkWidget::query-tooltip callback you can access your window using gtk_widget_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. 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. a #GdkDisplay 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 #GtkImage and #GtkLabel is embedded in the tooltip, which can be configured using gtk_tooltip_set_markup() and gtk_tooltip_set_icon(). a #GtkTooltip a #GtkWidget, or %NULL to unset the old custom widget. Sets the icon of the tooltip (which is in front of the text) to be @pixbuf. If @pixbuf is %NULL, the image will be hidden. a #GtkTooltip a #GdkPixbuf, or %NULL 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 %NULL, the image will be hidden. a #GtkTooltip a #GIcon representing the icon, or %NULL a stock icon size (#GtkIconSize) 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 %NULL, the image will be hidden. a #GtkTooltip an icon name, or %NULL a stock icon size (#GtkIconSize) Sets the icon of the tooltip (which is in front of the text) to be the stock item indicated by @stock_id with the size indicated by @size. If @stock_id is %NULL, the image will be hidden. Use gtk_tooltip_set_icon_from_icon_name() instead. a #GtkTooltip a stock id, or %NULL a stock icon size (#GtkIconSize) Sets the text of the tooltip to be @markup, which is marked up with the [Pango text markup language][PangoMarkupFormat]. If @markup is %NULL, the label will be hidden. a #GtkTooltip a markup string (see [Pango markup format][PangoMarkupFormat]) or %NULL Sets the text of the tooltip to be @text. If @text is %NULL, the label will be hidden. See also gtk_tooltip_set_markup(). a #GtkTooltip a text string or %NULL 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 #GtkTreeView rows and cells, #GtkIconViews, etc. For setting tooltips on #GtkTreeView, please refer to the convenience functions for this: gtk_tree_view_set_tooltip_row() and gtk_tree_view_set_tooltip_cell(). a #GtkTooltip a #GdkRectangle List of children. The function used to translate messages in e.g. #GtkIconFactory and #GtkActionGroup. the translated message The id of the message. In #GtkActionGroup this will be a label or tooltip from a #GtkActionEntry. user data passed in when registering the function A function to set the properties of a cell instead of just using the straight mapping between the cell and the model. This is useful for customizing the cell renderer. For example, a function might get an integer from the @tree_model, and render it to the “text” attribute of “cell” by converting it to its written equivalent. This is set by calling gtk_tree_view_column_set_cell_data_func() A #GtkTreeViewColumn The #GtkCellRenderer that is being rendered by @tree_column The #GtkTreeModel being rendered A #GtkTreeIter of the current row rendered user data Asks the #GtkTreeDragDest 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! whether a new row was created before position @dest a #GtkTreeDragDest row to drop in front of data to drop 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. %TRUE if a drop is possible before @dest_path a #GtkTreeDragDest destination row the data being dragged Asks the #GtkTreeDragDest 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! whether a new row was created before position @dest a #GtkTreeDragDest row to drop in front of data to drop 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. %TRUE if a drop is possible before @dest_path a #GtkTreeDragDest destination row the data being dragged whether a new row was created before position @dest a #GtkTreeDragDest row to drop in front of data to drop %TRUE if a drop is possible before @dest_path a #GtkTreeDragDest destination row the data being dragged Asks the #GtkTreeDragSource 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! %TRUE if the row was successfully deleted a #GtkTreeDragSource row that was being dragged Asks the #GtkTreeDragSource 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! %TRUE if data of the required type was provided a #GtkTreeDragSource row that was dragged a #GtkSelectionData to fill with data from the dragged row Asks the #GtkTreeDragSource 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. %TRUE if the row can be dragged a #GtkTreeDragSource row on which user is initiating a drag Asks the #GtkTreeDragSource 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! %TRUE if the row was successfully deleted a #GtkTreeDragSource row that was being dragged Asks the #GtkTreeDragSource 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! %TRUE if data of the required type was provided a #GtkTreeDragSource row that was dragged a #GtkSelectionData to fill with data from the dragged row Asks the #GtkTreeDragSource 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. %TRUE if the row can be dragged a #GtkTreeDragSource row on which user is initiating a drag %TRUE if the row can be dragged a #GtkTreeDragSource row on which user is initiating a drag %TRUE if data of the required type was provided a #GtkTreeDragSource row that was dragged a #GtkSelectionData to fill with data from the dragged row %TRUE if the row was successfully deleted a #GtkTreeDragSource row that was being dragged The #GtkTreeIter is the primary structure for accessing a #GtkTreeModel. Models are expected to put a unique integer in the @stamp member, and put model-specific data in the three @user_data members. a unique stamp to catch invalid iterators model-specific data model-specific data model-specific data Creates a dynamically allocated tree iterator as a copy of @iter. 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 gtk_tree_iter_free(). a newly-allocated copy of @iter a #GtkTreeIter-struct Frees an iterator that has been allocated by gtk_tree_iter_copy(). This function is mainly used for language bindings. a dynamically allocated tree iterator A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b respectively. If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the #GtkTreeSortable behaves as expected, the GtkTreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive. For example, if @model is a product catalogue, then a compare function for the “price” column could be one which returns `price_of(@a) - price_of(@b)`. a negative integer, zero or a positive integer depending on whether @a sorts before, with or after @b The #GtkTreeModel the comparison is within A #GtkTreeIter in @model Another #GtkTreeIter in @model Data passed when the compare func is assigned e.g. by gtk_tree_sortable_set_sort_func() The #GtkTreeModel interface defines a generic tree interface for use by the #GtkTreeView 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 #GtkTreeView 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 #GtkTreeStore and the #GtkListStore. 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 #GtkTreePath-struct and the #GtkTreeIter-struct (“iter” is short for iterator). Most of the interface consists of operations on a #GtkTreeIter-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 #GtkTreePath-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 #GtkTreeIter-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 gtk_tree_model_get_iter(). These iterators are the primary way of accessing a model and are similar to the iterators used by #GtkTextBuffer. 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 #GtkListStore model, which is internally a simple linked list, stores a list node in one of the pointers. The #GtkTreeModelSort 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 #GtkTreeStore and #GtkListStore). 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 #GTK_TREE_MODEL_ITERS_PERSIST 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 #GtkTreeIter-struct |[<!-- language="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 #GtkListStore. For information on how to write such a function, see the #GtkListStore documentation. ## Reading data from a #GtkTreeModel |[<!-- language="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 #GtkTreeModel interface contains two methods for reference counting: gtk_tree_model_ref_node() and gtk_tree_model_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. #GtkTreeView 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). Returns the type of the column. the type of the column a #GtkTreeModel the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of #GtkTreeModelFlags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a #GtkTreeModel 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. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct the #GtkTreePath-struct Returns the number of columns supported by @tree_model. the number of columns a #GtkTreeModel Returns a newly-created #GtkTreePath-struct referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created #GtkTreePath-struct a #GtkTreeModel the #GtkTreeIter-struct Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a #GtkTreeModel the #GtkTreeIter-struct the column to lookup the value at an empty #GValue to set 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 %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a #GtkTreeModel the new #GtkTreeIter-struct to be set to the child the #GtkTreeIter-struct, or %NULL Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a #GtkTreeModel the #GtkTreeIter-struct to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a #GtkTreeModel the #GtkTreeIter-struct, or %NULL 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. %TRUE if @iter has been changed to the next node a #GtkTreeModel the #GtkTreeIter-struct 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 %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a #GtkTreeModel the #GtkTreeIter-struct to set to the nth child the #GtkTreeIter-struct to get the child from, or %NULL. the index of the desired child 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. %TRUE, if @iter is set to the parent of @child a #GtkTreeModel the new #GtkTreeIter-struct to set to the parent the #GtkTreeIter-struct 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. %TRUE if @iter has been changed to the previous node a #GtkTreeModel the #GtkTreeIter-struct 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. a #GtkTreeModel the #GtkTreeIter-struct Emits the #GtkTreeModel::row-changed signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-deleted signal on @tree_model. 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. a #GtkTreeModel a #GtkTreePath-struct pointing to the previous location of the deleted row Emits the #GtkTreeModel::row-has-child-toggled signal on @tree_model. This should be called by models after the child state of a node changes. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-inserted signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the inserted row a valid #GtkTreeIter-struct pointing to the inserted row Emits the #GtkTreeModel::rows-reordered signal on @tree_model. This should be called by models when their rows have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 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` 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 gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a #GtkTreeModel the #GtkTreeIter-struct Creates a new #GtkTreeModel, with @child_model as the child_model and @root as the virtual root. A new #GtkTreeModel. A #GtkTreeModel. A #GtkTreePath or %NULL. Calls func on each node in model in a depth-first fashion. If @func returns %TRUE, then the tree ceases to be walked, and gtk_tree_model_foreach() returns. a #GtkTreeModel a function to be called on each row user data to passed to @func 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. a #GtkTreeModel a row in @tree_model pairs of column number and value return locations, terminated by -1 Returns the type of the column. the type of the column a #GtkTreeModel the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of #GtkTreeModelFlags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a #GtkTreeModel 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. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct the #GtkTreePath-struct 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. %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct Sets @iter to a valid iterator pointing to @path_string, if it exists. Otherwise, @iter is left invalid and %FALSE is returned. %TRUE, if @iter was set a #GtkTreeModel an uninitialized #GtkTreeIter-struct a string representation of a #GtkTreePath-struct Returns the number of columns supported by @tree_model. the number of columns a #GtkTreeModel Returns a newly-created #GtkTreePath-struct referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created #GtkTreePath-struct a #GtkTreeModel the #GtkTreeIter-struct 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. a newly-allocated string. Must be freed with g_free(). a #GtkTreeModel a #GtkTreeIter-struct See gtk_tree_model_get(), this version takes a va_list for language bindings to use. a #GtkTreeModel a row in @tree_model va_list of column/return location pairs Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a #GtkTreeModel the #GtkTreeIter-struct the column to lookup the value at an empty #GValue to set 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 %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a #GtkTreeModel the new #GtkTreeIter-struct to be set to the child the #GtkTreeIter-struct, or %NULL Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a #GtkTreeModel the #GtkTreeIter-struct to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a #GtkTreeModel the #GtkTreeIter-struct, or %NULL 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. %TRUE if @iter has been changed to the next node a #GtkTreeModel the #GtkTreeIter-struct 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 %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a #GtkTreeModel the #GtkTreeIter-struct to set to the nth child the #GtkTreeIter-struct to get the child from, or %NULL. the index of the desired child 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. %TRUE, if @iter is set to the parent of @child a #GtkTreeModel the new #GtkTreeIter-struct to set to the parent the #GtkTreeIter-struct 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. %TRUE if @iter has been changed to the previous node a #GtkTreeModel the #GtkTreeIter-struct 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. a #GtkTreeModel the #GtkTreeIter-struct Emits the #GtkTreeModel::row-changed signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-deleted signal on @tree_model. 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. a #GtkTreeModel a #GtkTreePath-struct pointing to the previous location of the deleted row Emits the #GtkTreeModel::row-has-child-toggled signal on @tree_model. This should be called by models after the child state of a node changes. a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row Emits the #GtkTreeModel::row-inserted signal on @tree_model. a #GtkTreeModel a #GtkTreePath-struct pointing to the inserted row a valid #GtkTreeIter-struct pointing to the inserted row Emits the #GtkTreeModel::rows-reordered signal on @tree_model. This should be called by models when their rows have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 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` Emits the #GtkTreeModel::rows-reordered signal on @tree_model. This should be called by models when their rows have been reordered. a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 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 of @new_order array 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 gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a #GtkTreeModel the #GtkTreeIter-struct This signal is emitted when a row in the model has changed. a #GtkTreePath-struct identifying the changed row a valid #GtkTreeIter-struct pointing to the changed row 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. a #GtkTreePath-struct identifying the row This signal is emitted when a row has gotten the first child row or lost its last child row. a #GtkTreePath-struct identifying the row a valid #GtkTreeIter-struct pointing to the row 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. a #GtkTreePath-struct identifying the new row a valid #GtkTreeIter-struct pointing to the new row This signal is emitted when the children of a node in the #GtkTreeModel 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. a #GtkTreePath-struct identifying the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 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` A #GtkTreeModelFilter 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 #GtkTreePath indicating the root node for the filter at construction time. The basic API is similar to #GtkTreeModelSort. For an example on its usage, see the section on #GtkTreeModelSort. When using #GtkTreeModelFilter, it is important to realize that #GtkTreeModelFilter 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. #GtkTreeModelFilter 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 #GtkTreeModel documentation. (Note that e.g. #GtkTreeStore 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 #GtkTreeModel section). Determining the visibility state of a given node based on the state of its child nodes is a frequently occurring use case. Therefore, #GtkTreeModelFilter 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, #GtkTreeModelFilter 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 #GtkTreeModelFilter'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), #GtkTreeModelFilter 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 #GtkTreeStore 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. This function should almost never be called. It clears the @filter of any cached iterators that haven’t been reffed with gtk_tree_model_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. A #GtkTreeModelFilter. Sets @filter_iter to point to the row in @filter that corresponds to the row pointed at by @child_iter. If @filter_iter was not set, %FALSE is returned. %TRUE, if @filter_iter was set, i.e. if @child_iter is a valid iterator pointing to a visible row in child model. A #GtkTreeModelFilter. An uninitialized #GtkTreeIter. A valid #GtkTreeIter pointing to a row on the child model. Converts @child_path to a path relative to @filter. 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 @filter, then %NULL is returned. A newly allocated #GtkTreePath, or %NULL. A #GtkTreeModelFilter. A #GtkTreePath to convert. Sets @child_iter to point to the row pointed to by @filter_iter. A #GtkTreeModelFilter. An uninitialized #GtkTreeIter. A valid #GtkTreeIter pointing to a row on @filter. Converts @filter_path to a path on the child model of @filter. That is, @filter_path points to a location in @filter. 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, %NULL is returned. A newly allocated #GtkTreePath, or %NULL. A #GtkTreeModelFilter. A #GtkTreePath to convert. Returns a pointer to the child model of @filter. A pointer to a #GtkTreeModel. A #GtkTreeModelFilter. Emits ::row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is visible or not. A #GtkTreeModelFilter. 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 gtk_tree_model_filter_set_modify_func() can only be called once for a given filter model. A #GtkTreeModelFilter. The number of columns in the filter model. The #GTypes of the columns. A #GtkTreeModelFilterModifyFunc User data to pass to the modify function, or %NULL. Destroy notifier of @data, or %NULL. Sets @column of the child_model to be the column where @filter 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 gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A #GtkTreeModelFilter A #gint which is the column containing the visible information Sets the visible function used when filtering the @filter 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 gtk_tree_model_filter_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. |[<!-- language="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 gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A #GtkTreeModelFilter A #GtkTreeModelFilterVisibleFunc, the visible function User data to pass to the visible function, or %NULL Destroy notifier of @data, or %NULL A function which calculates display values from raw values in the model. It must fill @value with the display value for the column @column in the row indicated by @iter. Since this function is called for each data access, it’s not a particularly efficient operation. the #GtkTreeModelFilter a #GtkTreeIter pointing to the row whose display values are determined A #GValue which is already initialized for with the correct type for the column @column. the column whose display value is determined user data given to gtk_tree_model_filter_set_modify_func() A function which decides whether the row indicated by @iter is visible. Whether the row indicated by @iter is visible. the child model of the #GtkTreeModelFilter a #GtkTreeIter pointing to the row in @model whose visibility is determined user data given to gtk_tree_model_filter_set_visible_func() These flags indicate various properties of a #GtkTreeModel. They are returned by gtk_tree_model_get_flags(), and must be static for the lifetime of the object. A more complete description of #GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of this section. iterators survive all signals emitted by the tree the model is a list only, and never has children Type of the callback passed to gtk_tree_model_foreach() to iterate over the rows in a tree model. %TRUE to stop iterating, %FALSE to continue the #GtkTreeModel being iterated the current #GtkTreePath the current #GtkTreeIter The user data passed to gtk_tree_model_foreach() a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row a #GtkTreeModel a #GtkTreePath-struct pointing to the inserted row a valid #GtkTreeIter-struct pointing to the inserted row a #GtkTreeModel a #GtkTreePath-struct pointing to the changed row a valid #GtkTreeIter-struct pointing to the changed row a #GtkTreeModel a #GtkTreePath-struct pointing to the previous location of the deleted row a #GtkTreeModel a #GtkTreePath-struct pointing to the tree node whose children have been reordered a valid #GtkTreeIter-struct pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 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` the flags supported by this interface a #GtkTreeModel the number of columns a #GtkTreeModel the type of the column a #GtkTreeModel the column index %TRUE, if @iter was set a #GtkTreeModel the uninitialized #GtkTreeIter-struct the #GtkTreePath-struct a newly-created #GtkTreePath-struct a #GtkTreeModel the #GtkTreeIter-struct a #GtkTreeModel the #GtkTreeIter-struct the column to lookup the value at an empty #GValue to set %TRUE if @iter has been changed to the next node a #GtkTreeModel the #GtkTreeIter-struct %TRUE if @iter has been changed to the previous node a #GtkTreeModel the #GtkTreeIter-struct %TRUE, if @iter has been set to the first child a #GtkTreeModel the new #GtkTreeIter-struct to be set to the child the #GtkTreeIter-struct, or %NULL %TRUE if @iter has children a #GtkTreeModel the #GtkTreeIter-struct to test for children the number of children of @iter a #GtkTreeModel the #GtkTreeIter-struct, or %NULL %TRUE, if @parent has an @n-th child a #GtkTreeModel the #GtkTreeIter-struct to set to the nth child the #GtkTreeIter-struct to get the child from, or %NULL. the index of the desired child %TRUE, if @iter is set to the parent of @child a #GtkTreeModel the new #GtkTreeIter-struct to set to the parent the #GtkTreeIter-struct a #GtkTreeModel the #GtkTreeIter-struct a #GtkTreeModel the #GtkTreeIter-struct The #GtkTreeModelSort is a model which implements the #GtkTreeSortable 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 #GtkTreeModelSort is not guaranteed to be stable. The use of this is best demonstrated through an example. In the following sample code we create two #GtkTreeView widgets each with a view of the same data. As the model is wrapped here by a #GtkTreeModelSort, 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 #GtkTreeModelSort |[<!-- language="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 #GtkTreeSelection #GtkTreeSelection::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 |[<!-- language="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); } ]| Creates a new #GtkTreeModelSort, with @child_model as the child model. A new #GtkTreeModelSort. A #GtkTreeModel This function should almost never be called. It clears the @tree_model_sort of any cached iterators that haven’t been reffed with gtk_tree_model_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. A #GtkTreeModelSort Sets @sort_iter to point to the row in @tree_model_sort 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. %TRUE, if @sort_iter was set, i.e. if @sort_iter is a valid iterator pointer to a visible row in the child model. A #GtkTreeModelSort An uninitialized #GtkTreeIter. A valid #GtkTreeIter pointing to a row on the child model Converts @child_path to a path relative to @tree_model_sort. 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 %NULL is returned. A newly allocated #GtkTreePath, or %NULL A #GtkTreeModelSort A #GtkTreePath to convert Sets @child_iter to point to the row pointed to by @sorted_iter. A #GtkTreeModelSort An uninitialized #GtkTreeIter A valid #GtkTreeIter pointing to a row on @tree_model_sort. Converts @sorted_path to a path on the child model of @tree_model_sort. That is, @sorted_path points to a location in @tree_model_sort. 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, %NULL is returned. A newly allocated #GtkTreePath, or %NULL A #GtkTreeModelSort A #GtkTreePath to convert Returns the model the #GtkTreeModelSort is sorting. the "child model" being sorted a #GtkTreeModelSort > This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this #GtkTreeModelSort. %TRUE if the iter is valid, %FALSE if the iter is invalid. A #GtkTreeModelSort. A #GtkTreeIter. 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 #GtkTreeModelSort is in “unsorted” state. A #GtkTreeModelSort Creates a new #GtkTreePath-struct. This refers to a row. A newly created #GtkTreePath-struct. Creates a new #GtkTreePath-struct. The string representation of this path is “0”. A new #GtkTreePath-struct Creates a new path with @first_index and @varargs as indices. A newly created #GtkTreePath-struct first integer list of integers terminated by -1 Creates a new path with the given @indices array of @length. A newly created #GtkTreePath-struct array of indices length of @indices array Creates a new #GtkTreePath-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, %NULL is returned. A newly-created #GtkTreePath-struct, or %NULL The string representation of a path Appends a new index to a path. As a result, the depth of the path is increased. a #GtkTreePath-struct the index Compares two paths. If @a appears before @b in a tree, then -1 is returned. If @b appears before @a, then 1 is returned. If the two nodes are equal, then 0 is returned. the relative positions of @a and @b a #GtkTreePath-struct a #GtkTreePath-struct to compare with Creates a new #GtkTreePath-struct as a copy of @path. a new #GtkTreePath-struct a #GtkTreePath-struct Moves @path to point to the first child of the current path. a #GtkTreePath-struct Frees @path. If @path is %NULL, it simply returns. a #GtkTreePath-struct Returns the current depth of @path. The depth of @path a #GtkTreePath-struct Returns the current indices of @path. 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 gtk_tree_path_get_depth(). The current indices, or %NULL a #GtkTreePath-struct Returns the current indices of @path. 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. The current indices, or %NULL a #GtkTreePath-struct return location for number of elements returned in the integer array, or %NULL Returns %TRUE if @descendant is a descendant of @path. %TRUE if @descendant is contained inside @path a #GtkTreePath-struct another #GtkTreePath-struct Returns %TRUE if @path is a descendant of @ancestor. %TRUE if @ancestor contains @path somewhere below it a #GtkTreePath-struct another #GtkTreePath-struct Moves the @path to point to the next node at the current depth. a #GtkTreePath-struct Prepends a new index to a path. As a result, the depth of the path is increased. a #GtkTreePath-struct the index Moves the @path to point to the previous node at the current depth, if it exists. %TRUE if @path has a previous node, and the move was made a #GtkTreePath-struct 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. A newly-allocated string. Must be freed with g_free(). A #GtkTreePath-struct Moves the @path to point to its parent node, if it has a parent. %TRUE if @path has a parent, and the move was made a #GtkTreePath-struct A GtkTreeRowReference tracks model changes so that it always refers to the same row (a #GtkTreePath refers to a position, not a fixed row). Create a new GtkTreeRowReference with gtk_tree_row_reference_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 %NULL is returned. a newly allocated #GtkTreeRowReference, or %NULL a #GtkTreeModel a valid #GtkTreePath-struct to monitor 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 %NULL is returned. However, unlike references created with gtk_tree_row_reference_new(), it does not listen to the model for changes. The creator of the row reference must do this explicitly using gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), gtk_tree_row_reference_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 #GtkTreeView 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. a newly allocated #GtkTreeRowReference, or %NULL a proxy #GObject a #GtkTreeModel a valid #GtkTreePath-struct to monitor Copies a #GtkTreeRowReference. a copy of @reference a #GtkTreeRowReference Free’s @reference. @reference may be %NULL a #GtkTreeRowReference, or %NULL Returns the model that the row reference is monitoring. the model a #GtkTreeRowReference Returns a path that the row reference currently points to, or %NULL if the path pointed to is no longer valid. a current path, or %NULL a #GtkTreeRowReference Returns %TRUE if the @reference is non-%NULL and refers to a current valid path. %TRUE if @reference points to a valid path a #GtkTreeRowReference, or %NULL Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-deleted signal. a #GObject the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-inserted signal. a #GObject the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::rows-reordered signal. a #GObject the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows The #GtkTreeSelection object is a helper object to manage the selection for a #GtkTreeView widget. The #GtkTreeSelection object is automatically created when a new #GtkTreeView widget is created, and cannot exist independently of this widget. The primary reason the #GtkTreeSelection 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 #GtkTreeView widget instead of a separate function. The #GtkTreeSelection object is gotten from a #GtkTreeView by calling gtk_tree_view_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 #GtkTreeSelection::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 #GtkTreeSelection::changed signal when nothing has happened (mostly as a result of programmers calling select_row on an already selected row). Returns the number of rows that have been selected in @tree. The number of rows selected. A #GtkTreeSelection. Gets the selection mode for @selection. See gtk_tree_selection_set_mode(). the current selection mode a #GtkTreeSelection Returns the current selection function. The function. A #GtkTreeSelection. Sets @iter to the currently selected node if @selection is set to #GTK_SELECTION_SINGLE or #GTK_SELECTION_BROWSE. @iter may be NULL if you just want to test if @selection has any selected nodes. @model is filled with the current model as a convenience. This function will not work if you use @selection is #GTK_SELECTION_MULTIPLE. TRUE, if there is a selected node. A #GtkTreeSelection. A pointer to set to the #GtkTreeModel, or NULL. The #GtkTreeIter, or NULL. 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 gtk_tree_row_reference_new(). To free the return value, use: |[<!-- language="C" --> g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ]| A #GList containing a #GtkTreePath for each selected row. A #GtkTreeSelection. A pointer to set to the #GtkTreeModel, or %NULL. Returns the tree view associated with @selection. A #GtkTreeView A #GtkTreeSelection Returns the user data for the selection function. The user data. A #GtkTreeSelection. Returns %TRUE if the row at @iter is currently selected. %TRUE, if @iter is selected A #GtkTreeSelection A valid #GtkTreeIter Returns %TRUE if the row pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned %TRUE if @path is selected. A #GtkTreeSelection. A #GtkTreePath to check selection on. Selects all the nodes. @selection must be set to #GTK_SELECTION_MULTIPLE mode. A #GtkTreeSelection. Selects the specified iterator. A #GtkTreeSelection. The #GtkTreeIter to be selected. Select the row at @path. A #GtkTreeSelection. The #GtkTreePath to be selected. Selects a range of nodes, determined by @start_path and @end_path inclusive. @selection must be set to #GTK_SELECTION_MULTIPLE mode. A #GtkTreeSelection. The initial node of the range. The final node of the range. Calls a function for each selected node. Note that you cannot modify the tree or selection from within this function. As a result, gtk_tree_selection_get_selected_rows() might be more useful. A #GtkTreeSelection. The function to call for each selected node. user data to pass to the function. Sets the selection mode of the @selection. If the previous type was #GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was previously selected. A #GtkTreeSelection. The selection mode 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. A #GtkTreeSelection. The selection function. May be %NULL The selection function’s data. May be %NULL The destroy function for user data. May be %NULL Unselects all the nodes. A #GtkTreeSelection. Unselects the specified iterator. A #GtkTreeSelection. The #GtkTreeIter to be unselected. Unselects the row at @path. A #GtkTreeSelection. The #GtkTreePath to be unselected. Unselects a range of nodes, determined by @start_path and @end_path inclusive. A #GtkTreeSelection. The initial node of the range. The initial node of the range. Selection mode. See gtk_tree_selection_set_mode() for more information on this property. 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. The parent class. A function used by gtk_tree_selection_selected_foreach() to map all selected rows. It will be called on every selected row in the view. The #GtkTreeModel being viewed The #GtkTreePath of a selected row A #GtkTreeIter pointing to a selected row user data A function used by gtk_tree_selection_set_select_function() to filter whether or not a row may be selected. It is called whenever a row's state might change. A return value of %TRUE indicates to @selection that it is okay to change the selection. %TRUE, if the selection state of the row can be toggled A #GtkTreeSelection A #GtkTreeModel being viewed The #GtkTreePath of the row in question %TRUE, if the path is currently selected user data #GtkTreeSortable is an interface to be implemented by tree models which support sorting. The #GtkTreeView uses the methods provided by this interface to sort the model. 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. %TRUE if the sort column is not one of the special sort column ids. A #GtkTreeSortable The sort column id to be filled in The #GtkSortType to be filled in 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. %TRUE, if the model has a default sort function A #GtkTreeSortable Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, 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 @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A #GtkTreeSortable The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a #GtkTreeSortable::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 A #GtkTreeSortable the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A #GtkTreeSortable the sort column id to set the function for The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Emits a #GtkTreeSortable::sort-column-changed signal on @sortable. A #GtkTreeSortable 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. %TRUE if the sort column is not one of the special sort column ids. A #GtkTreeSortable The sort column id to be filled in The #GtkSortType to be filled in 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. %TRUE, if the model has a default sort function A #GtkTreeSortable Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, 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 @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A #GtkTreeSortable The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a #GtkTreeSortable::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 A #GtkTreeSortable the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A #GtkTreeSortable the sort column id to set the function for The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL Emits a #GtkTreeSortable::sort-column-changed signal on @sortable. A #GtkTreeSortable 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. A #GtkTreeSortable %TRUE if the sort column is not one of the special sort column ids. A #GtkTreeSortable The sort column id to be filled in The #GtkSortType to be filled in A #GtkTreeSortable the sort column id to set The sort order of the column A #GtkTreeSortable the sort column id to set the function for The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL A #GtkTreeSortable The comparison function User data to pass to @sort_func, or %NULL Destroy notifier of @user_data, or %NULL %TRUE, if the model has a default sort function A #GtkTreeSortable The #GtkTreeStore object is a list model for use with a #GtkTreeView widget. It implements the #GtkTreeModel interface, and consequentially, can use all of the methods available there. It also implements the #GtkTreeSortable interface so it can be sorted by the view. Finally, it also implements the tree [drag and drop][gtk3-GtkTreeView-drag-and-drop] interfaces. # GtkTreeStore as GtkBuildable The GtkTreeStore implementation of the #GtkBuildable 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: |[ <object class="GtkTreeStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> </object> ]| 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 #GtkTreeStore with three columns, of type #gint, #gchararray, and #GdkPixbuf respectively. a new #GtkTreeStore number of columns in the tree store all #GType types for the columns, from first to last Non vararg creation function. Used primarily by language bindings. a new #GtkTreeStore number of columns in the tree store an array of #GType types for the columns, from first to last Appends a new row to @tree_store. If @parent is non-%NULL, 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 gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the appended row A valid #GtkTreeIter, or %NULL Removes all rows from @tree_store a #GtkTreeStore Creates a new row at @position. If parent is non-%NULL, 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 gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to @parent ’s children. If @parent and @sibling are %NULL, 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 gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL A valid #GtkTreeIter, or %NULL Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to @parent ’s children. If @parent and @sibling are %NULL, 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 gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the new row A valid #GtkTreeIter, or %NULL A valid #GtkTreeIter, or %NULL 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 |[<!-- language="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, gtk_tree_store_insert_with_values() should generally be preferred when inserting rows in a sorted tree store. A #GtkTreeStore An unset #GtkTreeIter to set the new row, or %NULL. A valid #GtkTreeIter, or %NULL position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language bindings. A #GtkTreeStore An unset #GtkTreeIter to set the new row, or %NULL. A valid #GtkTreeIter, or %NULL position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays Returns %TRUE if @iter is an ancestor of @descendant. That is, @iter is the parent (or grandparent or great-grandparent) of @descendant. %TRUE, if @iter is an ancestor of @descendant A #GtkTreeStore A valid #GtkTreeIter A valid #GtkTreeIter Returns the depth of @iter. This will be 0 for anything on the root level, 1 for anything down a level, etc. The depth of @iter A #GtkTreeStore A valid #GtkTreeIter 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 #GtkTreeStore. %TRUE if the iter is valid, %FALSE if the iter is invalid. A #GtkTreeStore. A #GtkTreeIter. Moves @iter in @tree_store 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 %NULL, @iter will be moved to the start of the level. A #GtkTreeStore. A #GtkTreeIter. A #GtkTreeIter. Moves @iter in @tree_store 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 %NULL, @iter will be moved to the end of the level. A #GtkTreeStore. A #GtkTreeIter. A #GtkTreeIter or %NULL. Prepends a new row to @tree_store. If @parent is non-%NULL, 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 gtk_tree_store_set() or gtk_tree_store_set_value(). A #GtkTreeStore An unset #GtkTreeIter to set to the prepended row A valid #GtkTreeIter, or %NULL Removes @iter from @tree_store. After being removed, @iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one. %TRUE if @iter is still valid, %FALSE if not. A #GtkTreeStore A valid #GtkTreeIter Reorders the children of @parent in @tree_store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. A #GtkTreeStore A #GtkTreeIter, or %NULL 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`. 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. A #GtkTreeStore A valid #GtkTreeIter for the row being modified pairs of column number and value, terminated with -1 This function is meant primarily for #GObjects that inherit from #GtkTreeStore, and should only be used when constructing a new #GtkTreeStore. It will not function after a row has been added, or a method on the #GtkTreeModel interface is called. A #GtkTreeStore Number of columns for the tree store An array of #GType types, one for each column See gtk_tree_store_set(); this version takes a va_list for use by language bindings. A #GtkTreeStore A valid #GtkTreeIter for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. a #GtkTreeStore A valid #GtkTreeIter for the row being modified column number to modify new value for the cell A variant of gtk_tree_store_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. A #GtkTreeStore A valid #GtkTreeIter for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in the same level of @tree_store. Note that this function only works with unsorted stores. A #GtkTreeStore. A #GtkTreeIter. Another #GtkTreeIter. Widget that displays any object that implements the #GtkTreeModel 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 GtkTreeView API. These are:  Coordinate systems in GtkTreeView API: - Widget coordinates: Coordinates relative to the widget (usually `widget->window`). - Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to. - Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. 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 gtk_tree_view_convert_widget_to_bin_window_coords() (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords() (and vice versa). # GtkTreeView as GtkBuildable The GtkTreeView implementation of the GtkBuildable interface accepts #GtkTreeViewColumn objects as <child> elements and exposes the internal #GtkTreeSelection in UI definitions. An example of a UI definition fragment with GtkTreeView: |[ <object class="GtkTreeView" id="treeview"> <property name="model">liststore1</property> <child> <object class="GtkTreeViewColumn" id="test-column"> <property name="title">Test</property> <child> <object class="GtkCellRendererText" id="test-renderer"/> <attributes> <attribute name="text">1</attribute> </attributes> </child> </object> </child> <child internal-child="selection"> <object class="GtkTreeSelection" id="selection"> <signal name="changed" handler="on_treeview_selection_changed"/> </object> </child> </object> ]| # CSS nodes |[<!-- language="plain" --> treeview.view ├── header │ ├── <column header> ┊ ┊ │ ╰── <column header> │ ╰── [rubberband] ]| GtkTreeView 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. Creates a new #GtkTreeView widget. A newly created #GtkTreeView widget. Creates a new #GtkTreeView widget with the model initialized to @model. A newly created #GtkTreeView widget. the model. Activates the cell determined by @path and @column. A #GtkTreeView The #GtkTreePath to be activated. The #GtkTreeViewColumn to be activated. Appends @column to the list of columns. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after appending. A #GtkTreeView. The #GtkTreeViewColumn to add. Recursively collapses all visible, expanded nodes in @tree_view. A #GtkTreeView. Collapses a row (hides its child rows, if they exist). %TRUE if the row was collapsed. a #GtkTreeView path to a row in the @tree_view Resizes all columns to their optimal width. Only works after the treeview has been realized. A #GtkTreeView. Converts bin_window coordinates to coordinates for the tree (the full scrollable area of the tree). a #GtkTreeView X coordinate relative to bin_window Y coordinate relative to bin_window return location for tree X coordinate return location for tree Y coordinate Converts bin_window coordinates (see gtk_tree_view_get_bin_window()) to widget relative coordinates. a #GtkTreeView bin_window X coordinate bin_window Y coordinate return location for widget X coordinate return location for widget Y coordinate Converts tree coordinates (coordinates in full scrollable area of the tree) to bin_window coordinates. a #GtkTreeView tree X coordinate tree Y coordinate return location for X coordinate relative to bin_window return location for Y coordinate relative to bin_window Converts tree coordinates (coordinates in full scrollable area of the tree) to widget coordinates. a #GtkTreeView X coordinate relative to the tree Y coordinate relative to the tree return location for widget X coordinate return location for widget Y coordinate Converts widget coordinates to coordinates for the bin_window (see gtk_tree_view_get_bin_window()). a #GtkTreeView X coordinate relative to the widget Y coordinate relative to the widget return location for bin_window X coordinate return location for bin_window Y coordinate Converts widget coordinates to coordinates for the tree (the full scrollable area of the tree). a #GtkTreeView X coordinate relative to the widget Y coordinate relative to the widget return location for tree X coordinate return location for tree Y coordinate Creates a #cairo_surface_t representation of the row at @path. This image is used for a drag icon. a newly-allocated surface of the drag icon. a #GtkTreeView a #GtkTreePath in @tree_view Turns @tree_view into a drop destination for automatic DND. Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag from this widget Turns @tree_view into a drag source for automatic DND. Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView Mask of allowed buttons to start drag the table of targets that the drag will support the number of items in @targets the bitmask of possible actions for a drag from this widget Recursively expands all nodes in the @tree_view. A #GtkTreeView. Opens the row so its children are visible. %TRUE if the row existed and had children a #GtkTreeView path to a row whether to recursively expand, or just expand immediate children Expands the row at @path. This will also expand all parent rows of @path as necessary. A #GtkTreeView. path to a row. Gets the setting set by gtk_tree_view_set_activate_on_single_click(). %TRUE if row-activated will be emitted on a single click a #GtkTreeView 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 %NULL, 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 %NULL, the @x and @width fields will be filled with 0. The returned rectangle is equivalent to the @background_area passed to gtk_cell_renderer_render(). These background areas tile to cover the entire bin window. Contrast with the @cell_area, returned by gtk_tree_view_get_cell_area(), which returns only the cell itself, excluding surrounding borders and the tree expander area. a #GtkTreeView a #GtkTreePath for the row, or %NULL to get only horizontal coordinates a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordiantes rectangle to fill with cell background rect Returns the window that @tree_view renders to. This is used primarily to compare to `event->window` to confirm that the event on @tree_view is on the right window. A #GdkWindow, or %NULL when @tree_view hasn’t been realized yet. A #GtkTreeView 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 %NULL, or points to a path not currently displayed, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, 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 gtk_cell_renderer_render(). This function is only valid if @tree_view is realized. a #GtkTreeView a #GtkTreePath for the row, or %NULL to get only horizontal coordinates a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates rectangle to fill with cell rect Gets the #GtkTreeViewColumn at the given position in the #tree_view. The #GtkTreeViewColumn, or %NULL if the position is outside the range of columns. A #GtkTreeView. The position of the column, counting from 0. Returns a #GList of all the #GtkTreeViewColumn s currently in @tree_view. The returned list must be freed with g_list_free (). A list of #GtkTreeViewColumn s A #GtkTreeView Fills in @path and @focus_column with the current path and focus column. If the cursor isn’t currently set, then *@path will be %NULL. If no column currently has focus, then *@focus_column will be %NULL. The returned #GtkTreePath must be freed with gtk_tree_path_free() when you are done with it. A #GtkTreeView A pointer to be filled with the current cursor path, or %NULL A pointer to be filled with the current focus column, or %NULL 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 @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. whether there is a row at the given position, %TRUE if this is indeed the case. a #GtkTreeView the position to determine the destination row for the position to determine the destination row for Return location for the path of the highlighted row, or %NULL. Return location for the drop position, or %NULL Gets information about the row that is highlighted for feedback. a #GtkTreeView Return location for the path of the highlighted row, or %NULL. Return location for the drop position, or %NULL Returns whether or not the tree allows to start interactive searching by typing in text. whether or not to let the user search interactively A #GtkTreeView Returns whether or not tree lines are drawn in @tree_view. %TRUE if tree lines are drawn in @tree_view, %FALSE otherwise. a #GtkTreeView. Returns the column that is the current expander column. This column has the expander arrow drawn next to it. The expander column. A #GtkTreeView Returns whether fixed height mode is turned on for @tree_view. %TRUE if @tree_view is in fixed height mode a #GtkTreeView Returns which grid lines are enabled in @tree_view. a #GtkTreeViewGridLines value indicating which grid lines are enabled. a #GtkTreeView Gets the #GtkAdjustment currently being used for the horizontal aspect. Use gtk_scrollable_get_hadjustment() A #GtkAdjustment object, or %NULL if none is currently being used. A #GtkTreeView Returns whether all header columns are clickable. %TRUE if all header columns are clickable, otherwise %FALSE A #GtkTreeView. Returns %TRUE if the headers on the @tree_view are visible. Whether the headers are visible or not. A #GtkTreeView. Returns whether hover expansion mode is turned on for @tree_view. %TRUE if @tree_view is in hover expansion mode a #GtkTreeView Returns whether hover selection mode is turned on for @tree_view. %TRUE if @tree_view is in hover selection mode a #GtkTreeView Returns the amount, in pixels, of extra indentation for child levels in @tree_view. the amount of extra indentation for child levels in @tree_view. A return value of 0 means that this feature is disabled. a #GtkTreeView. Returns the model the #GtkTreeView is based on. Returns %NULL if the model is unset. A #GtkTreeModel, or %NULL if none is currently being used. a #GtkTreeView Queries the number of columns in the given @tree_view. The number of columns in the @tree_view a #GtkTreeView Finds the path at the point (@x, @y), relative to bin_window coordinates (please see gtk_tree_view_get_bin_window()). That is, @x and @y are relative to an events coordinates. @x and @y must come from an event on the @tree_view only where `event->window == gtk_tree_view_get_bin_window ()`. It is primarily for things like popup menus. If @path is non-%NULL, then it will be filled with the #GtkTreePath at that point. This path should be freed with gtk_tree_path_free(). If @column is non-%NULL, 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 gtk_cell_renderer_render()). This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). %TRUE if a row exists at that coordinate. A #GtkTreeView. The x position to be identified (relative to bin_window). The y position to be identified (relative to bin_window). A pointer to a #GtkTreePath pointer to be filled in, or %NULL A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL A pointer where the X coordinate relative to the cell can be placed, or %NULL A pointer where the Y coordinate relative to the cell can be placed, or %NULL Retrieves whether the user can reorder the tree via drag-and-drop. See gtk_tree_view_set_reorderable(). %TRUE if the tree can be reordered. a #GtkTreeView Returns the current row separator function. the current row separator function. a #GtkTreeView Returns whether rubber banding is turned on for @tree_view. If the selection mode is #GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. %TRUE if rubber banding in @tree_view is enabled. a #GtkTreeView Gets the setting set by gtk_tree_view_set_rules_hint(). %TRUE if the hint is set a #GtkTreeView Gets the column searched on by the interactive search code. the column the interactive search code searches in. A #GtkTreeView Returns the #GtkEntry which is currently in use as interactive search entry for @tree_view. In case the built-in entry is being used, %NULL will be returned. the entry currently in use as search entry. A #GtkTreeView Returns the compare function currently in use. the currently used compare function for the search code. A #GtkTreeView Returns the positioning function currently in use. the currently used function for positioning the search dialog. A #GtkTreeView Gets the #GtkTreeSelection associated with @tree_view. A #GtkTreeSelection object. A #GtkTreeView. Returns whether or not expanders are drawn in @tree_view. %TRUE if expanders are drawn in @tree_view, %FALSE otherwise. a #GtkTreeView. Returns the column of @tree_view’s model which is being used for displaying tooltips on @tree_view’s rows. the index of the tooltip column that is currently being used, or -1 if this is disabled. a #GtkTreeView This function is supposed to be used in a #GtkWidget::query-tooltip signal handler for #GtkTreeView. 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 @tree_view’s bin_window if @keyboard_tooltip is %FALSE. whether or not the given tooltip context points to a row. a #GtkTreeView the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a #GtkTreeModel or %NULL a pointer to receive a #GtkTreePath or %NULL a pointer to receive a #GtkTreeIter or %NULL Gets the #GtkAdjustment currently being used for the vertical aspect. Use gtk_scrollable_get_vadjustment() A #GtkAdjustment object, or %NULL if none is currently being used. A #GtkTreeView 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 gtk_tree_path_free() after use. %TRUE, if valid paths were placed in @start_path and @end_path. A #GtkTreeView Return location for start of region, or %NULL. Return location for end of region, or %NULL. Fills @visible_rect with the currently-visible region of the buffer, in tree coordinates. Convert to bin_window coordinates with gtk_tree_view_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. a #GtkTreeView rectangle to fill This inserts the @column into the @tree_view at @position. If @position is -1, then the column is inserted at the end. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after insertion. A #GtkTreeView. The #GtkTreeViewColumn to be inserted. The position to insert @column in. Creates a new #GtkTreeViewColumn and inserts it into the @tree_view 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 @tree_view has “fixed_height” mode enabled, then the new column will have its sizing property set to be GTK_TREE_VIEW_COLUMN_FIXED. The number of columns in @tree_view after insertion. A #GtkTreeView The position to insert the new column in The title to set the header to The #GtkCellRenderer A %NULL-terminated list of attributes Convenience function that inserts a new column into the #GtkTreeView with the given cell renderer and a #GtkTreeCellDataFunc to set cell renderer attributes (normally using data from the model). See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). If @tree_view has “fixed_height” mode enabled, then the new column will have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. number of columns in the tree view post-insert a #GtkTreeView Position to insert, -1 for append column title cell renderer for column function to set attributes of cell renderer data for @func destroy notifier for @data Determine whether the point (@x, @y) in @tree_view 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 @tree_view where `event->window == gtk_tree_view_get_bin_window ()`. For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). The @path, @column, @cell_x and @cell_y arguments will be filled in likewise as for gtk_tree_view_get_path_at_pos(). Please see gtk_tree_view_get_path_at_pos() for more information. %TRUE if the area at the given coordinates is blank, %FALSE otherwise. A #GtkTreeView The x position to be identified (relative to bin_window) The y position to be identified (relative to bin_window) A pointer to a #GtkTreePath pointer to be filled in, or %NULL A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL A pointer where the X coordinate relative to the cell can be placed, or %NULL A pointer where the Y coordinate relative to the cell can be placed, or %NULL Returns whether a rubber banding operation is currently being done in @tree_view. %TRUE if a rubber banding operation is currently being done in @tree_view. a #GtkTreeView Calls @func on all expanded rows. A #GtkTreeView A function to be called User data to be passed to the function. Moves @column to be after to @base_column. If @base_column is %NULL, then @column is placed in the first position. A #GtkTreeView The #GtkTreeViewColumn to be moved. The #GtkTreeViewColumn to be moved relative to, or %NULL. Removes @column from @tree_view. The number of columns in @tree_view after removing. A #GtkTreeView. The #GtkTreeViewColumn to remove. Activates the cell determined by @path and @column. A #GtkTreeView The #GtkTreePath to be activated. The #GtkTreeViewColumn to be activated. Returns %TRUE if the node pointed to by @path is expanded in @tree_view. %TRUE if #path is expanded. A #GtkTreeView. A #GtkTreePath to test expansion state. Moves the alignments of @tree_view to the position specified by @column and @path. If @column is %NULL, then no horizontal scrolling occurs. Likewise, if @path is %NULL no vertical scrolling occurs. At a minimum, one of @column or @path need to be non-%NULL. @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 @tree_view is realized, the centered path will be modified to reflect this change. A #GtkTreeView. The path of the row to move to, or %NULL. The #GtkTreeViewColumn to move horizontally to, or %NULL. whether to use alignment arguments, or %FALSE. The vertical alignment of the row specified by @path. The horizontal alignment of the column specified by @column. 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 @tree_view must be realized before this function is called. If it isn't, you probably want to be using gtk_tree_view_scroll_to_cell(). If either @tree_x or @tree_y are -1, then that direction isn’t scrolled. a #GtkTreeView X coordinate of new top-left pixel of visible area, or -1 Y coordinate of new top-left pixel of visible area, or -1 Cause the #GtkTreeView::row-activated signal to be emitted on a single click instead of a double click. a #GtkTreeView %TRUE to emit row-activated on a single click 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 @tree_view, the #GtkTreeViewColumn being dragged, the two #GtkTreeViewColumn s determining the drop spot, and @user_data. If either of the #GtkTreeViewColumn arguments for the drop spot are %NULL, then they indicate an edge. If @func is set to be %NULL, then @tree_view reverts to the default behavior of allowing all columns to be dropped everywhere. A #GtkTreeView. A function to determine which columns are reorderable, or %NULL. User data to be passed to @func, or %NULL Destroy notifier for @user_data, or %NULL 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 %NULL, 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 @gtk_widget_grab_focus (@tree_view) 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. A #GtkTreeView A #GtkTreePath A #GtkTreeViewColumn, or %NULL %TRUE if the specified cell should start being edited. 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 %NULL, then focus is given to the column specified by it. If @focus_column and @focus_cell are not %NULL, 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 @gtk_widget_grab_focus (@tree_view) 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. A #GtkTreeView A #GtkTreePath A #GtkTreeViewColumn, or %NULL A #GtkCellRenderer, or %NULL %TRUE if the specified cell should start being edited. This function should almost never be used. It is meant for private use by ATK for determining the number of visible children that are removed when the user collapses a row, or a row is deleted. Accessibility does not need the function anymore. A #GtkTreeView Function to be called when a view row is destroyed, or %NULL User data to be passed to @func, or %NULL Destroy notifier for @data, or %NULL Sets the row that is highlighted for feedback. If @path is %NULL, an existing highlight is removed. a #GtkTreeView The path of the row to highlight, or %NULL Specifies whether to drop before, after or into the row 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. A #GtkTreeView %TRUE, if the user can search interactively Sets whether to draw lines interconnecting the expanders in @tree_view. This does not have any visible effects for lists. a #GtkTreeView %TRUE to enable tree line drawing, %FALSE otherwise. Sets the column to draw the expander arrow at. It must be in @tree_view. If @column is %NULL, 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. A #GtkTreeView %NULL, or the column to draw the expander arrow at. Enables or disables the fixed height mode of @tree_view. Fixed height mode speeds up #GtkTreeView 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 %GTK_TREE_VIEW_COLUMN_FIXED. a #GtkTreeView %TRUE to enable fixed height mode Sets which grid lines to draw in @tree_view. a #GtkTreeView a #GtkTreeViewGridLines value indicating which grid lines to enable. Sets the #GtkAdjustment for the current horizontal aspect. Use gtk_scrollable_set_hadjustment() A #GtkTreeView The #GtkAdjustment to set, or %NULL Allow the column title buttons to be clicked. A #GtkTreeView. %TRUE if the columns are clickable. Sets the visibility state of the headers. A #GtkTreeView. %TRUE if the headers are visible Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. a #GtkTreeView %TRUE to enable hover selection mode 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 %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. a #GtkTreeView %TRUE to enable hover selection mode Sets the amount of extra indentation for child levels to use in @tree_view 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. a #GtkTreeView the amount, in pixels, of extra indentation in @tree_view. Sets the model for a #GtkTreeView. If the @tree_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. A #GtkTreeView. The model. This function is a convenience function to allow you to reorder models that support the #GtkTreeDragSourceIface and the #GtkTreeDragDestIface. Both #GtkTreeStore and #GtkListStore 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 #GtkTreeModel::row-inserted and #GtkTreeModel::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. A #GtkTreeView. %TRUE, if the tree can be reordered. 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 %NULL, no separators are drawn. This is the default value. a #GtkTreeView a #GtkTreeViewRowSeparatorFunc user data to pass to @func, or %NULL destroy notifier for @data, or %NULL Enables or disables rubber banding in @tree_view. If the selection mode is #GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. a #GtkTreeView %TRUE to enable rubber banding Sets a hint for the theme to draw even/odd rows in the @tree_view with different colors, also known as "zebra striping". This function tells the GTK+ theme that the user interface for your application requires users to read across tree rows and associate cells with one another. Do not use it just because you prefer the appearance of the ruled tree; that’s a question for the theme. Some themes will draw tree rows in alternating colors even when rules are turned off, and users who prefer that appearance all the time can choose those themes. You should call this function only as a semantic hint to the theme engine that your tree makes alternating colors useful from a functional standpoint (since it has lots of columns, generally). a #GtkTreeView %TRUE if the tree requires reading across rows 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. A #GtkTreeView the column of the model to search in, or -1 to disable searching Sets the entry which the interactive search code will use for this @tree_view. This is useful when you want to provide a search entry in our interface at all time at a fixed position. Passing %NULL for @entry will make the interactive search code use the built-in popup entry again. A #GtkTreeView the entry the interactive search code of @tree_view should use or %NULL Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 0 for equality #GtkTreeViewSearchEqualFunc returns %FALSE on matches. A #GtkTreeView the compare function to use during the search user data to pass to @search_equal_func, or %NULL Destroy notifier for @search_user_data, or %NULL Sets the function to use when positioning the search dialog. A #GtkTreeView the function to use to position the search dialog, or %NULL to use the default search position function user data to pass to @func, or %NULL Destroy notifier for @data, or %NULL Sets whether to draw and enable expanders and indent child rows in @tree_view. 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 gtk_tree_view_set_level_indentation(). This does not have any visible effects for lists. a #GtkTreeView %TRUE to enable expander drawing, %FALSE otherwise. Sets the tip area of @tooltip to the area @path, @column and @cell have in common. For example if @path is %NULL and @column is set, the tip area will be set to the full area covered by @column. See also gtk_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 gtk_tree_view_set_tooltip_column() for a simpler alternative. a #GtkTreeView a #GtkTooltip a #GtkTreePath or %NULL a #GtkTreeViewColumn or %NULL a #GtkCellRenderer or %NULL If you only plan to have simple (text-only) tooltips on full rows, you can use this function to have #GtkTreeView handle these automatically for you. @column should be set to the column in @tree_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, #GtkWidget:has-tooltip will be set to %TRUE and @tree_view will connect a #GtkWidget::query-tooltip signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. a #GtkTreeView an integer, which is a valid column number for @tree_view’s model Sets the tip area of @tooltip to be the area covered by the row at @path. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). a #GtkTreeView a #GtkTooltip a #GtkTreePath Sets the #GtkAdjustment for the current vertical aspect. Use gtk_scrollable_set_vadjustment() A #GtkTreeView The #GtkAdjustment to set, or %NULL Undoes the effect of gtk_tree_view_enable_model_drag_dest(). Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView Undoes the effect of gtk_tree_view_enable_model_drag_source(). Calling this method sets #GtkTreeView:reorderable to %FALSE. a #GtkTreeView The activate-on-single-click property specifies whether the "row-activated" signal will be emitted after a single click. Setting the ::fixed-height-mode property to %TRUE speeds up #GtkTreeView by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see gtk_tree_view_set_fixed_height_mode() for more information on this option. 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 #GtkComboBox or #GtkEntryCompletion. 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 %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. This mode is primarily intended for treeviews in popups, e.g. in #GtkComboBox or #GtkEntryCompletion. Extra indentation for each level. Sets a hint to the theme to draw rows in alternating colors. The theme is responsible for drawing rows using zebra striping %TRUE if the view has expanders. The number of columns of the treeview has changed. The position of the cursor (focused cell) has changed. The #GtkTreeView::move-cursor signal is a [keybinding signal][GtkBindingSignal] 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 gtk_tree_view_set_cursor() and gtk_tree_view_set_cursor_on_cell() when moving horizontally #GtkTreeView::move-cursor does not reset the current selection. %TRUE if @step is supported, %FALSE otherwise. the granularity of the move, as a #GtkMovementStep. %GTK_MOVEMENT_LOGICAL_POSITIONS, %GTK_MOVEMENT_VISUAL_POSITIONS, %GTK_MOVEMENT_DISPLAY_LINES, %GTK_MOVEMENT_PAGES and %GTK_MOVEMENT_BUFFER_ENDS are supported. %GTK_MOVEMENT_LOGICAL_POSITIONS and %GTK_MOVEMENT_VISUAL_POSITIONS are treated identically. the direction to move: +1 to move forwards; -1 to move backwards. The resulting movement is undefined for all other values. The "row-activated" signal is emitted when the method gtk_tree_view_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 #GtkTreeSelection. the #GtkTreePath for the activated row the #GtkTreeViewColumn in which the activation occurred The given row has been collapsed (child nodes are hidden). the tree iter of the collapsed row a tree path that points to the row The given row has been expanded (child nodes are shown). the tree iter of the expanded row a tree path that points to the 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. %FALSE to allow collapsing, %TRUE to reject the tree iter of the row to collapse a tree path that points to the 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. %FALSE to allow expansion, %TRUE to reject the tree iter of the row to expand a tree path that points to the row A #GtkTreeView The #GtkTreePath to be activated. The #GtkTreeViewColumn to be activated. The GtkTreeViewColumn object represents a visible column in a #GtkTreeView 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. Creates a new #GtkTreeViewColumn. A newly created #GtkTreeViewColumn. Creates a new #GtkTreeViewColumn using @area to render its cells. A newly created #GtkTreeViewColumn. the #GtkCellArea that the newly created column should use to layout cells. Creates a new #GtkTreeViewColumn with a number of default values. This is equivalent to calling gtk_tree_view_column_set_title(), gtk_tree_view_column_pack_start(), and gtk_tree_view_column_set_attributes() on the newly created #GtkTreeViewColumn. Here’s a simple example: |[<!-- language="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); } ]| A newly created #GtkTreeViewColumn. The title to set the header to The #GtkCellRenderer A %NULL-terminated list of attributes Emits the “clicked” signal on the column. This function will only work if @tree_column is clickable. a #GtkTreeViewColumn Adds an attribute mapping to the list in @tree_column. 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 #GtkCellRendererText get its values from column 2. A #GtkTreeViewColumn. the #GtkCellRenderer to set attributes on An attribute on the renderer The column position on the model to get the attribute from. 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. %TRUE if @cell belongs to @tree_column. a #GtkTreeViewColumn a #GtkCellRenderer return location for the horizontal position of @cell within @tree_column, may be %NULL return location for the width of @cell, may be %NULL Obtains the width and height needed to render the column. This is used primarily by the #GtkTreeView. A #GtkTreeViewColumn. The area a cell in the column will be allocated, or %NULL location to return x offset of a cell relative to @cell_area, or %NULL location to return y offset of a cell relative to @cell_area, or %NULL location to return width needed to render a cell, or %NULL location to return height needed to render a cell, or %NULL Returns %TRUE if any of the cells packed into the @tree_column are visible. For this to be meaningful, you must first initialize the cells with gtk_tree_view_column_cell_set_cell_data() %TRUE, if any of the cells packed into the @tree_column are currently visible A #GtkTreeViewColumn Sets the cell renderer based on the @tree_model and @iter. That is, for every attribute mapping in @tree_column, 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 #GtkTreeView. A #GtkTreeViewColumn. The #GtkTreeModel to to get the cell renderers attributes from. The #GtkTreeIter to to get the cell renderer’s attributes from. %TRUE, if the row has children %TRUE, if the row has visible children Unsets all the mappings on all renderers on the @tree_column. A #GtkTreeViewColumn Clears all existing attributes previously set with gtk_tree_view_column_set_attributes(). a #GtkTreeViewColumn a #GtkCellRenderer to clear the attribute mapping on. Emits the “clicked” signal on the column. This function will only work if @tree_column is clickable. a #GtkTreeViewColumn Sets the current keyboard focus to be at @cell, if the column contains 2 or more editable and activatable cells. A #GtkTreeViewColumn A #GtkCellRenderer Returns the current x alignment of @tree_column. This value can range between 0.0 and 1.0. The current alignent of @tree_column. A #GtkTreeViewColumn. Returns the button used in the treeview column header The button for the column header. A #GtkTreeViewColumn Returns %TRUE if the user can click on the header for the column. %TRUE if user can click the column header. a #GtkTreeViewColumn Returns %TRUE if the column expands to fill available space. %TRUE if the column expands to fill available space. A #GtkTreeViewColumn. Gets the fixed width of the column. This may not be the actual displayed width of the column; for that, use gtk_tree_view_column_get_width(). The fixed width of the column. A #GtkTreeViewColumn. Returns the maximum width in pixels of the @tree_column, or -1 if no maximum width is set. The maximum width of the @tree_column. A #GtkTreeViewColumn. Returns the minimum width in pixels of the @tree_column, or -1 if no minimum width is set. The minimum width of the @tree_column. A #GtkTreeViewColumn. Returns %TRUE if the @tree_column can be reordered by the user. %TRUE if the @tree_column can be reordered by the user. A #GtkTreeViewColumn Returns %TRUE if the @tree_column can be resized by the end user. %TRUE, if the @tree_column can be resized. A #GtkTreeViewColumn Returns the current type of @tree_column. The type of @tree_column. A #GtkTreeViewColumn. Gets the logical @sort_column_id that the model sorts on when this column is selected for sorting. See gtk_tree_view_column_set_sort_column_id(). the current @sort_column_id for this column, or -1 if this column can’t be used for sorting. a #GtkTreeViewColumn Gets the value set by gtk_tree_view_column_set_sort_indicator(). whether the sort indicator arrow is displayed a #GtkTreeViewColumn Gets the value set by gtk_tree_view_column_set_sort_order(). the sort order the sort indicator is indicating a #GtkTreeViewColumn Returns the spacing of @tree_column. the spacing of @tree_column. A #GtkTreeViewColumn. Returns the title of the widget. the title of the column. This string should not be modified or freed. A #GtkTreeViewColumn. Returns the #GtkTreeView wherein @tree_column has been inserted. If @column is currently not inserted in any tree view, %NULL is returned. The tree view wherein @column has been inserted if any, %NULL otherwise. A #GtkTreeViewColumn Returns %TRUE if @tree_column is visible. whether the column is visible or not. If it is visible, then the tree will show the column. A #GtkTreeViewColumn. Returns the #GtkWidget in the button on the column header. If a custom widget has not been set then %NULL is returned. The #GtkWidget in the column header, or %NULL A #GtkTreeViewColumn. Returns the current size of @tree_column in pixels. The current width of @tree_column. A #GtkTreeViewColumn. Returns the current X offset of @tree_column in pixels. The current X offset of @tree_column. A #GtkTreeViewColumn. 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. A #GtkTreeViewColumn. The #GtkCellRenderer. %TRUE if @cell is to be given extra space allocated to @tree_column. 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. A #GtkTreeViewColumn. The #GtkCellRenderer. %TRUE if @cell is to be given extra space allocated to @tree_column. Flags the column, and the cell renderers added to this column, to have their sizes renegotiated. A #GtkTreeViewColumn 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. A #GtkTreeViewColumn. The alignment, which is between [0.0 and 1.0] inclusive. Sets the attributes in the list as the attributes of @tree_column. The attributes should be in attribute/column order, as in gtk_tree_view_column_add_attribute(). All existing attributes are removed, and replaced with the new attributes. A #GtkTreeViewColumn the #GtkCellRenderer we’re setting the attributes of A %NULL-terminated list of attributes 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 @tree_column's cell renderer as appropriate. @func may be %NULL to remove an older one. A #GtkTreeViewColumn A #GtkCellRenderer The #GtkTreeCellDataFunc to use. The user data for @func. The destroy notification for @func_data 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. A #GtkTreeViewColumn. %TRUE if the header is active. 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. A #GtkTreeViewColumn. %TRUE if the column should expand to fill available space. If @fixed_width is not -1, sets the fixed width of @tree_column; 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 #GTK_TREE_VIEW_COLUMN_GROW_ONLY or #GTK_TREE_VIEW_COLUMN_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. A #GtkTreeViewColumn. The new fixed width, in pixels, or -1. Sets the maximum width of the @tree_column. 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. A #GtkTreeViewColumn. The maximum width of the column in pixels, or -1. Sets the minimum width of the @tree_column. If @min_width is -1, then the minimum width is unset. A #GtkTreeViewColumn. The minimum width of the column in pixels, or -1. If @reorderable is %TRUE, then the column can be reordered by the end user dragging the header. A #GtkTreeViewColumn %TRUE, if the column can be reordered. 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 #GTK_TREE_VIEW_COLUMN_AUTOSIZE, then the sizing mode is changed to #GTK_TREE_VIEW_COLUMN_GROW_ONLY. A #GtkTreeViewColumn %TRUE, if the column can be resized Sets the growth behavior of @tree_column to @type. A #GtkTreeViewColumn. The #GtkTreeViewColumnSizing. 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. a #GtkTreeViewColumn The @sort_column_id of the model to sort on. Call this function with a @setting of %TRUE to display an arrow in the header button indicating the column is sorted. Call gtk_tree_view_column_set_sort_order() to change the direction of the arrow. a #GtkTreeViewColumn %TRUE to display an indicator that the column is sorted Changes the appearance of the sort indicator. This does not actually sort the model. Use gtk_tree_view_column_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 gtk_tree_sortable_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 gtk_tree_view_column_set_sort_indicator(). a #GtkTreeViewColumn sort order that the sort indicator should indicate Sets the spacing field of @tree_column, which is the number of pixels to place between cell renderers packed into it. A #GtkTreeViewColumn. distance between cell renderers in pixels. Sets the title of the @tree_column. If a custom widget has been set, then this value is ignored. A #GtkTreeViewColumn. The title of the @tree_column. Sets the visibility of @tree_column. A #GtkTreeViewColumn. %TRUE if the @tree_column is visible. Sets the widget in the header to be @widget. If widget is %NULL, then the header button is set with a #GtkLabel set to the title of @tree_column. A #GtkTreeViewColumn. A child #GtkWidget, or %NULL. The #GtkCellArea used to layout cell renderers for this column. If no area is specified when creating the tree view column with gtk_tree_view_column_new_with_area() a horizontally oriented #GtkCellAreaBox will be used. 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. a #GtkTreeViewColumn Function type for determining whether @column can be dropped in a particular spot (as determined by @prev_column and @next_column). In left to right locales, @prev_column is on the left of the potential drop spot, and @next_column is on the right. In right to left mode, this is reversed. This function should return %TRUE if the spot is a valid drop spot. Please note that returning %TRUE does not actually indicate that the column drop was made, but is meant only to indicate a possible drop spot to the user. %TRUE, if @column can be dropped in this spot A #GtkTreeView The #GtkTreeViewColumn being dragged A #GtkTreeViewColumn on one side of @column A #GtkTreeViewColumn on the other side of @column user data The sizing method the column uses to determine its width. Please note that @GTK_TREE_VIEW_COLUMN_AUTOSIZE are inefficient for large views, and can make columns appear choppy. Columns only get bigger in reaction to changes in the model Columns resize to be the optimal size everytime the model changes. Columns are a fixed numbers of pixels wide. An enum for determining where a dropped row goes. dropped row is inserted before dropped row is inserted after dropped row becomes a child or is inserted before dropped row becomes a child or is inserted after Used to indicate which grid lines to draw in a tree view. No grid lines. Horizontal grid lines. Vertical grid lines. Horizontal and vertical grid lines. Function used for gtk_tree_view_map_expanded_rows(). A #GtkTreeView The path that’s expanded user data Function type for determining whether the row pointed to by @iter should be rendered as a separator. A common way to implement this is to have a boolean column in the model, whose values the #GtkTreeViewRowSeparatorFunc returns. %TRUE if the row is a separator the #GtkTreeModel a #GtkTreeIter pointing at a row in @model user data A function used for checking whether a row in @model matches a search key string entered by the user. Note the return value is reversed from what you would normally expect, though it has some similarity to strcmp() returning 0 for equal strings. %FALSE if the row matches, %TRUE otherwise. the #GtkTreeModel being searched the search column set by gtk_tree_view_set_search_column() the key string to compare with a #GtkTreeIter pointing the row of @model that should be compared with @key. user data from gtk_tree_view_set_search_equal_func() > GtkUIManager is deprecated since GTK+ 3.10. To construct user interfaces > from XML definitions, you should use #GtkBuilder, #GMenuModel, et al. To > work with actions, use #GAction, #GtkActionable et al. These newer classes > support richer functionality and integration with various desktop shells. > It should be possible to migrate most/all functionality from GtkUIManager. A #GtkUIManager constructs a user interface (menus and toolbars) from one or more UI definitions, which reference actions from one or more action groups. # UI Definitions # {#XML-UI} The UI definitions are specified in an XML format which can be roughly described by the following DTD. > Do not confuse the GtkUIManager UI Definitions described here with > the similarly named [GtkBuilder UI Definitions][BUILDER-UI]. |[ <!ELEMENT ui (menubar|toolbar|popup|accelerator)* > <!ELEMENT menubar (menuitem|separator|placeholder|menu)* > <!ELEMENT menu (menuitem|separator|placeholder|menu)* > <!ELEMENT popup (menuitem|separator|placeholder|menu)* > <!ELEMENT toolbar (toolitem|separator|placeholder)* > <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* > <!ELEMENT menuitem EMPTY > <!ELEMENT toolitem (menu?) > <!ELEMENT separator EMPTY > <!ELEMENT accelerator EMPTY > <!ATTLIST menubar name #IMPLIED action #IMPLIED > <!ATTLIST toolbar name #IMPLIED action #IMPLIED > <!ATTLIST popup name #IMPLIED action #IMPLIED accelerators (true|false) #IMPLIED > <!ATTLIST placeholder name #IMPLIED action #IMPLIED > <!ATTLIST separator name #IMPLIED action #IMPLIED expand (true|false) #IMPLIED > <!ATTLIST menu name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED > <!ATTLIST menuitem name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED always-show-image (true|false) #IMPLIED > <!ATTLIST toolitem name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED > <!ATTLIST accelerator name #IMPLIED action #REQUIRED > ]| There are some additional restrictions beyond those specified in the DTD, e.g. every toolitem must have a toolbar in its anchestry and every menuitem must have a menubar or popup in its anchestry. Since a #GMarkupParser is used to parse the UI description, it must not only be valid XML, but valid markup. If a name is not specified, it defaults to the action. If an action is not specified either, the element name is used. The name and action attributes must not contain “/” characters after parsing (since that would mess up path lookup) and must be usable as XML attributes when enclosed in doublequotes, thus they must not “"” characters or references to the &quot; entity. # A UI definition # |[ <ui> <menubar> <menu name="FileMenu" action="FileMenuAction"> <menuitem name="New" action="New2Action" /> <placeholder name="FileMenuAdditions" /> </menu> <menu name="JustifyMenu" action="JustifyMenuAction"> <menuitem name="Left" action="justify-left"/> <menuitem name="Centre" action="justify-center"/> <menuitem name="Right" action="justify-right"/> <menuitem name="Fill" action="justify-fill"/> </menu> </menubar> <toolbar action="toolbar1"> <placeholder name="JustifyToolItems"> <separator/> <toolitem name="Left" action="justify-left"/> <toolitem name="Centre" action="justify-center"/> <toolitem name="Right" action="justify-right"/> <toolitem name="Fill" action="justify-fill"/> <separator/> </placeholder> </toolbar> </ui> ]| The constructed widget hierarchy is very similar to the element tree of the XML, with the exception that placeholders are merged into their parents. The correspondence of XML elements to widgets should be almost obvious: - menubar a #GtkMenuBar - toolbar a #GtkToolbar - popup a toplevel #GtkMenu - menu a #GtkMenu attached to a menuitem - menuitem a #GtkMenuItem subclass, the exact type depends on the action - toolitem a #GtkToolItem subclass, the exact type depends on the action. Note that toolitem elements may contain a menu element, but only if their associated action specifies a #GtkMenuToolButton as proxy. - separator a #GtkSeparatorMenuItem or #GtkSeparatorToolItem - accelerator a keyboard accelerator The “position” attribute determines where a constructed widget is positioned wrt. to its siblings in the partially constructed tree. If it is “top”, the widget is prepended, otherwise it is appended. # UI Merging # {#UI-Merging} The most remarkable feature of #GtkUIManager is that it can overlay a set of menuitems and toolitems over another one, and demerge them later. Merging is done based on the names of the XML elements. Each element is identified by a path which consists of the names of its anchestors, separated by slashes. For example, the menuitem named “Left” in the example above has the path `/ui/menubar/JustifyMenu/Left` and the toolitem with the same name has path `/ui/toolbar1/JustifyToolItems/Left`. # Accelerators # Every action has an accelerator path. Accelerators are installed together with menuitem proxies, but they can also be explicitly added with <accelerator> elements in the UI definition. This makes it possible to have accelerators for actions even if they have no visible proxies. # Smart Separators # {#Smart-Separators} The separators created by #GtkUIManager are “smart”, i.e. they do not show up in the UI unless they end up between two visible menu or tool items. Separators which are located at the very beginning or end of the menu or toolbar containing them, or multiple separators next to each other, are hidden. This is a useful feature, since the merging of UI elements from multiple sources can make it hard or impossible to determine in advance whether a separator will end up in such an unfortunate position. For separators in toolbars, you can set `expand="true"` to turn them from a small, visible separator to an expanding, invisible one. Toolitems following an expanding separator are effectively right-aligned. # Empty Menus Submenus pose similar problems to separators inconnection with merging. It is impossible to know in advance whether they will end up empty after merging. #GtkUIManager offers two ways to treat empty submenus: - make them disappear by hiding the menu item they’re attached to - add an insensitive “Empty” item The behaviour is chosen based on the “hide_if_empty” property of the action to which the submenu is associated. # GtkUIManager as GtkBuildable # {#GtkUIManager-BUILDER-UI} The GtkUIManager implementation of the GtkBuildable interface accepts GtkActionGroup objects as <child> elements in UI definitions. A GtkUIManager UI definition as described above can be embedded in an GtkUIManager <object> element in a GtkBuilder UI definition. The widgets that are constructed by a GtkUIManager can be embedded in other parts of the constructed user interface with the help of the “constructor” attribute. See the example below. ## An embedded GtkUIManager UI definition |[ <object class="GtkUIManager" id="uiman"> <child> <object class="GtkActionGroup" id="actiongroup"> <child> <object class="GtkAction" id="file"> <property name="label">_File</property> </object> </child> </object> </child> <ui> <menubar name="menubar1"> <menu action="file"> </menu> </menubar> </ui> </object> <object class="GtkWindow" id="main-window"> <child> <object class="GtkMenuBar" id="menubar1" constructor="uiman"/> </child> </object> ]| Creates a new ui manager object. a new ui manager object. Looks up an action by following a path. See gtk_ui_manager_get_widget() for more information about paths. the action whose proxy widget is found by following the path, or %NULL if no widget was found. a #GtkUIManager a path Looks up a widget by following a path. The path consists of the names specified in the XML description of the UI. separated by “/”. Elements which don’t have a name or action attribute in the XML (e.g. <popup>) can be addressed by their XML element name (e.g. "popup"). The root element ("/ui") can be omitted in the path. Note that the widget found by following a path that ends in a <menu>; element is the menuitem to which the menu is attached, not the menu it manages. Also note that the widgets constructed by a ui manager are not tied to the lifecycle of the ui manager. If you add the widgets returned by this function to some container or explicitly ref them, they will survive the destruction of the ui manager. the widget found by following the path, or %NULL if no widget was found a #GtkUIManager a path Adds a UI element to the current contents of @manager. If @type is %GTK_UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or separator if such an element can be inserted at the place determined by @path. Otherwise @type must indicate an element that can be inserted at the place determined by @path. If @path points to a menuitem or toolitem, the new element will be inserted before or after this item, depending on @top. a #GtkUIManager the merge id for the merged UI, see gtk_ui_manager_new_merge_id() a path the name for the added UI element the name of the action to be proxied, or %NULL to add a separator the type of UI element to add. if %TRUE, the UI element is added before its siblings, otherwise it is added after its siblings. Parses a file containing a [UI definition][XML-UI] and merges it with the current contents of @manager. The merge id for the merged UI. The merge id can be used to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred, the return value is 0. a #GtkUIManager object the name of the file to parse Parses a resource file containing a [UI definition][XML-UI] and merges it with the current contents of @manager. The merge id for the merged UI. The merge id can be used to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred, the return value is 0. a #GtkUIManager object the resource path of the file to parse Parses a string containing a [UI definition][XML-UI] and merges it with the current contents of @manager. An enclosing <ui> element is added if it is missing. The merge id for the merged UI. The merge id can be used to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred, the return value is 0. a #GtkUIManager object the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Makes sure that all pending updates to the UI have been completed. This may occasionally be necessary, since #GtkUIManager updates the UI in an idle function. A typical example where this function is useful is to enforce that the menubar and toolbar have been added to the main window before showing it: |[<!-- language="C" --> gtk_container_add (GTK_CONTAINER (window), vbox); g_signal_connect (merge, "add-widget", G_CALLBACK (add_widget), vbox); gtk_ui_manager_add_ui_from_file (merge, "my-menus"); gtk_ui_manager_add_ui_from_file (merge, "my-toolbars"); gtk_ui_manager_ensure_update (merge); gtk_widget_show (window); ]| a #GtkUIManager Returns the #GtkAccelGroup associated with @manager. the #GtkAccelGroup. a #GtkUIManager object Looks up an action by following a path. See gtk_ui_manager_get_widget() for more information about paths. the action whose proxy widget is found by following the path, or %NULL if no widget was found. a #GtkUIManager a path Returns the list of action groups associated with @manager. a #GList of action groups. The list is owned by GTK+ and should not be modified. a #GtkUIManager object Returns whether menus generated by this #GtkUIManager will have tearoff menu items. Tearoff menus are deprecated and should not be used in newly written code. whether tearoff menu items are added a #GtkUIManager Obtains a list of all toplevel widgets of the requested types. a newly-allocated #GSList of all toplevel widgets of the requested types. Free the returned list with g_slist_free(). a #GtkUIManager specifies the types of toplevel widgets to include. Allowed types are #GTK_UI_MANAGER_MENUBAR, #GTK_UI_MANAGER_TOOLBAR and #GTK_UI_MANAGER_POPUP. Creates a [UI definition][XML-UI] of the merged UI. A newly allocated string containing an XML representation of the merged UI. a #GtkUIManager Looks up a widget by following a path. The path consists of the names specified in the XML description of the UI. separated by “/”. Elements which don’t have a name or action attribute in the XML (e.g. <popup>) can be addressed by their XML element name (e.g. "popup"). The root element ("/ui") can be omitted in the path. Note that the widget found by following a path that ends in a <menu>; element is the menuitem to which the menu is attached, not the menu it manages. Also note that the widgets constructed by a ui manager are not tied to the lifecycle of the ui manager. If you add the widgets returned by this function to some container or explicitly ref them, they will survive the destruction of the ui manager. the widget found by following the path, or %NULL if no widget was found a #GtkUIManager a path Inserts an action group into the list of action groups associated with @manager. Actions in earlier groups hide actions with the same name in later groups. If @pos is larger than the number of action groups in @manager, or negative, @action_group will be inserted at the end of the internal list. a #GtkUIManager object the action group to be inserted the position at which the group will be inserted. Returns an unused merge id, suitable for use with gtk_ui_manager_add_ui(). an unused merge id. a #GtkUIManager Removes an action group from the list of action groups associated with @manager. a #GtkUIManager object the action group to be removed Unmerges the part of @manager's content identified by @merge_id. a #GtkUIManager object a merge id as returned by gtk_ui_manager_add_ui_from_string() Sets the “add_tearoffs” property, which controls whether menus generated by this #GtkUIManager will have tearoff menu items. Note that this only affects regular menus. Generated popup menus never have tearoff menu items. Tearoff menus are deprecated and should not be used in newly written code. a #GtkUIManager whether tearoff menu items are added The "add-tearoffs" property controls whether generated menus have tearoff menu items. Note that this only affects regular menus. Generated popup menus never have tearoff menu items. Tearoff menus are deprecated and should not be used in newly written code. The ::actions-changed signal is emitted whenever the set of actions changes. The ::add-widget signal is emitted for each generated menubar and toolbar. It is not emitted for generated popup menus, which can be obtained by gtk_ui_manager_get_widget(). the added widget The ::connect-proxy signal is emitted after connecting a proxy to an action in the group. This is intended for simple customizations for which a custom action class would be too clumsy, e.g. showing tooltips for menuitems in the statusbar. the action the proxy The ::disconnect-proxy signal is emitted after disconnecting a proxy from an action in the group. the action the proxy The ::post-activate signal is emitted just after the @action is activated. This is intended for applications to get notification just after any action is activated. the action The ::pre-activate signal is emitted just before the @action is activated. This is intended for applications to get notification just before any action is activated. the action the widget found by following the path, or %NULL if no widget was found a #GtkUIManager a path the action whose proxy widget is found by following the path, or %NULL if no widget was found. a #GtkUIManager a path These enumeration values are used by gtk_ui_manager_add_ui() to determine what UI element to create. Pick the type of the UI element according to context. Create a menubar. Create a menu. Create a toolbar. Insert a placeholder. Create a popup menu. Create a menuitem. Create a toolitem. Create a separator. Install an accelerator. Same as %GTK_UI_MANAGER_POPUP, but the actions’ accelerators are shown. See also gtk_print_settings_set_paper_width(). No units. Dimensions in points. Dimensions in inches. Dimensions in millimeters A #GtkVBox is a container that organizes child widgets into a single column. Use the #GtkBox packing interface to determine the arrangement, spacing, height, and alignment of #GtkVBox children. All children are allocated the same width. GtkVBox has been deprecated. You can use #GtkBox with a #GtkOrientable:orientation set to %GTK_ORIENTATION_VERTICAL instead when calling gtk_box_new(), which is a very quick and easy change. If you have derived your own classes from GtkVBox, you can change the inheritance to derive directly from #GtkBox, and set the #GtkOrientable:orientation property to %GTK_ORIENTATION_VERTICAL in your instance init function, with a call like: |[<!-- language="C" --> gtk_orientable_set_orientation (GTK_ORIENTABLE (object), GTK_ORIENTATION_VERTICAL); ]| If you have a grid-like layout composed of nested boxes, and you don’t need first-child or last-child styling, the recommendation is to switch to #GtkGrid. For more information about migrating to #GtkGrid, see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. Creates a new #GtkVBox. You can use gtk_box_new() with %GTK_ORIENTATION_VERTICAL instead, which is a quick and easy change. But the recommendation is to switch to #GtkGrid, since #GtkBox is going to go away eventually. See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. a new #GtkVBox. %TRUE if all children are to be given equal space allotments. the number of pixels to place by default between children. Creates a new vertical button box. Use gtk_button_box_new() with %GTK_ORIENTATION_VERTICAL instead a new button box #GtkWidget. The VPaned widget is a container widget with two children arranged vertically. The division between the two panes is adjustable by the user by dragging a handle. See #GtkPaned for details. GtkVPaned has been deprecated, use #GtkPaned instead. Create a new #GtkVPaned Use gtk_paned_new() with %GTK_ORIENTATION_VERTICAL instead the new #GtkVPaned The #GtkVScale widget is used to allow the user to select a value using a vertical slider. To create one, use gtk_hscale_new_with_range(). The position to show the current value, and the number of decimal places shown can be set using the parent #GtkScale class’s functions. GtkVScale has been deprecated, use #GtkScale instead. Creates a new #GtkVScale. Use gtk_scale_new() with %GTK_ORIENTATION_VERTICAL instead a new #GtkVScale. the #GtkAdjustment which sets the range of the scale. Creates a new vertical scale widget 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 gtk_scale_set_digits() to correct it. Use gtk_scale_new_with_range() with %GTK_ORIENTATION_VERTICAL instead a new #GtkVScale minimum value maximum value step increment (tick size) used with keyboard shortcuts The #GtkVScrollbar widget is a widget arranged vertically creating a scrollbar. See #GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to handle the adjustment of the scrollbar or it may be left %NULL in which case one will be created for you. See #GtkScrollbar for a description of what the fields in an adjustment represent for a scrollbar. GtkVScrollbar has been deprecated, use #GtkScrollbar instead. Creates a new vertical scrollbar. Use gtk_scrollbar_new() with %GTK_ORIENTATION_VERTICAL instead the new #GtkVScrollbar the #GtkAdjustment to use, or %NULL to create a new adjustment The #GtkVSeparator widget is a vertical separator, used to group the widgets within a window. It displays a vertical line with a shadow to make it appear sunken into the interface. GtkVSeparator has been deprecated, use #GtkSeparator instead. Creates a new #GtkVSeparator. Use gtk_separator_new() with %GTK_ORIENTATION_VERTICAL instead a new #GtkVSeparator. The #GtkViewport widget acts as an adaptor class, implementing scrollability for child widgets that lack their own scrolling capabilities. Use GtkViewport to scroll child widgets such as #GtkGrid, #GtkBox, and so on. If a widget has native scrolling abilities, such as #GtkTextView, #GtkTreeView or #GtkIconView, it can be added to a #GtkScrolledWindow with gtk_container_add(). If a widget does not, you must first add the widget to a #GtkViewport, then add the viewport to the scrolled window. gtk_container_add() does this automatically if a child that does not implement #GtkScrollable is added to a #GtkScrolledWindow, so you can ignore the presence of the viewport. The GtkViewport will start scrolling content only if allocated less than the child widget’s minimum size in a given orientation. # CSS nodes GtkViewport has a single CSS node with name viewport. Creates a new #GtkViewport with the given adjustments, or with default adjustments if none are given. a new #GtkViewport horizontal adjustment vertical adjustment Gets the bin window of the #GtkViewport. a #GdkWindow a #GtkViewport Returns the horizontal adjustment of the viewport. Use gtk_scrollable_get_hadjustment() the horizontal adjustment of @viewport. a #GtkViewport. Gets the shadow type of the #GtkViewport. See gtk_viewport_set_shadow_type(). the shadow type a #GtkViewport Returns the vertical adjustment of the viewport. Use gtk_scrollable_get_vadjustment() the vertical adjustment of @viewport. a #GtkViewport. Gets the view window of the #GtkViewport. a #GdkWindow a #GtkViewport Sets the horizontal adjustment of the viewport. Use gtk_scrollable_set_hadjustment() a #GtkViewport. a #GtkAdjustment. Sets the shadow type of the viewport. a #GtkViewport. the new shadow type. Sets the vertical adjustment of the viewport. Use gtk_scrollable_set_vadjustment() a #GtkViewport. a #GtkAdjustment. The parent class. #GtkVolumeButton is a subclass of #GtkScaleButton that has been tailored for use as a volume control widget with suitable icons, tooltips and accessible labels. Creates a #GtkVolumeButton, 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 #GtkScaleButton. a new #GtkVolumeButton 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. GtkWidget 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: - #GtkWidgetClass.get_request_mode() - #GtkWidgetClass.get_preferred_width() - #GtkWidgetClass.get_preferred_height() - #GtkWidgetClass.get_preferred_height_for_width() - #GtkWidgetClass.get_preferred_width_for_height() - #GtkWidgetClass.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 #GtkSizeRequestMode chosen by the toplevel. For example, when queried in the normal %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: First, the default minimum and natural width for each widget in the interface will be computed using gtk_widget_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 gtk_widget_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 gtk_window_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 gtk_window_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 #GtkWidget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, #GtkWidget caches a small number of results to avoid re-querying for the same sizes in one allocation cycle. See [GtkContainer’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 #GtkLabel that does height-for-width word wrapping will not expect to have #GtkWidgetClass.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 %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH widget generally deals with width-for-height requests, for #GtkWidgetClass.get_preferred_height() it will do: |[<!-- language="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 #GtkWidgetClass.get_preferred_width_for_height() it will simply return the minimum and natural width: |[<!-- language="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: |[<!-- language="C" --> GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget, &min, &natural); ]| It will not work to use the wrapper functions, such as gtk_widget_get_preferred_width() inside your own size request implementation. These return a request adjusted by #GtkSizeGroup and by the #GtkWidgetClass.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, #GtkSizeGroup, 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 %GTK_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 #GtkWidgetClass.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 #GtkWidgetClass.get_preferred_height() and #GtkWidgetClass.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 %GTK_ALIGN_FILL, but the selected baseline can be found via gtk_widget_get_allocated_baseline(). If this has a value other than -1 you need to align the widget such that the baseline appears at the position. # Style Properties #GtkWidget 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 gtk_widget_class_install_style_property() to install style properties for a widget class, gtk_widget_class_find_style_property() or gtk_widget_class_list_style_properties() to get information about existing style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or gtk_widget_style_get_valist() to obtain the value of a style property. # GtkWidget as GtkBuildable The GtkWidget implementation of the GtkBuildable 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: |[ <object class="GtkButton"> <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/> </object> ]| In addition to accelerators, GtkWidget also support a custom <accessible> element, which supports actions and relations. Properties on the accessible implementation of an object can be set by accessing the internal child “accessible” of a #GtkWidget. An example of a UI definition fragment specifying an accessible: |[ <object class="GtkLabel" id="label1"/> <property name="label">I am a Label for a Button</property> </object> <object class="GtkButton" id="button1"> <accessibility> <action action_name="click" translatable="yes">Click the button.</action> <relation target="label1" type="labelled-by"/> </accessibility> <child internal-child="accessible"> <object class="AtkObject" id="a11y-button1"> <property name="accessible-name">Clickable Button</property> </object> </child> </object> ]| Finally, GtkWidget allows style information such as style classes to be associated with widgets, using the custom <style> element: |[ <object class="GtkButton" id="button1"> <style> <class name="my-special-button-class"/> <class name="dark-button"/> </style> </object> ]| # Building composite widgets from template XML ## {#composite-templates} GtkWidget exposes some facilities to automate the procedure of creating composite widgets using #GtkBuilder interface description language. To create composite widgets with #GtkBuilder XML, one must associate the interface description with the widget class at class initialization time using gtk_widget_class_set_template(). The interface description semantics expected in composite template descriptions is slightly different from regular #GtkBuilder XML. Unlike regular interface descriptions, gtk_widget_class_set_template() will expect a <template> tag as a direct child of the toplevel <interface> tag. The <template> tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type, this is ignored by the GtkBuilder but required for Glade to introspect what kind of properties and internal children exist for a given type when the actual type does not exist. The XML which is contained inside the <template> tag behaves as if it were added to the <object> tag defining @widget itself. You may set properties on @widget by inserting <property> tags into the <template> tag, and also add <child> tags to add children and extend @widget in the normal way you would with <object> tags. Additionally, <object> tags can also be added before and after the initial <template> tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the <template> tag. An example of a GtkBuilder Template Definition: |[ <interface> <template class="FooWidget" parent="GtkBox"> <property name="orientation">GTK_ORIENTATION_HORIZONTAL</property> <property name="spacing">4</property> <child> <object class="GtkButton" id="hello_button"> <property name="label">Hello World</property> <signal name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/> </object> </child> <child> <object class="GtkButton" id="goodbye_button"> <property name="label">Goodbye World</property> </object> </child> </template> </interface> ]| Typically, you'll place the template fragment into a file that is bundled with your project, using #GResource. In order to load the template, you need to call gtk_widget_class_set_template_from_resource() from the class initialization of your #GtkWidget type: |[<!-- language="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 gtk_widget_init_template() from the instance initialization function: |[<!-- language="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 gtk_widget_get_template_child() function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call gtk_widget_class_bind_template_child_private() with that name, e.g. |[<!-- language="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. |[<!-- language="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); } ]| 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 g_object_new(), but returns a widget so you don’t have to cast the object yourself. a new #GtkWidget of type @widget_type type ID of the widget to create name of first property to set value of first property, followed by more properties, %NULL-terminated Obtains the current default reading direction. See gtk_widget_set_default_direction(). the current default direction. Returns the default style used by all widgets initially. Use #GtkStyleContext instead, and gtk_css_provider_get_default() to obtain a #GtkStyleProvider with the default widget style information. the default style. This #GtkStyle object is owned by GTK+ and should not be modified or freed. Cancels the effect of a previous call to gtk_widget_push_composite_child(). Use gtk_widget_class_set_template(), or don’t use this API at all. Makes all newly-created widgets as composite children until the corresponding gtk_widget_pop_composite_child() call. A composite child is a child that’s an implementation detail of the container it’s inside and should not be visible to people using the container. Composite children aren’t treated differently by GTK+ (but see gtk_container_foreach() vs. gtk_container_forall()), but e.g. GUI builders might want to treat them in a different way. This API never really worked well and was mostly unused, now we have a more complete mechanism for composite children, see gtk_widget_class_set_template(). Sets the default reading direction for widgets where the direction has not been explicitly set by gtk_widget_set_direction(). the new default direction. This cannot be %GTK_TEXT_DIR_NONE. Determines whether an accelerator that activates the signal identified by @signal_id can currently be activated. This is done by emitting the #GtkWidget::can-activate-accel signal on @widget; if the signal isn’t overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped. %TRUE if the accelerator can be activated. a #GtkWidget the ID of a signal installed on @widget Emits a #GtkWidget::child-notify signal for the [child property][child-properties] @child_property on @widget. This is the analogue of g_object_notify() for child properties. Also see gtk_container_child_notify(). a #GtkWidget the name of a child property installed on the class of @widget’s parent 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 #GtkWidget::destroy signal if you hold a reference to @widget and you wish to remove it when this function is called. It is not necessary to do so if you are implementing a #GtkContainer, as you'll be able to use the #GtkContainerClass.remove() virtual function for that. It's important to notice that gtk_widget_destroy() will only cause the @widget to be finalized if no additional references, acquired using g_object_ref(), are held on it. In case additional references are in place, the @widget will be in an "inert" state after calling this function; @widget will still point to valid memory, allowing you to release the references you hold, but you may not query the widget's own state. You should typically call this function on top level widgets, and rarely on child widgets. See also: gtk_container_remove() a #GtkWidget Rarely-used function. This function is used to emit the event signals on a widget (those signals should never be emitted without using this function to do so). If you want to synthesize an event though, don’t use this function; instead, use gtk_main_do_event() so the event will behave as if it were in the event queue. Don’t synthesize expose events; instead, use gdk_window_invalidate_rect() to invalidate a region of the window. return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a #GdkEvent Returns the accessible object that describes the widget to an assistive technology. If accessibility support is not available, this #AtkObject instance may be a no-op. Likewise, if no class-specific #AtkObject implementation is available for the widget instance in question, it will inherit an #AtkObject 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. the #AtkObject associated with @widget a #GtkWidget 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 GtkWidgetClass::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. a #GtkWidget instance location to store the minimum height, or %NULL location to store the natural height, or %NULL 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 GtkWidgetClass::adjust_size_request and GtkWidgetClass::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. a #GtkWidget instance the width which is available for allocation, or -1 if none location for storing the minimum height, or %NULL location for storing the natural height, or %NULL location for storing the baseline for the minimum height, or %NULL location for storing the baseline for the natural height, or %NULL Retrieves a widget’s minimum and natural height if it would be given the specified @width. The returned request will be modified by the GtkWidgetClass::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. a #GtkWidget instance the width which is available for allocation location for storing the minimum height, or %NULL location for storing the natural height, or %NULL 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 GtkWidgetClass::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. a #GtkWidget instance location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a widget’s minimum and natural width if it would be given the specified @height. The returned request will be modified by the GtkWidgetClass::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. a #GtkWidget instance the height which is available for allocation location for storing the minimum width, or %NULL location for storing the natural width, or %NULL Gets whether the widget prefers a height-for-width layout or a width-for-height layout. #GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities. The #GtkSizeRequestMode preferred by @widget. a #GtkWidget instance Causes @widget to have the keyboard focus for the #GtkWindow it's inside. @widget must be a focusable widget, such as a #GtkEntry; something like #GtkFrame won’t work. More precisely, it must have the %GTK_CAN_FOCUS flag set. Use gtk_widget_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. a #GtkWidget Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user). a #GtkWidget This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the #GtkWidget::keynav-failed signal on the widget and its return value should be interpreted in a way similar to the return value of gtk_widget_child_focus(): When %TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When %FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling gtk_widget_child_focus() on the widget’s toplevel. The default ::keynav-failed handler returns %FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of #GtkDirectionType it returns %TRUE. Whenever the default handler returns %TRUE, it also calls gtk_widget_error_bell() to notify the user of the failed keyboard navigation. A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of #GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. %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). a #GtkWidget direction of focus movement This function is only for use in widget implementations. Causes a widget to be mapped if it isn’t already. a #GtkWidget Emits the #GtkWidget::mnemonic-activate signal. %TRUE if the signal has been handled a #GtkWidget %TRUE if there are other widgets with the same mnemonic Invalidates the area of @widget defined by @region by calling gdk_window_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 #GtkDrawingArea or some portion thereof. a #GtkWidget region to draw Creates the GDK (windowing system) resources associated with a widget. For example, @widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling gtk_widget_realize() realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as #GtkWidget::draw. Or simply g_signal_connect () to the #GtkWidget::realize signal. a #GtkWidget Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. If you want to show all the widgets in a container, it’s easier to call gtk_widget_show_all() on the container, instead of individually showing the widgets. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped. a #GtkWidget Recursively shows a widget, and any child widgets (if the widget is a container). a #GtkWidget This function is only used by #GtkContainer 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 #GtkWidget:halign and #GtkWidget:valign properties. For baseline support in containers you need to use gtk_widget_size_allocate_with_baseline() instead. a #GtkWidget position and size to be allocated to @widget This function is only for use in widget implementations. Causes a widget to be unmapped if it’s currently mapped. a #GtkWidget This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as @widget->window). a #GtkWidget For widgets that can be “activated” (buttons, menu items, etc.) this function activates them. Activation is what happens when you press Enter on a widget during key navigation. If @widget isn't activatable, the function returns %FALSE. %TRUE if the widget was activatable a #GtkWidget that’s activatable Installs an accelerator for this @widget in @accel_group that causes @accel_signal to be emitted if the accelerator is activated. The @accel_group needs to be added to the widget’s toplevel via gtk_window_add_accel_group(), and the signal must be of type %G_SIGNAL_ACTION. Accelerators added through this function are not user changeable during runtime. If you want to support accelerators that can be changed by the user, use gtk_accel_map_add_entry() and gtk_widget_set_accel_path() or gtk_menu_item_set_accel_path() instead. widget to install an accelerator on widget signal to emit on accelerator activation accel group for this widget, added to its toplevel GDK keyval of the accelerator modifier key combination of the accelerator flag accelerators, e.g. %GTK_ACCEL_VISIBLE Adds the device events in the bitfield @events to the event mask for @widget. See gtk_widget_set_device_events() for details. a #GtkWidget a #GdkDevice an event mask, see #GdkEventMask Adds the events in the bitfield @events to the event mask for @widget. See gtk_widget_set_events() and the [input handling overview][event-masks] for details. a #GtkWidget an event mask, see #GdkEventMask Adds a widget to the list of mnemonic labels for this widget. (See gtk_widget_list_mnemonic_labels()). Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well, by using a connection to the #GtkWidget::destroy signal or a weak notifier. a #GtkWidget a #GtkWidget that acts as a mnemonic label for @widget Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a #GtkLabel), then you will have to call gtk_widget_queue_resize() or gtk_widget_queue_draw_area() yourself. gdk_frame_clock_get_frame_time() should generally be used for timing continuous animations and gdk_frame_timings_get_predicted_presentation_time() if you are trying to display isolated frames at particular times. This is a more convenient alternative to connecting directly to the #GdkFrameClock::update signal of #GdkFrameClock, since you don't have to worry about when a #GdkFrameClock is assigned to a widget. an id for the connection of this callback. Remove the callback by passing it to gtk_widget_remove_tick_callback() a #GtkWidget function to call for updating animations data to pass to @callback function to call to free @user_data when the callback is removed. Determines whether an accelerator that activates the signal identified by @signal_id can currently be activated. This is done by emitting the #GtkWidget::can-activate-accel signal on @widget; if the signal isn’t overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped. %TRUE if the accelerator can be activated. a #GtkWidget the ID of a signal installed on @widget This function is used by custom widget implementations; if you're writing an app, you’d use gtk_widget_grab_focus() to move the focus to a particular widget, and gtk_container_set_focus_chain() to change the focus tab order. So you may want to investigate those functions instead. gtk_widget_child_focus() is called by containers as the user moves around the window using keyboard shortcuts. @direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). gtk_widget_child_focus() emits the #GtkWidget::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 gtk_widget_grab_focus() to place the focus accordingly; if returning %FALSE, they don’t modify the current focus location. %TRUE if focus ended up inside @widget a #GtkWidget direction of focus movement Emits a #GtkWidget::child-notify signal for the [child property][child-properties] @child_property on @widget. This is the analogue of g_object_notify() for child properties. Also see gtk_container_child_notify(). a #GtkWidget the name of a child property installed on the class of @widget’s parent Same as gtk_widget_path(), but always uses the name of a widget’s type, never uses a custom name set with gtk_widget_set_name(). Use gtk_widget_get_path() instead a #GtkWidget location to store the length of the class path, or %NULL location to store the class path as an allocated string, or %NULL location to store the reverse class path as an allocated string, or %NULL Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at gtk_widget_get_hexpand() or gtk_widget_get_vexpand(). This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded. The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do. whether widget tree rooted here should be expanded the widget expand direction Creates a new #PangoContext with the appropriate font map, font options, font description, and base direction for drawing text for this widget. See also gtk_widget_get_pango_context(). the new #PangoContext a #GtkWidget Creates a new #PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget. If you keep a #PangoLayout created in this way around, you need to re-create it when the widget #PangoContext is replaced. This can be tracked by using the #GtkWidget::screen-changed signal on the widget. the new #PangoLayout a #GtkWidget text to set on the layout (can be %NULL) 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 #GtkWidget::destroy signal if you hold a reference to @widget and you wish to remove it when this function is called. It is not necessary to do so if you are implementing a #GtkContainer, as you'll be able to use the #GtkContainerClass.remove() virtual function for that. It's important to notice that gtk_widget_destroy() will only cause the @widget to be finalized if no additional references, acquired using g_object_ref(), are held on it. In case additional references are in place, the @widget will be in an "inert" state after calling this function; @widget will still point to valid memory, allowing you to release the references you hold, but you may not query the widget's own state. You should typically call this function on top level widgets, and rarely on child widgets. See also: gtk_container_remove() a #GtkWidget This function sets *@widget_pointer to %NULL if @widget_pointer != %NULL. It’s intended to be used as a callback connected to the “destroy” signal of a widget. You connect gtk_widget_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 %NULL. Useful for example to avoid multiple copies of the same dialog. a #GtkWidget address of a variable that contains @widget Returns %TRUE if @device has been shadowed by a GTK+ device grab on another widget, so it would stop sending events to @widget. This may be used in the #GtkWidget::grab-notify signal to check for specific devices. See gtk_device_grab_add(). %TRUE if there is an ongoing grab on @device by another #GtkWidget than @widget. a #GtkWidget a #GdkDevice This function is equivalent to gtk_drag_begin_with_coordinates(), passing -1, -1 as coordinates. Use gtk_drag_begin_with_coordinates() instead the context for this drag the source widget The targets (data formats) in which the source can provide the data A bitmask of the allowed drag actions for this drag The button the user clicked to start the drag The event that triggered the start of the drag, or %NULL if none can be obtained. 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 gtk_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 %NULL, 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 #GtkWidget::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 #GtkWidget::button-press-event handler. 2. During a #GtkWidget::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 #GtkWidget::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 %NULL instead. the context for this drag the source widget The targets (data formats) in which the source can provide the data A bitmask of the allowed drag actions for this drag The button the user clicked to start the drag The event that triggered the start of the drag, or %NULL if none can be obtained. The initial x coordinate to start dragging from, in the coordinate space of @widget. If -1 is passed, the coordinates are retrieved from @event or the current pointer position The initial y coordinate to start dragging from, in the coordinate space of @widget. If -1 is passed, the coordinates are retrieved from @event or the current pointer position 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. %TRUE if the drag threshold has been passed. a #GtkWidget X coordinate of start of drag Y coordinate of start of drag current X coordinate current Y coordinate Add the image targets supported by #GtkSelectionData to the target list of the drag destination. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_image_targets() and gtk_drag_dest_set_target_list(). a #GtkWidget that’s a drag destination Add the text targets supported by #GtkSelectionData to the target list of the drag destination. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_text_targets() and gtk_drag_dest_set_target_list(). a #GtkWidget that’s a drag destination Add the URI targets supported by #GtkSelectionData to the target list of the drag destination. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_uri_targets() and gtk_drag_dest_set_target_list(). a #GtkWidget that’s a drag destination 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 gtk_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. first target that the source offers and the dest can accept, or %GDK_NONE drag destination widget drag context list of droppable targets, or %NULL to use gtk_drag_dest_get_target_list (@widget). Returns the list of targets this widget can accept from drag-and-drop. the #GtkTargetList, or %NULL if none a #GtkWidget Returns whether the widget has been configured to always emit #GtkWidget::drag-motion signals. %TRUE if the widget always emits #GtkWidget::drag-motion events a #GtkWidget that’s a drag destination 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 (#GtkWidget::drag-motion, #GtkWidget::drag-drop, ...). They all exist for convenience. When passing #GTK_DEST_DEFAULT_ALL for instance it is sufficient to connect to the widget’s #GtkWidget::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 #GtkWidget::drag-motion. The default behaviors described by @flags make some assumptions, that can conflict with your own signal handlers. For instance #GTK_DEST_DEFAULT_DROP causes invokations of gdk_drag_status() in the context of #GtkWidget::drag-motion, and invokations of gtk_drag_finish() in #GtkWidget::drag-data-received. Especially the later is dramatic, when your own #GtkWidget::drag-motion handler calls gtk_drag_get_data() to inspect the dragged data. There’s no way to set a default action here, you can use the #GtkWidget::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: |[<!-- language="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); } ]| a #GtkWidget which types of default drag behavior to use a pointer to an array of #GtkTargetEntrys indicating the drop types that this @widget will accept, or %NULL. Later you can access the list with gtk_drag_dest_get_target_list() and gtk_drag_dest_find_target(). the number of entries in @targets a bitmask of possible actions for a drop onto this @widget. Sets this widget as a proxy for drops to another window. a #GtkWidget the window to which to forward drag events the drag protocol which the @proxy_window accepts (You can use gdk_drag_get_protocol() to determine this) If %TRUE, send the same coordinates to the destination, because it is an embedded subwindow. Sets the target types that this widget can accept from drag-and-drop. The widget must first be made into a drag destination with gtk_drag_dest_set(). a #GtkWidget that’s a drag destination list of droppable targets, or %NULL for none Tells the widget to emit #GtkWidget::drag-motion and #GtkWidget::drag-leave events regardless of the targets and the %GTK_DEST_DEFAULT_MOTION flag. This may be used when a widget wants to do generic actions regardless of the targets that the source offers. a #GtkWidget that’s a drag destination whether to accept all targets Clears information about a drop destination set with gtk_drag_dest_set(). The widget will no longer receive notification of drags. a #GtkWidget Gets the data associated with a drag. When the data is received or the retrieval fails, GTK+ will emit a #GtkWidget::drag-data-received signal. Failure of the retrieval is indicated by the length field of the @selection_data signal parameter being negative. However, when gtk_drag_get_data() is called implicitely because the %GTK_DEST_DEFAULT_DROP was set, then the widget will not receive notification of failed drops. the widget that will receive the #GtkWidget::drag-data-received signal the drag context the target (form of the data) to retrieve a timestamp for retrieving the data. This will generally be the time received in a #GtkWidget::drag-motion or #GtkWidget::drag-drop signal Highlights a widget as a currently hovered drop target. To end the highlight, call gtk_drag_unhighlight(). GTK+ calls this automatically if %GTK_DEST_DEFAULT_HIGHLIGHT is set. a widget to highlight Add the writable image targets supported by #GtkSelectionData to the target list of the drag source. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_image_targets() and gtk_drag_source_set_target_list(). a #GtkWidget that’s is a drag source Add the text targets supported by #GtkSelectionData to the target list of the drag source. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_text_targets() and gtk_drag_source_set_target_list(). a #GtkWidget that’s is a drag source Add the URI targets supported by #GtkSelectionData to the target list of the drag source. The targets are added with @info = 0. If you need another value, use gtk_target_list_add_uri_targets() and gtk_drag_source_set_target_list(). a #GtkWidget that’s is a drag source Gets the list of targets this widget can provide for drag-and-drop. the #GtkTargetList, or %NULL if none a #GtkWidget 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. a #GtkWidget the bitmask of buttons that can start the drag the table of targets that the drag will support, may be %NULL the number of items in @targets the bitmask of possible actions for a drag from this widget Sets the icon that will be used for drags from a particular source to @icon. See the docs for #GtkIconTheme for more details. a #GtkWidget A #GIcon Sets the icon that will be used for drags from a particular source to a themed icon. See the docs for #GtkIconTheme for more details. a #GtkWidget name of icon to use Sets the icon that will be used for drags from a particular widget from a #GdkPixbuf. GTK+ retains a reference for @pixbuf and will release it when it is no longer needed. a #GtkWidget the #GdkPixbuf for the drag icon Sets the icon that will be used for drags from a particular source to a stock icon. Use gtk_drag_source_set_icon_name() instead. a #GtkWidget the ID of the stock icon to use Changes the target types that this widget offers for drag-and-drop. The widget must first be made into a drag source with gtk_drag_source_set(). a #GtkWidget that’s a drag source list of draggable targets, or %NULL for none Undoes the effects of gtk_drag_source_set(). a #GtkWidget Removes a highlight set by gtk_drag_highlight() from a widget. a widget to remove the highlight from Draws @widget to @cr. The top left corner of the widget will be drawn to the currently set origin point of @cr. You should pass a cairo context as @cr argument that is in an original state. Otherwise the resulting drawing is undefined. For example changing the operator using cairo_set_operator() or the line width using cairo_set_line_width() might have unwanted side effects. You may however change the context’s transform matrix - like with cairo_scale(), cairo_translate() or cairo_set_matrix() and clip region with cairo_clip() prior to calling this function. Also, it is fine to modify the context with cairo_save() and cairo_push_group() prior to calling this function. Note that special-purpose widgets may contain special code for rendering to the screen and might appear differently on screen and when rendered using gtk_widget_draw(). the widget to draw. It must be drawable (see gtk_widget_is_drawable()) and a size must have been allocated. a cairo context to draw to Ensures that @widget has a style (@widget->style). Not a very useful function; most of the time, if you want the style, the widget is realized, and realized widgets are guaranteed to have a style already. Use #GtkStyleContext instead a #GtkWidget Notifies the user about an input-related error on this widget. If the #GtkSettings:gtk-error-bell setting is %TRUE, it calls gdk_window_beep(), otherwise it does nothing. Note that the effect of gdk_window_beep() can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used. a #GtkWidget Rarely-used function. This function is used to emit the event signals on a widget (those signals should never be emitted without using this function to do so). If you want to synthesize an event though, don’t use this function; instead, use gtk_main_do_event() so the event will behave as if it were in the event queue. Don’t synthesize expose events; instead, use gdk_window_invalidate_rect() to invalidate a region of the window. return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a #GdkEvent Stops emission of #GtkWidget::child-notify signals on @widget. The signals are queued until gtk_widget_thaw_child_notify() is called on @widget. This is the analogue of g_object_freeze_notify() for child properties. a #GtkWidget Returns the accessible object that describes the widget to an assistive technology. If accessibility support is not available, this #AtkObject instance may be a no-op. Likewise, if no class-specific #AtkObject implementation is available for the widget instance in question, it will inherit an #AtkObject 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. the #AtkObject associated with @widget a #GtkWidget Retrieves the #GActionGroup that was registered using @prefix. The resulting #GActionGroup may have been registered to @widget or any #GtkWidget in its ancestry. If no action group was found matching @prefix, then %NULL is returned. A #GActionGroup or %NULL. A #GtkWidget The “prefix” of the action group. Returns the baseline that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the #GtkWidget::draw function, and when allocating child widgets in #GtkWidget::size_allocate. the baseline of the @widget, or -1 if none the widget to query Returns the height that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the #GtkWidget::draw function. the height of the @widget the widget to query Retrieves the widget’s allocated size. This function returns the last values passed to gtk_widget_size_allocate_with_baseline(). The value differs from the size returned in gtk_widget_get_allocation() in that functions like gtk_widget_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. a #GtkWidget a pointer to a #GtkAllocation to copy to a pointer to an integer to copy to Returns the width that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the #GtkWidget::draw function. the width of the @widget the widget to query Retrieves the widget’s allocation. Note, when implementing a #GtkContainer: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent container typically calls gtk_widget_size_allocate() with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. gtk_widget_get_allocation() returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the gtk_widget_size_allocate() allocation, however. So a #GtkContainer 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 gtk_widget_size_allocate(), since it isn’t stored; if a container implementation needs that information it will have to track it itself. a #GtkWidget a pointer to a #GtkAllocation to copy to Gets the first ancestor of @widget with type @widget_type. For example, `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets the first #GtkBox that’s an ancestor of @widget. No reference will be added to the returned widget; it should not be unreferenced. See note about checking for a toplevel #GtkWindow in the docs for gtk_widget_get_toplevel(). Note that unlike gtk_widget_is_ancestor(), gtk_widget_get_ancestor() considers @widget to be an ancestor of itself. the ancestor widget, or %NULL if not found a #GtkWidget ancestor type Determines whether the application intends to draw on the widget in an #GtkWidget::draw handler. See gtk_widget_set_app_paintable() %TRUE if the widget is app paintable a #GtkWidget Determines whether @widget can be a default widget. See gtk_widget_set_can_default(). %TRUE if @widget can be a default widget, %FALSE otherwise a #GtkWidget Determines whether @widget can own the input focus. See gtk_widget_set_can_focus(). %TRUE if @widget can own the input focus, %FALSE otherwise a #GtkWidget This function is only for use in widget implementations. Obtains @widget->requisition, unless someone has forced a particular geometry on the widget (e.g. with gtk_widget_set_size_request()), in which case it returns that geometry instead of the widget's requisition. This function differs from gtk_widget_size_request() in that it retrieves the last size request value from @widget->requisition, while gtk_widget_size_request() actually calls the "size_request" method on @widget to compute the size request and fill in @widget->requisition, and only then returns @widget->requisition. Because this function does not call the “size_request” method, it can only be used when you know that @widget->requisition is up-to-date, that is, gtk_widget_size_request() has been called since the last time a resize was queued. In general, only container implementations have this information; applications should use gtk_widget_size_request(). Use gtk_widget_get_preferred_size() instead. a #GtkWidget a #GtkRequisition to be filled in Gets the value set with gtk_widget_set_child_visible(). If you feel a need to use this function, your code probably needs reorganization. This function is only useful for container implementations and never should be called by an application. %TRUE if the widget is mapped with the parent. a #GtkWidget Retrieves the widget’s clip area. The clip area is the area in which all of @widget's drawing will happen. Other toolkits call it the bounding box. Historically, in GTK+ the clip area has been equal to the allocation retrieved via gtk_widget_get_allocation(). a #GtkWidget a pointer to a #GtkAllocation to copy to Returns the clipboard object for the given selection to be used with @widget. @widget must have a #GdkDisplay associated with it, so must be attached to a toplevel window. 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. a #GtkWidget a #GdkAtom 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. Obtains the composite name of a widget. Use gtk_widget_class_set_template(), or don’t use this API at all. the composite name of @widget, or %NULL if @widget is not a composite child. The string should be freed when it is no longer needed. a #GtkWidget Returns whether @device can interact with @widget and its children. See gtk_widget_set_device_enabled(). %TRUE is @device is enabled for @widget a #GtkWidget a #GdkDevice 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 event mask for @widget a #GtkWidget a #GdkDevice Gets the reading direction for a particular widget. See gtk_widget_set_direction(). the reading direction for the widget. a #GtkWidget Get the #GdkDisplay for the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a #GtkWindow at the top. In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. the #GdkDisplay for the toplevel for this widget. a #GtkWidget Determines whether the widget is double buffered. See gtk_widget_set_double_buffered() %TRUE if the widget is double buffered a #GtkWidget Returns the event mask (see #GdkEventMask) 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 gtk_widget_set_events() or gtk_widget_add_events(), and the event mask necessary to cater for every #GtkEventController created for the widget. event mask for @widget a #GtkWidget Returns whether the widget should grab focus when it is clicked with the mouse. See gtk_widget_set_focus_on_click(). %TRUE if the widget should grab focus when it is clicked with the mouse. a #GtkWidget Gets the font map that has been set with gtk_widget_set_font_map(). A #PangoFontMap, or %NULL a #GtkWidget Returns the #cairo_font_options_t used for Pango rendering. When not set, the defaults font options for the #GdkScreen will be used. the #cairo_font_options_t or %NULL if not set a #GtkWidget Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call gdk_frame_clock_get_frame_time(), in order to get a time to use for animating. For example you might record the start of the animation with an initial value from gdk_frame_clock_get_frame_time(), and then update the animation by calling gdk_frame_clock_get_frame_time() again during each repaint. gdk_frame_clock_request_phase() will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use gtk_widget_queue_draw() which invalidates the widget (thus scheduling it to receive a draw on the next frame). gtk_widget_queue_draw() will also end up requesting a frame on the appropriate frame clock. A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock. Unrealized widgets do not have a frame clock. a #GdkFrameClock, or %NULL if widget is unrealized a #GtkWidget Gets the value of the #GtkWidget:halign property. For backwards compatibility reasons this method will never return %GTK_ALIGN_BASELINE, but instead it will convert it to %GTK_ALIGN_FILL. Baselines are not supported for horizontal alignment. the horizontal alignment of @widget a #GtkWidget Returns the current value of the has-tooltip property. See #GtkWidget:has-tooltip for more information. current value of has-tooltip on @widget. a #GtkWidget Determines whether @widget has a #GdkWindow of its own. See gtk_widget_set_has_window(). %TRUE if @widget has a window, %FALSE otherwise a #GtkWidget Gets whether the widget would like any available extra horizontal space. When a user resizes a #GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Containers should use gtk_widget_compute_expand() rather than this function, to see whether a widget, or any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also. This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand. whether hexpand flag is set the widget Gets whether gtk_widget_set_hexpand() has been used to explicitly set the expand flag on this widget. If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. whether hexpand has been explicitly set the widget Whether the widget is mapped. %TRUE if the widget is mapped, %FALSE otherwise. a #GtkWidget Gets the value of the #GtkWidget:margin-bottom property. The bottom margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-end property. The end margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-left property. Use gtk_widget_get_margin_start() instead. The left margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-right property. Use gtk_widget_get_margin_end() instead. The right margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-start property. The start margin of @widget a #GtkWidget Gets the value of the #GtkWidget:margin-top property. The top margin of @widget a #GtkWidget Returns the modifier mask the @widget’s windowing system backend uses for a particular purpose. See gdk_keymap_get_modifier_mask(). the modifier mask used for @intent. a #GtkWidget the use case for the modifier mask Returns the current modifier style for the widget. (As set by gtk_widget_modify_style().) If no style has previously set, a new #GtkRcStyle will be created with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you must call gtk_widget_modify_style(), passing in the returned rc style, to make sure that your changes take effect. Caution: passing the style back to gtk_widget_modify_style() will normally end up destroying it, because gtk_widget_modify_style() copies the passed-in style and sets the copy as the new modifier style, thus dropping any reference to the old modifier style. Add a reference to the modifier style if you want to keep it alive. Use #GtkStyleContext with a custom #GtkStyleProvider instead the modifier style for the widget. This rc style is owned by the widget. If you want to keep a pointer to value this around, you must add a refcount using g_object_ref(). a #GtkWidget Retrieves the name of a widget. See gtk_widget_set_name() for the significance of widget names. name of the widget. This string is owned by GTK+ and should not be modified or freed a #GtkWidget Returns the current value of the #GtkWidget:no-show-all property, which determines whether calls to gtk_widget_show_all() will affect this widget. the current value of the “no-show-all” property. a #GtkWidget Fetches the requested opacity for this widget. See gtk_widget_set_opacity(). the requested opacity for this widget. a #GtkWidget Gets a #PangoContext with the appropriate font map, font description, and base direction for this widget. Unlike the context returned by gtk_widget_create_pango_context(), this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by using the #GtkWidget::screen-changed signal on the widget. the #PangoContext for the widget. a #GtkWidget Returns the parent container of @widget. the parent container of @widget, or %NULL a #GtkWidget Gets @widget’s parent window, or %NULL if it does not have one. the parent window of @widget, or %NULL if it does not have a parent window. a #GtkWidget. Returns the #GtkWidgetPath representing @widget, if the widget is not connected to a toplevel widget, a partial path will be created. The #GtkWidgetPath representing @widget a #GtkWidget Obtains the location of the mouse pointer in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as @widget->window coordinates for widgets that return %TRUE for gtk_widget_get_has_window(); and are relative to @widget->allocation.x, @widget->allocation.y otherwise. Use gdk_window_get_device_position() instead. a #GtkWidget return location for the X coordinate, or %NULL return location for the Y coordinate, or %NULL 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 GtkWidgetClass::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. a #GtkWidget instance location to store the minimum height, or %NULL location to store the natural height, or %NULL 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 GtkWidgetClass::adjust_size_request and GtkWidgetClass::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. a #GtkWidget instance the width which is available for allocation, or -1 if none location for storing the minimum height, or %NULL location for storing the natural height, or %NULL location for storing the baseline for the minimum height, or %NULL location for storing the baseline for the natural height, or %NULL Retrieves a widget’s minimum and natural height if it would be given the specified @width. The returned request will be modified by the GtkWidgetClass::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. a #GtkWidget instance the width which is available for allocation location for storing the minimum height, or %NULL location for storing the natural height, or %NULL Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management. This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as GtkLayout. Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width. Use gtk_widget_get_preferred_height_and_baseline_for_width() if you want to support baseline alignment. a #GtkWidget instance location for storing the minimum size, or %NULL location for storing the natural size, or %NULL 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 GtkWidgetClass::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. a #GtkWidget instance location to store the minimum width, or %NULL location to store the natural width, or %NULL Retrieves a widget’s minimum and natural width if it would be given the specified @height. The returned request will be modified by the GtkWidgetClass::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. a #GtkWidget instance the height which is available for allocation location for storing the minimum width, or %NULL location for storing the natural width, or %NULL Determines whether @widget is realized. %TRUE if @widget is realized, %FALSE otherwise a #GtkWidget Determines whether @widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See gtk_widget_set_receives_default(). %TRUE if @widget acts as the default widget when focused, %FALSE otherwise a #GtkWidget Gets whether the widget prefers a height-for-width layout or a width-for-height layout. #GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities. The #GtkSizeRequestMode preferred by @widget. a #GtkWidget instance Retrieves the widget’s requisition. This function should only be used by widget implementations in order to figure whether the widget’s requisition has actually changed after some internal state change (so that they can call gtk_widget_queue_resize() instead of gtk_widget_queue_draw()). Normally, gtk_widget_size_request() should be used. The #GtkRequisition cache on the widget was removed, If you need to cache sizes across requests and allocations, add an explicit cache to the widget in question instead. a #GtkWidget a pointer to a #GtkRequisition to copy to Get the root window where this widget is located. This function can only be called after the widget has been added to a widget hierarchy with #GtkWindow at the top. The root window is useful for such purposes as creating a popup #GdkWindow associated with the window. In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. Use gdk_screen_get_root_window() instead the #GdkWindow root window for the toplevel for this widget. a #GtkWidget 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_window_get_scale_factor(). the scale factor for @widget a #GtkWidget Get the #GdkScreen 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 #GtkWindow 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. the #GdkScreen for the toplevel for this widget. a #GtkWidget Returns the widget’s sensitivity (in the sense of returning the value that has been set using gtk_widget_set_sensitive()). The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See gtk_widget_is_sensitive(). %TRUE if the widget is sensitive a #GtkWidget Gets the settings object holding the settings used for this widget. Note that this function can only be called when the #GtkWidget is attached to a toplevel, since the settings object is specific to a particular #GdkScreen. the relevant #GtkSettings object a #GtkWidget Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request(). A value of -1 stored in @width or @height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See gtk_widget_set_size_request(). To get the size a widget will actually request, call gtk_widget_get_preferred_size() instead of this function. a #GtkWidget return location for width, or %NULL return location for height, or %NULL Returns the widget’s state. See gtk_widget_set_state(). Use gtk_widget_get_state_flags() instead. the state of @widget. a #GtkWidget Returns the widget state as a flag set. It is worth mentioning that the effective %GTK_STATE_FLAG_INSENSITIVE state will be returned, that is, also based on parent insensitivity, even if @widget itself is sensitive. Also note that if you are looking for a way to obtain the #GtkStateFlags to pass to a #GtkStyleContext method, you should look at gtk_style_context_get_state(). The state flags for widget a #GtkWidget Simply an accessor function that returns @widget->style. Use #GtkStyleContext instead the widget’s #GtkStyle a #GtkWidget Returns the style context associated to @widget. The returned object is guaranteed to be the same for the lifetime of @widget. a #GtkStyleContext. This memory is owned by @widget and must not be freed. a #GtkWidget Returns %TRUE if @widget is multiple pointer aware. See gtk_widget_set_support_multidevice() for more information. %TRUE if @widget is multidevice aware. a #GtkWidget Fetch an object build from the template XML for @widget_type in this @widget instance. This will only report children which were previously declared with gtk_widget_class_bind_template_child_full() or one of its variants. This function is only meant to be called for code which is private to the @widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets. The object built in the template XML with the id @name A #GtkWidget The #GType to get a template child for The “id” of the child defined in the template XML Gets the contents of the tooltip for @widget. the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkWidget Gets the contents of the tooltip for @widget. the tooltip text, or %NULL. You should free the returned string with g_free() when done. a #GtkWidget Returns the #GtkWindow of the current tooltip. This can be the GtkWindow created by default, or the custom tooltip window set using gtk_widget_set_tooltip_window(). The #GtkWindow of the current tooltip. a #GtkWidget This function returns the topmost widget in the container hierarchy @widget is a part of. If @widget has no parent widgets, it will be returned as the topmost widget. No reference will be added to the returned widget; it should not be unreferenced. Note the difference in behavior vs. gtk_widget_get_ancestor(); `gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)` would return %NULL if @widget wasn’t inside a toplevel window, and if the window was inside a #GtkWindow-derived widget which was in turn inside the toplevel #GtkWindow. While the second case may seem unlikely, it actually happens when a #GtkPlug is embedded inside a #GtkSocket within the same application. To reliably find the toplevel #GtkWindow, use gtk_widget_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: |[<!-- language="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; } ]| the topmost ancestor of @widget, or @widget itself if there’s no ancestor. a #GtkWidget Gets the value of the #GtkWidget:valign property. For backwards compatibility reasons this method will never return %GTK_ALIGN_BASELINE, but instead it will convert it to %GTK_ALIGN_FILL. If your widget want to support baseline aligned children it must use gtk_widget_get_valign_with_baseline(), or `g_object_get (widget, "valign", &value, NULL)`, which will also report the true value. the vertical alignment of @widget, ignoring baseline alignment a #GtkWidget Gets the value of the #GtkWidget:valign property, including %GTK_ALIGN_BASELINE. the vertical alignment of @widget a #GtkWidget Gets whether the widget would like any available extra vertical space. See gtk_widget_get_hexpand() for more detail. whether vexpand flag is set the widget Gets whether gtk_widget_set_vexpand() has been used to explicitly set the expand flag on this widget. See gtk_widget_get_hexpand_set() for more detail. whether vexpand has been explicitly set the widget Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use gtk_widget_is_visible() instead. This function does not check if the widget is obscured in any way. See gtk_widget_set_visible(). %TRUE if the widget is visible a #GtkWidget Gets the visual that will be used to render @widget. the visual for @widget a #GtkWidget Returns the widget’s window if it is realized, %NULL otherwise @widget’s window. a #GtkWidget Makes @widget 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 @widget is not sensitive, it is not set as the current grabbed widget and this function does nothing. The widget that grabs keyboard and pointer events Causes @widget to become the default widget. @widget must be able to be a default widget; typically you would ensure this yourself by calling gtk_widget_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, gtk_widget_activate() should affect them. Note that #GtkEntry widgets require the “activates-default” property set to %TRUE before they activate the default widget when Enter is pressed and the #GtkEntry is focused. a #GtkWidget Causes @widget to have the keyboard focus for the #GtkWindow it's inside. @widget must be a focusable widget, such as a #GtkEntry; something like #GtkFrame won’t work. More precisely, it must have the %GTK_CAN_FOCUS flag set. Use gtk_widget_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. a #GtkWidget Removes the grab from the given widget. You have to pair calls to gtk_grab_add() and gtk_grab_remove(). If @widget does not have the grab, this function does nothing. The widget which gives up the grab Determines whether @widget is the current default widget within its toplevel. See gtk_widget_set_can_default(). %TRUE if @widget is the current default widget within its toplevel, %FALSE otherwise a #GtkWidget Determines if the widget has the global input focus. See gtk_widget_is_focus() for the difference between having the global input focus, and only having the focus within a toplevel. %TRUE if the widget has the global input focus. a #GtkWidget Determines whether the widget is currently grabbing events, so it is the only widget receiving input events (keyboard and mouse). See also gtk_grab_add(). %TRUE if the widget is in the grab_widgets stack a #GtkWidget Determines if the widget style has been looked up through the rc mechanism. Use #GtkStyleContext instead %TRUE if the widget has been looked up through the rc mechanism, %FALSE otherwise. a #GtkWidget Checks whether there is a #GdkScreen 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. %TRUE if there is a #GdkScreen associated with the widget. a #GtkWidget 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 @widget. See gtk_window_get_focus_visible() for more information about focus indication. To find out if the widget has the global input focus, use gtk_widget_has_focus(). %TRUE if the widget should display a “focus rectangle” a #GtkWidget Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user). a #GtkWidget Utility function; intended to be connected to the #GtkWidget::delete-event signal on a #GtkWindow. The function calls gtk_widget_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. %TRUE a #GtkWidget Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work. %TRUE if @widget is being destroyed a #GtkWidget Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using gtk_widget_class_set_template() It is important to call this function in the instance initializer of a #GtkWidget subclass and not in #GObject.constructed() or #GObject.constructor() for two reasons. One reason is that generally derived widgets will assume that parent class composite widgets have been created in their instance initializers. Another reason is that when calling g_object_new() on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to g_object_new() should take precedence over properties set in the private template XML. a #GtkWidget Sets an input shape for this widget’s GDK window. This allows for windows which react to mouse click in a nonrectangular region, see gdk_window_input_shape_combine_region() for more information. a #GtkWidget shape to be added, or %NULL to remove an existing shape Inserts @group into @widget. Children of @widget that implement #GtkActionable can then be associated with actions in @group by setting their “action-name” to @prefix.`action-name`. If @group is %NULL, a previously inserted group for @name is removed from @widget. a #GtkWidget the prefix for actions in @group a #GActionGroup, or %NULL Computes the intersection of a @widget’s area and @area, storing the intersection in @intersection, and returns %TRUE if there was an intersection. @intersection may be %NULL if you’re only interested in whether there was an intersection. %TRUE if there was an intersection a #GtkWidget a rectangle rectangle to store intersection of @widget and @area Determines whether @widget is somewhere inside @ancestor, possibly with intermediate containers. %TRUE if @ancestor contains @widget as a child, grandchild, great grandchild, etc. a #GtkWidget another #GtkWidget Whether @widget can rely on having its alpha channel drawn correctly. On X11 this function returns whether a compositing manager is running for @widget’s screen. 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_window_set_composited()). Use gdk_screen_is_composited() instead. %TRUE if the widget can rely on its alpha channel being drawn correctly. a #GtkWidget Determines whether @widget can be drawn to. A widget can be drawn to if it is mapped and visible. %TRUE if @widget is drawable, %FALSE otherwise a #GtkWidget Determines if the widget is the focus widget within its toplevel. (This does not mean that the #GtkWidget:has-focus property is necessarily set; #GtkWidget:has-focus will only be set if the toplevel widget additionally has the global input focus.) %TRUE if the widget is the focus widget. a #GtkWidget Returns the widget’s effective sensitivity, which means it is sensitive itself and also its parent widget is sensitive %TRUE if the widget is effectively sensitive a #GtkWidget Determines whether @widget is a toplevel widget. Currently only #GtkWindow and #GtkInvisible (and out-of-process #GtkPlugs) are toplevel widgets. Toplevel widgets have no parent widget. %TRUE if @widget is a toplevel, %FALSE otherwise a #GtkWidget Determines whether the widget and all its parents are marked as visible. This function does not check if the widget is obscured in any way. See also gtk_widget_get_visible() and gtk_widget_set_visible() %TRUE if the widget and all its parents are visible a #GtkWidget This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the #GtkWidget::keynav-failed signal on the widget and its return value should be interpreted in a way similar to the return value of gtk_widget_child_focus(): When %TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When %FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling gtk_widget_child_focus() on the widget’s toplevel. The default ::keynav-failed handler returns %FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of #GtkDirectionType it returns %TRUE. Whenever the default handler returns %TRUE, it also calls gtk_widget_error_bell() to notify the user of the failed keyboard navigation. A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of #GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. %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). a #GtkWidget direction of focus movement Lists the closures used by @widget for accelerator group connections with gtk_accel_group_connect_by_path() or gtk_accel_group_connect(). The closures can be used to monitor accelerator changes on @widget, by connecting to the @GtkAccelGroup::accel-changed signal of the #GtkAccelGroup of a closure which can be found out with gtk_accel_group_from_accel_closure(). a newly allocated #GList of closures widget to list accelerator closures for Retrieves a %NULL-terminated array of strings containing the prefixes of #GActionGroup's available to @widget. a %NULL-terminated array of strings. A #GtkWidget Returns a newly allocated list of the widgets, normally labels, for which this widget is the target of a mnemonic (see for example, gtk_label_set_mnemonic_widget()). The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. the list of mnemonic labels; free this list with g_list_free() when you are done with it. a #GtkWidget This function is only for use in widget implementations. Causes a widget to be mapped if it isn’t already. a #GtkWidget Emits the #GtkWidget::mnemonic-activate signal. %TRUE if the signal has been handled a #GtkWidget %TRUE if there are other widgets with the same mnemonic Sets the base color for a widget in a particular state. All other style values are left untouched. The base color is the background color used along with the text color (see gtk_widget_modify_text()) for widgets such as #GtkEntry and #GtkTextView. See also gtk_widget_modify_style(). > Note that “no window” widgets (which have the %GTK_NO_WINDOW > flag set) draw on their parent container’s window and thus may > not draw any background themselves. This is the case for e.g. > #GtkLabel. > > To modify the background of such widgets, you have to set the > base color on their parent; if you want to set the background > of a rectangular area around a label, try placing the label in > a #GtkEventBox widget and setting the base color on that. Use gtk_widget_override_background_color() instead a #GtkWidget the state for which to set the base color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_base(). Sets the background color for a widget in a particular state. All other style values are left untouched. See also gtk_widget_modify_style(). > Note that “no window” widgets (which have the %GTK_NO_WINDOW > flag set) draw on their parent container’s window and thus may > not draw any background themselves. This is the case for e.g. > #GtkLabel. > > To modify the background of such widgets, you have to set the > background color on their parent; if you want to set the background > of a rectangular area around a label, try placing the label in > a #GtkEventBox widget and setting the background color on that. Use gtk_widget_override_background_color() instead a #GtkWidget the state for which to set the background color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_bg(). Sets the cursor color to use in a widget, overriding the #GtkWidget cursor-color and secondary-cursor-color style properties. All other style values are left untouched. See also gtk_widget_modify_style(). Use gtk_widget_override_cursor() instead. a #GtkWidget the color to use for primary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_cursor(). the color to use for secondary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_cursor(). Sets the foreground color for a widget in a particular state. All other style values are left untouched. See also gtk_widget_modify_style(). Use gtk_widget_override_color() instead a #GtkWidget the state for which to set the foreground color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_fg(). Sets the font to use for a widget. All other style values are left untouched. See also gtk_widget_modify_style(). Use gtk_widget_override_font() instead a #GtkWidget the font description to use, or %NULL to undo the effect of previous calls to gtk_widget_modify_font() Modifies style values on the widget. Modifications made using this technique take precedence over style values set via an RC file, however, they will be overridden if a style is explicitly set on the widget using gtk_widget_set_style(). The #GtkRcStyle-struct is designed so each field can either be set or unset, so it is possible, using this function, to modify some style values and leave the others unchanged. Note that modifications made with this function are not cumulative with previous calls to gtk_widget_modify_style() or with such functions as gtk_widget_modify_fg(). If you wish to retain previous values, you must first call gtk_widget_get_modifier_style(), make your modifications to the returned style, then call gtk_widget_modify_style() with that style. On the other hand, if you first call gtk_widget_modify_style(), subsequent calls to such functions gtk_widget_modify_fg() will have a cumulative effect with the initial modifications. Use #GtkStyleContext with a custom #GtkStyleProvider instead a #GtkWidget the #GtkRcStyle-struct holding the style modifications Sets the text color for a widget in a particular state. All other style values are left untouched. The text color is the foreground color used along with the base color (see gtk_widget_modify_base()) for widgets such as #GtkEntry and #GtkTextView. See also gtk_widget_modify_style(). Use gtk_widget_override_color() instead a #GtkWidget the state for which to set the text color the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_modify_text(). Sets the background color to use for a widget. All other style values are left untouched. See gtk_widget_override_color(). 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 #GtkStyleProvider and a CSS style class. You can also override the default drawing of a widget through the #GtkWidget::draw signal, and use Cairo to draw a specific color, regardless of the CSS style. a #GtkWidget the state for which to set the background color the color to assign, or %NULL to undo the effect of previous calls to gtk_widget_override_background_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 gtk_style_context_add_class(). This way, your widget library can install a #GtkCssProvider 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 #GtkCssProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority. Use a custom style provider and style classes instead a #GtkWidget the state for which to set the color the color to assign, or %NULL to undo the effect of previous calls to gtk_widget_override_color() 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 gtk_widget_modify_style(). Note that the underlying properties have the #GdkColor type, so the alpha value in @primary and @secondary will be ignored. 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 #GtkStyleProvider and a CSS style class. a #GtkWidget the color to use for primary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_override_cursor(). the color to use for secondary cursor (does not need to be allocated), or %NULL to undo the effect of previous calls to of gtk_widget_override_cursor(). Sets the font to use for a widget. All other style values are left untouched. See gtk_widget_override_color(). 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 #GtkStyleProvider and a CSS style class. a #GtkWidget the font description to use, or %NULL to undo the effect of previous calls to gtk_widget_override_font() Sets a symbolic color for a widget. All other style values are left untouched. See gtk_widget_override_color() for overriding the foreground or background color. 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 #GtkStyleProvider and a CSS style class. a #GtkWidget the name of the symbolic color to modify the color to assign (does not need to be allocated), or %NULL to undo the effect of previous calls to gtk_widget_override_symbolic_color() Obtains the full path to @widget. The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. The name of a widget comes from gtk_widget_get_name(). Paths are used to apply styles to a widget in gtkrc configuration files. Widget names are the type of the widget by default (e.g. “GtkButton”) or can be set to an application-specific value with gtk_widget_set_name(). By setting the name of a widget, you allow users or theme authors to apply styles to that specific widget in their gtkrc file. @path_reversed_p fills in the path in reverse order, i.e. starting with @widget’s name instead of starting with the name of @widget’s outermost ancestor. Use gtk_widget_get_path() instead a #GtkWidget location to store length of the path, or %NULL location to store allocated path string, or %NULL location to store allocated reverse path string, or %NULL This function is only for use in widget implementations. Flags the widget for a rerun of the GtkWidgetClass::size_allocate function. Use this function instead of gtk_widget_queue_resize() when the @widget's size request didn't change but it wants to reposition its contents. An example user of this function is gtk_widget_set_halign(). a #GtkWidget Mark @widget as needing to recompute its expand flags. Call this function when setting legacy expand child properties on the child of a container. See gtk_widget_compute_expand(). a #GtkWidget Equivalent to calling gtk_widget_queue_draw_area() for the entire area of a widget. a #GtkWidget Convenience function that calls gtk_widget_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 @widget->window coordinates for widgets that return %TRUE for gtk_widget_get_has_window(), and are relative to @widget->allocation.x, @widget->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. a #GtkWidget x coordinate of upper-left corner of rectangle to redraw y coordinate of upper-left corner of rectangle to redraw width of region to draw height of region to draw Invalidates the area of @widget defined by @region by calling gdk_window_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 #GtkDrawingArea or some portion thereof. a #GtkWidget region to draw This function is only for use in widget implementations. Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size request. For example, when you change the text in a #GtkLabel, #GtkLabel queues a resize to ensure there’s enough space for the new text. Note that you cannot call gtk_widget_queue_resize() on a widget from inside its implementation of the GtkWidgetClass::size_allocate virtual method. Calls to gtk_widget_queue_resize() from inside GtkWidgetClass::size_allocate will be silently ignored. a #GtkWidget This function works like gtk_widget_queue_resize(), except that the widget is not invalidated. a #GtkWidget Creates the GDK (windowing system) resources associated with a widget. For example, @widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling gtk_widget_realize() realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as #GtkWidget::draw. Or simply g_signal_connect () to the #GtkWidget::realize signal. a #GtkWidget Computes the intersection of a @widget’s area and @region, returning the intersection. The result may be empty, use cairo_region_is_empty() to check. Use gtk_widget_get_allocation() and cairo_region_intersect_rectangle() to get the same behavior. A newly allocated region holding the intersection of @widget and @region. a #GtkWidget a #cairo_region_t, in the same coordinate system as @widget->allocation. That is, relative to @widget->window for widgets which return %FALSE from gtk_widget_get_has_window(); relative to the parent window of @widget->window otherwise. Registers a #GdkWindow with the widget and sets it up so that the widget receives events for it. Call gtk_widget_unregister_window() when destroying the window. Before 3.8 you needed to call gdk_window_set_user_data() directly to set this up. This is now deprecated and you should use gtk_widget_register_window() instead. Old code will keep working as is, although some new features like transparency might not work perfectly. a #GtkWidget a #GdkWindow Removes an accelerator from @widget, previously installed with gtk_widget_add_accelerator(). whether an accelerator was installed and could be removed widget to install an accelerator on accel group for this widget GDK keyval of the accelerator modifier key combination of the accelerator Removes a widget from the list of mnemonic labels for this widget. (See gtk_widget_list_mnemonic_labels()). The widget must have previously been added to the list with gtk_widget_add_mnemonic_label(). a #GtkWidget a #GtkWidget that was previously set as a mnemonic label for @widget with gtk_widget_add_mnemonic_label(). Removes a tick callback previously registered with gtk_widget_add_tick_callback(). a #GtkWidget an id returned by gtk_widget_add_tick_callback() A convenience function that uses the theme settings for @widget to look up @stock_id and render it to a pixbuf. @stock_id should be a stock icon ID such as #GTK_STOCK_OPEN or #GTK_STOCK_OK. @size should be a size such as #GTK_ICON_SIZE_MENU. @detail should be a string that identifies the widget or code doing the rendering, so that theme engines can special-case rendering for that widget or code. The pixels in the returned #GdkPixbuf are shared with the rest of the application and should not be modified. The pixbuf should be freed after use with g_object_unref(). Use gtk_widget_render_icon_pixbuf() instead. a new pixbuf, or %NULL if the stock ID wasn’t known a #GtkWidget a stock ID a stock size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale (if there are multiple source sizes, GTK+ picks one of the available sizes). render detail to pass to theme engine A convenience function that uses the theme engine and style settings for @widget to look up @stock_id and render it to a pixbuf. @stock_id should be a stock icon ID such as #GTK_STOCK_OPEN or #GTK_STOCK_OK. @size should be a size such as #GTK_ICON_SIZE_MENU. The pixels in the returned #GdkPixbuf are shared with the rest of the application and should not be modified. The pixbuf should be freed after use with g_object_unref(). Use gtk_icon_theme_load_icon() instead. a new pixbuf, or %NULL if the stock ID wasn’t known a #GtkWidget a stock ID a stock size (#GtkIconSize). A size of `(GtkIconSize)-1` means render at the size of the source and don’t scale (if there are multiple source sizes, GTK+ picks one of the available sizes). Moves a widget from one #GtkContainer to another, handling reference count issues to avoid destroying the widget. Use gtk_container_remove() and gtk_container_add(). a #GtkWidget a #GtkContainer to move the widget into Reset the styles of @widget and all descendents, so when they are looked up again, they get the correct values for the currently loaded RC file settings. This function is not useful for applications. Use #GtkStyleContext instead, and gtk_widget_reset_style() a #GtkWidget. Updates the style context of @widget 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 gtk_container_get_path_for_child(). a #GtkWidget 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 (gtk_widget_get_has_window() is %FALSE), and that is normally done using gtk_container_propagate_draw(). If you want to force an area of a window to be redrawn, use gdk_window_invalidate_rect() or gdk_window_invalidate_region(). To cause the redraw to be done immediately, follow that call with a call to gdk_window_process_updates(). Application and widget code should not handle expose events directly; invalidation should use the #GtkWidget API, and drawing should only happen inside #GtkWidget::draw implementations return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a expose #GdkEvent Sends the focus change @event to @widget This function is not meant to be used by applications. The only time it should be used is when it is necessary for a #GtkWidget 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 #GtkTreeView. An example of its usage is: |[<!-- language="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); ]| the return value from the event signal emission: %TRUE if the event was handled, and %FALSE otherwise a #GtkWidget a #GdkEvent of type GDK_FOCUS_CHANGE Given an accelerator group, @accel_group, and an accelerator path, @accel_path, sets up an accelerator in @accel_group so whenever the key binding that is defined for @accel_path is pressed, @widget will be activated. This removes any accelerators (for any accelerator group) installed by previous calls to gtk_widget_set_accel_path(). Associating accelerators with paths allows them to be modified by the user and the modifications to be saved for future use. (See gtk_accel_map_save().) This function is a low level function that would most likely be used by a menu creation system like #GtkUIManager. If you use #GtkUIManager, setting up accelerator paths will be done automatically. Even when you you aren’t using #GtkUIManager, if you only want to set up accelerators on menu items gtk_menu_item_set_accel_path() provides a somewhat more convenient interface. Note that @accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string(). a #GtkWidget path used to look up the accelerator a #GtkAccelGroup. 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 #GtkContainer, you want to use gtk_widget_size_allocate() instead of gtk_widget_set_allocation(). The GtkWidgetClass::adjust_size_allocation virtual method adjusts the allocation inside gtk_widget_size_allocate() to create an adjusted allocation. a #GtkWidget a pointer to a #GtkAllocation to copy from Sets whether the application intends to draw on the widget in an #GtkWidget::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 #GtkEventBox and #GtkWindow, 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. a #GtkWidget %TRUE if the application will paint on the widget Specifies whether @widget can be a default widget. See gtk_widget_grab_default() for details about the meaning of “default”. a #GtkWidget whether or not @widget can be a default widget. Specifies whether @widget can own the input focus. See gtk_widget_grab_focus() for actually setting the input focus on a widget. a #GtkWidget whether or not @widget can own the input focus. Sets whether @widget should be mapped along with its when its parent is mapped and @widget has been shown with gtk_widget_show(). The child visibility can be set for widget before it is added to a container with gtk_widget_set_parent(), to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of %TRUE when the widget is removed from a container. Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. This function is only useful for container implementations and never should be called by an application. a #GtkWidget if %TRUE, @widget should be mapped along with its parent. 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 gtk_widget_set_allocation() (or after chaining up to the parent class), because that function resets the clip. The clip set should be the area that @widget draws on. If @widget is a #GtkContainer, the area must contain all children's clips. If this function is not called by @widget during a ::size-allocate handler, the clip will be set to @widget's allocation. a #GtkWidget a pointer to a #GtkAllocation to copy from Sets a widgets composite name. The widget must be a composite child of its parent; see gtk_widget_push_composite_child(). Use gtk_widget_class_set_template(), or don’t use this API at all. a #GtkWidget. the name to set Enables or disables a #GdkDevice to interact with @widget and all its children. It does so by descending through the #GdkWindow hierarchy and enabling the same mask that is has for core events (i.e. the one that gdk_window_get_events() returns). a #GtkWidget a #GdkDevice whether to enable the device Sets the device event mask (see #GdkEventMask) 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 gtk_widget_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 gtk_widget_get_has_window()); to get events on those widgets, place them inside a #GtkEventBox and receive events on the event box. a #GtkWidget a #GdkDevice event mask Sets the reading direction on a particular widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitly visual rather than logical (such as buttons for text justification). If the direction is set to %GTK_TEXT_DIR_NONE, then the value set by gtk_widget_set_default_direction() will be used. a #GtkWidget the new direction Widgets are double buffered by default; you can use this function to turn off the buffering. “Double buffered” simply means that gdk_window_begin_draw_frame() and gdk_window_end_draw_frame() are called automatically around expose events sent to the widget. gdk_window_begin_draw_frame() diverts all drawing to a widget's window to an offscreen buffer, and gdk_window_end_draw_frame() draws the buffer to the screen. The result is that users see the window update in one smooth step, and don’t see individual graphics primitives being rendered. In very simple terms, double buffered widgets don’t flicker, so you would only use this function to turn off double buffering if you had special needs and really knew what you were doing. Note: if you turn off double-buffering, you have to handle expose events, since even the clearing to the background color or pixmap will not happen automatically (as it is done in gdk_window_begin_draw_frame()). In 3.10 GTK and GDK have been restructured for translucent drawing. Since then expose events for double-buffered widgets are culled into a single event to the toplevel GDK window. If you now unset double buffering, you will cause a separate rendering pass for every widget. This will likely cause rendering problems - in particular related to stacking - and usually increases rendering times significantly. This function does not work under non-X11 backends or with non-native windows. It should not be used in newly written code. a #GtkWidget %TRUE to double-buffer a widget Sets the event mask (see #GdkEventMask) for a widget. The event mask determines which events a widget will receive. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget’s functionality, so be careful. This function must be called while a widget is unrealized. Consider gtk_widget_add_events() for widgets that are already realized, or if you want to preserve the existing event mask. This function can’t be used with widgets that have no window. (See gtk_widget_get_has_window()). To get events on those widgets, place them inside a #GtkEventBox and receive events on the event box. a #GtkWidget event mask 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. a #GtkWidget whether the widget should grab focus when clicked with the mouse Sets the font map to use for Pango rendering. When not set, the widget will inherit the font map from its parent. a #GtkWidget a #PangoFontMap, or %NULL to unset any previously set font map Sets the #cairo_font_options_t used for Pango rendering in this widget. When not set, the default font options for the #GdkScreen will be used. a #GtkWidget a #cairo_font_options_t, or %NULL to unset any previously set default font options. Sets the horizontal alignment of @widget. See the #GtkWidget:halign property. a #GtkWidget the horizontal alignment Sets the has-tooltip property on @widget to @has_tooltip. See #GtkWidget:has-tooltip for more information. a #GtkWidget whether or not @widget has a tooltip. Specifies whether @widget has a #GdkWindow of its own. Note that all realized widgets have a non-%NULL “window” pointer (gtk_widget_get_window() never returns a %NULL window when a widget is realized), but for many of them it’s actually the #GdkWindow of one of its parent widgets. Widgets that do not create a %window for themselves in #GtkWidget::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. a #GtkWidget whether or not @widget has a window. Sets whether the widget would like any available extra horizontal space. When a user resizes a #GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room. By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call gtk_widget_compute_expand(). A container can decide how the expandability of children affects the expansion of the container by overriding the compute_expand virtual method on #GtkWidget.). Setting hexpand explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, regardless of children. The override occurs because gtk_widget_set_hexpand() sets the hexpand-set property (see gtk_widget_set_hexpand_set()) which causes the widget’s hexpand value to be used, rather than looking at children and widget state. the widget whether to expand Sets whether the hexpand flag (see gtk_widget_get_hexpand()) will be used. The hexpand-set property will be set automatically when you call gtk_widget_set_hexpand() to set hexpand, so the most likely reason to use this function would be to unset an explicit expand flag. If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. the widget value for hexpand-set property Marks the widget as being mapped. This function should only ever be called in a derived widget's “map” or “unmap” implementation. a #GtkWidget %TRUE to mark the widget as mapped Sets the bottom margin of @widget. See the #GtkWidget:margin-bottom property. a #GtkWidget the bottom margin Sets the end margin of @widget. See the #GtkWidget:margin-end property. a #GtkWidget the end margin Sets the left margin of @widget. See the #GtkWidget:margin-left property. Use gtk_widget_set_margin_start() instead. a #GtkWidget the left margin Sets the right margin of @widget. See the #GtkWidget:margin-right property. Use gtk_widget_set_margin_end() instead. a #GtkWidget the right margin Sets the start margin of @widget. See the #GtkWidget:margin-start property. a #GtkWidget the start margin Sets the top margin of @widget. See the #GtkWidget:margin-top property. a #GtkWidget the top margin Widgets can be named, which allows you to refer to them from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for #GtkStyleContext). Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice. a #GtkWidget name for the widget Sets the #GtkWidget:no-show-all property, which determines whether calls to gtk_widget_show_all() will affect this widget. This is mostly for use in constructing widget hierarchies with externally controlled visibility, see #GtkUIManager. a #GtkWidget the new value for the “no-show-all” property Request the @widget to be rendered partially transparent, with opacity 0 being fully transparent and 1 fully opaque. (Opacity values are clamped to the [0,1] range.). 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 gtk_widget_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. a #GtkWidget desired opacity, between 0 and 1 This function is useful only when implementing subclasses of #GtkContainer. Sets the container as the parent of @widget, and takes care of some details such as updating the state and style of the child to reflect its new location. The opposite function is gtk_widget_unparent(). a #GtkWidget parent container Sets a non default parent window for @widget. For #GtkWindow classes, setting a @parent_window effects whether the window is a toplevel window or can be embedded into other widgets. For #GtkWindow classes, this needs to be called before the window is realized. a #GtkWidget. the new parent window. Marks the widget as being realized. This function must only be called after all #GdkWindows for the @widget have been created and registered. This function should only ever be called in a derived widget's “realize” or “unrealize” implementation. a #GtkWidget %TRUE to mark the widget as realized Specifies whether @widget will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See gtk_widget_grab_default() for details about the meaning of “default”. a #GtkWidget whether or not @widget can be a default widget. 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 gtk_widget_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 @widget->window, you are responsible for invalidating both the old and new allocation of the widget when the widget is moved and responsible for invalidating regions newly when the widget increases size. a #GtkWidget 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. 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. a #GtkWidget %TRUE to make the widget sensitive Sets the minimum size of a widget; that is, the widget’s size request will be at least @width by @height. You can use this function to force a widget to be larger than it normally would be. In most cases, gtk_window_set_default_size() is a better choice for toplevel windows than this function; setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request. When dealing with window sizes, gtk_window_set_geometry_hints() can be a useful function as well. Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hardcode a size that will always be correct. The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested. If the size request in a given direction is -1 (unset), then the “natural” size request of the widget will be used instead. The size request set here does not include any margin from the #GtkWidget properties margin-left, margin-right, margin-top, and margin-bottom, but it does include pretty much all other padding or border properties set by any subclass of #GtkWidget. a #GtkWidget width @widget should request, or -1 to unset height @widget should request, or -1 to unset This function is for use in widget implementations. Sets the state of a widget (insensitive, prelighted, etc.) Usually you should set the state using wrapper functions such as gtk_widget_set_sensitive(). Use gtk_widget_set_state_flags() instead. a #GtkWidget new state for @widget This function is for use in widget implementations. Turns on flag values in the current widget state (insensitive, prelighted, etc.). This function accepts the values %GTK_STATE_FLAG_DIR_LTR and %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's direction, use gtk_widget_set_direction(). It is worth mentioning that any other state than %GTK_STATE_FLAG_INSENSITIVE, will be propagated down to all non-internal children if @widget is a #GtkContainer, while %GTK_STATE_FLAG_INSENSITIVE itself will be propagated down to all #GtkContainer children by different means than turning on the state flag down the hierarchy, both gtk_widget_get_state_flags() and gtk_widget_is_sensitive() will make use of these. a #GtkWidget State flags to turn on Whether to clear state before turning on @flags Used to set the #GtkStyle for a widget (@widget->style). Since GTK 3, this function does nothing, the passed in style is ignored. Use #GtkStyleContext instead a #GtkWidget a #GtkStyle, or %NULL to remove the effect of a previous call to gtk_widget_set_style() and go back to the default style Enables or disables multiple pointer awareness. If this setting is %TRUE, @widget will start receiving multiple, per device enter/leave events. Note that if custom #GdkWindows are created in #GtkWidget::realize, gdk_window_set_support_multidevice() will have to be called manually on them. a #GtkWidget %TRUE to support input from multiple devices. 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 #GtkWidget:has-tooltip to %TRUE and of the default handler for the #GtkWidget::query-tooltip signal. See also the #GtkWidget:tooltip-markup property and gtk_tooltip_set_markup(). a #GtkWidget the contents of the tooltip for @widget, or %NULL Sets @text as the contents of the tooltip. This function will take care of setting #GtkWidget:has-tooltip to %TRUE and of the default handler for the #GtkWidget::query-tooltip signal. See also the #GtkWidget:tooltip-text property and gtk_tooltip_set_text(). a #GtkWidget the contents of the tooltip for @widget 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 %NULL, the default tooltip window will be used. a #GtkWidget a #GtkWindow, or %NULL Sets the vertical alignment of @widget. See the #GtkWidget:valign property. a #GtkWidget the vertical alignment Sets whether the widget would like any available extra vertical space. See gtk_widget_set_hexpand() for more detail. the widget whether to expand Sets whether the vexpand flag (see gtk_widget_get_vexpand()) will be used. See gtk_widget_set_hexpand_set() for more detail. the widget value for vexpand-set property Sets the visibility state of @widget. Note that setting this to %TRUE doesn’t mean the widget is actually viewable, see gtk_widget_get_visible(). This function simply calls gtk_widget_show() or gtk_widget_hide() but is nicer to use when the visibility of the widget depends on some condition. a #GtkWidget whether the widget should be shown or not Sets the visual that should be used for by widget and its children for creating #GdkWindows. The visual must be on the same #GdkScreen as returned by gtk_widget_get_screen(), so handling the #GtkWidget::screen-changed signal is necessary. Setting a new @visual will not cause @widget to recreate its windows, so you should call this function before @widget is realized. a #GtkWidget visual to be used or %NULL to unset a previous one Sets a widget’s window. This function should only be used in a widget’s #GtkWidget::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 gtk_widget_get_parent_window(). Widgets must indicate whether they will create their own #GdkWindow by calling gtk_widget_set_has_window(). This is usually done in the widget’s init() function. Note that this function does not add any reference to @window. a #GtkWidget a #GdkWindow Sets a shape for this widget’s GDK window. This allows for transparent windows etc., see gdk_window_shape_combine_region() for more information. a #GtkWidget shape to be added, or %NULL to remove an existing shape Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. If you want to show all the widgets in a container, it’s easier to call gtk_widget_show_all() on the container, instead of individually showing the widgets. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped. a #GtkWidget Recursively shows a widget, and any child widgets (if the widget is a container). a #GtkWidget Shows a widget. If the widget is an unmapped toplevel widget (i.e. a #GtkWindow 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. a #GtkWidget This function is only used by #GtkContainer 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 #GtkWidget:halign and #GtkWidget:valign properties. For baseline support in containers you need to use gtk_widget_size_allocate_with_baseline() instead. a #GtkWidget position and size to be allocated to @widget This function is only used by #GtkContainer 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 #GtkWidget:halign and #GtkWidget:valign properties. If the child widget does not have a valign of %GTK_ALIGN_BASELINE the baseline argument is ignored and -1 is used instead. a #GtkWidget position and size to be allocated to @widget The baseline of the child, or -1 This function is typically used when implementing a #GtkContainer subclass. Obtains the preferred size of a widget. The container uses this information to arrange its child widgets and decide what size allocations to give them with gtk_widget_size_allocate(). You can also call this function from an application, with some caveats. Most notably, getting a size request requires the widget to be associated with a screen, because font information may be needed. Multihead-aware applications should keep this in mind. Also remember that the size request is not necessarily the size a widget will actually be allocated. Use gtk_widget_get_preferred_size() instead. a #GtkWidget a #GtkRequisition to be filled in This function attaches the widget’s #GtkStyle to the widget's #GdkWindow. It is a replacement for |[ widget->style = gtk_style_attach (widget->style, widget->window); ]| and should only ever be called in a derived widget’s “realize” implementation which does not chain up to its parent class' “realize” implementation, because one of the parent classes (finally #GtkWidget) would attach the style itself. This step is unnecessary with #GtkStyleContext. a #GtkWidget Gets the values of a multiple style properties of @widget. a #GtkWidget the name of the first property to get pairs of property names and locations to return the property values, starting with the location for @first_property_name, terminated by %NULL. Gets the value of a style property of @widget. a #GtkWidget the name of a style property location to return the property value Non-vararg variant of gtk_widget_style_get(). Used primarily by language bindings. a #GtkWidget the name of the first property to get a va_list of pairs of property names and locations to return the property values, starting with the location for @first_property_name. Reverts the effect of a previous call to gtk_widget_freeze_child_notify(). This causes all queued #GtkWidget::child-notify signals on @widget to be emitted. a #GtkWidget Translate coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations. In order to perform this operation, both widgets must be realized, and must share a common toplevel. %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. a #GtkWidget a #GtkWidget X position relative to @src_widget Y position relative to @src_widget location to store X position relative to @dest_widget location to store Y position relative to @dest_widget Triggers a tooltip query on the display where the toplevel of @widget is located. See gtk_tooltip_trigger_tooltip_query() for more information. a #GtkWidget This function is only for use in widget implementations. Causes a widget to be unmapped if it’s currently mapped. a #GtkWidget This function is only for use in widget implementations. Should be called by implementations of the remove method on #GtkContainer, to dissociate a child from the container. a #GtkWidget This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as @widget->window). a #GtkWidget Unregisters a #GdkWindow from the widget that was previously set up with gtk_widget_register_window(). You need to call this when the window is no longer used by the widget, such as when you destroy it. a #GtkWidget a #GdkWindow This function is for use in widget implementations. Turns off flag values for the current widget state (insensitive, prelighted, etc.). See gtk_widget_set_state_flags(). a #GtkWidget State flags to turn off Whether the widget is double buffered. Widgets should not use this property. Whether to expand in both directions. Setting this sets both #GtkWidget:hexpand and #GtkWidget:vexpand 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 (GtkButton, GtkFileChooserButton, GtkComboBox) implemented this property individually. How to distribute horizontal space if widget gets extra space, see #GtkAlign Enables or disables the emission of #GtkWidget::query-tooltip on @widget. A value of %TRUE indicates that @widget can have a tooltip, in this case the widget will be queried using #GtkWidget::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. Whether to expand horizontally. See gtk_widget_set_hexpand(). Whether to use the #GtkWidget:hexpand property. See gtk_widget_get_hexpand_set(). Sets all four sides' margin at once. If read, returns max margin on any side. Margin on bottom side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Margin on left side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Use #GtkWidget:margin-start instead. Margin on right side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Use #GtkWidget:margin-end instead. Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. Margin on top side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example. The requested opacity of the widget. See gtk_widget_set_opacity() for more details about window opacity. Before 3.8 this was only available in GtkWindow The scale factor of the widget. See gtk_widget_get_scale_factor() for more details about widget scaling. The style of the widget, which contains information about how it will look (colors, etc). Use #GtkStyleContext instead Sets the text of tooltip to be the given string, which is marked up with the [Pango text markup language][PangoMarkupFormat]. Also see gtk_tooltip_set_markup(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL: #GtkWidget:has-tooltip will automatically be set to %TRUE and there will be taken care of #GtkWidget::query-tooltip in the default signal handler. Note that if both #GtkWidget:tooltip-text and #GtkWidget:tooltip-markup are set, the last one wins. Sets the text of tooltip to be the given string. Also see gtk_tooltip_set_text(). This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL: #GtkWidget:has-tooltip will automatically be set to %TRUE and there will be taken care of #GtkWidget::query-tooltip in the default signal handler. Note that if both #GtkWidget:tooltip-text and #GtkWidget:tooltip-markup are set, the last one wins. How to distribute vertical space if widget gets extra space, see #GtkAlign Whether to expand vertically. See gtk_widget_set_vexpand(). Whether to use the #GtkWidget:vexpand property. See gtk_widget_get_vexpand_set(). The widget's window if it is realized, %NULL otherwise. The ::button-press-event signal will be emitted when a button (typically from a mouse) is pressed. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_BUTTON_PRESS_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal. The ::button-release-event signal will be emitted when a button (typically from a mouse) is released. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_BUTTON_RELEASE_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventButton which triggered this signal. 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 #GtkWidget handling for determining whether an accelerator can be activated. %TRUE if the signal can be activated. the ID of a signal installed on @widget 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. the #GParamSpec of the changed child property The ::composited-changed signal is emitted when the composited status of @widgets screen changes. See gdk_screen_is_composited(). Use GdkScreen::composited-changed instead. 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 #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventConfigure which triggered this signal. 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. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventExpose 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 gtk_widget_hide_on_delete() to this signal will cause the window to be hidden instead, so that it can later be shown again without reconstructing it. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the event which triggered this signal 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. The ::destroy-event signal is emitted when a #GdkWindow 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 #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the event which triggered this signal The ::direction-changed signal is emitted when the text direction of a widget changes. the previous text direction of @widget 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. gtk_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. the drag context The ::drag-data-delete signal is emitted on the drag source when a drag with the action %GDK_ACTION_MOVE is successfully completed. The signal handler is responsible for deleting the data that has been dropped. What "delete" means depends on the context of the drag operation. the drag context The ::drag-data-get signal is emitted on the drag source when the drop site requests the data which is dragged. It is the responsibility of the signal handler to fill @data with the data in the format which is indicated by @info. See gtk_selection_data_set() and gtk_selection_data_set_text(). the drag context the #GtkSelectionData to be filled with the dragged data the info that has been registered with the target in the #GtkTargetList the timestamp at which the data was requested 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 #GtkWidget::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_drag_context_get_selected_action() before calling gtk_drag_finish(), e.g. to implement %GDK_ACTION_ASK as shown in the following example: |[<!-- language="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); } ]| the drag context where the drop happened where the drop happened the received data the info that has been registered with the target in the #GtkTargetList the timestamp at which the data was received 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 #GtkWidget::drag-data-received handler which gets triggered by calling gtk_drag_get_data() to receive the data for one or more of the supported targets. whether the cursor position is in a drop zone the drag context the x coordinate of the current cursor position the y coordinate of the current cursor position the timestamp of the motion event 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 #GtkWidget::drag-begin. the drag context 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. %TRUE if the failed drag operation has been already handled. the drag context the result of the drag operation 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 #GtkWidget::drag-motion, e.g. undo highlighting with gtk_drag_unhighlight(). Likewise, the #GtkWidget::drag-leave signal is also emitted before the ::drag-drop signal, for instance to allow cleaning up of a preview item created in the #GtkWidget::drag-motion signal handler. the drag context the timestamp of the motion event 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 gtk_drag_get_data() and defer the gdk_drag_status() call to the #GtkWidget::drag-data-received handler. Note that you must pass #GTK_DEST_DEFAULT_DROP, #GTK_DEST_DEFAULT_MOTION or #GTK_DEST_DEFAULT_ALL to gtk_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 #GtkWidget::drag-leave and if not, treat the drag-motion signal as an "enter" signal. Upon an "enter", the handler will typically highlight the drop site with gtk_drag_highlight(). |[<!-- language="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 } } ]| whether the cursor position is in a drop zone the drag context the x coordinate of the current cursor position the y coordinate of the current cursor position the timestamp of the motion event 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 gtk_widget_get_allocated_width() and gtk_widget_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(). %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the cairo context to draw to The ::enter-notify-event will be emitted when the pointer enters the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_ENTER_NOTIFY_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventCrossing which triggered this signal. 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. #GtkWidget::key-press-event) and finally a generic #GtkWidget::event-after signal. %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. the #GdkEvent which triggered this signal After the emission of the #GtkWidget::event signal and (optionally) the second more specific signal, ::event-after will be emitted regardless of the previous two signals handlers return values. the #GdkEvent which triggered this signal %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. The ::focus-in-event signal will be emitted when the keyboard focus enters the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_FOCUS_CHANGE_MASK mask. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventFocus which triggered this signal. The ::focus-out-event signal will be emitted when the keyboard focus leaves the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_FOCUS_CHANGE_MASK mask. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventFocus which triggered this signal. 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. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventGrabBroken event The ::grab-notify signal is emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed. A widget is shadowed by a gtk_grab_add() when the topmost grab widget in the grab stack of its window group is not its ancestor. %FALSE if the widget becomes shadowed, %TRUE if it becomes unshadowed The ::hide signal is emitted when @widget is hidden, for example with gtk_widget_hide(). The ::hierarchy-changed signal is emitted when the anchored state of a widget changes. A widget is “anchored” when its toplevel ancestor is a #GtkWindow. This signal is emitted when a widget changes from un-anchored to anchored or vice-versa. the previous toplevel ancestor, or %NULL if the widget was previously unanchored 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 #GdkWindow associated to the widget needs to enable the #GDK_KEY_PRESS_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventKey which triggered this signal. The ::key-release-event signal is emitted when a key is released. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_KEY_RELEASE_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventKey which triggered this signal. Gets emitted if keyboard navigation fails. See gtk_widget_keynav_failed() for details. %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). the direction of movement The ::leave-notify-event will be emitted when the pointer leaves the @widget's window. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_LEAVE_NOTIFY_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventCrossing which triggered this signal. The ::map signal is emitted when @widget is going to be mapped, that is when the widget is visible (which is controlled with gtk_widget_set_visible()) and all its parents up to the toplevel widget are also visible. Once the map has occurred, #GtkWidget::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 #GtkWidget::unmap. 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 #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventAny which triggered this signal. The default handler for this signal activates @widget if @group_cycling is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. %TRUE if there are other widgets with the same mnemonic The ::motion-notify-event signal is emitted when the pointer moves over the widget's #GdkWindow. To receive this signal, the #GdkWindow associated to the widget needs to enable the #GDK_POINTER_MOTION_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventMotion which triggered this signal. The ::parent-set signal is emitted when a new parent has been set on a widget. the previous parent, or %NULL if the widget just got its initial parent. 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 #GtkEntry 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. %TRUE if a menu was activated 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 #GdkWindow associated to the widget needs to enable the #GDK_PROPERTY_CHANGE_MASK mask. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventProperty which triggered this signal. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_PROXIMITY_IN_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventProximity which triggered this signal. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_PROXIMITY_OUT_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventProximity which triggered this signal. Emitted when #GtkWidget: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. %TRUE if @tooltip should be shown right now, %FALSE otherwise. the x coordinate of the cursor position where the request has been emitted, relative to @widget's left side the y coordinate of the cursor position where the request has been emitted, relative to @widget's top %TRUE if the tooltip was triggered using the keyboard a #GtkTooltip The ::realize signal is emitted when @widget is associated with a #GdkWindow, which means that gtk_widget_realize() has been called or the widget has been mapped (that is, it is going to be drawn). The ::screen-changed signal gets emitted when the screen of a widget has changed. the previous screen, or %NULL if the widget was not associated with a screen before 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 #GdkWindow associated to the widget needs to enable the #GDK_SCROLL_MASK mask. This signal will be sent to the grab widget if there is one. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventScroll which triggered this signal. The ::selection-clear-event signal will be emitted when the the @widget's window has lost ownership of a selection. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventSelection which triggered this signal. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. The ::selection-request-event signal will be emitted when another client requests ownership of the selection owned by the @widget's window. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventSelection which triggered this signal. The ::show signal is emitted when @widget is shown, for example with gtk_widget_show(). %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the region which has been allocated to the widget. The ::state-changed signal is emitted when the widget state changes. See gtk_widget_get_state(). Use #GtkWidget::state-flags-changed instead. the previous state The ::state-flags-changed signal is emitted when the widget state changes, see gtk_widget_get_state_flags(). The previous state flags. The ::style-set signal is emitted when a new style has been set on a widget. Note that style-modifying functions like gtk_widget_modify_base() also cause this signal to be emitted. Note that this signal is emitted for changes to the deprecated #GtkStyle. To track changes to the #GtkStyleContext associated with a widget, use the #GtkWidget::style-updated signal. Use the #GtkWidget::style-updated signal the previous style, or %NULL if the widget just got its initial style The ::style-updated signal is a convenience signal that is emitted when the #GtkStyleContext::changed signal is emitted on the @widget's associated #GtkStyleContext as returned by gtk_widget_get_style_context(). Note that style-modifying functions like gtk_widget_override_color() also cause this signal to be emitted. 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. 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 #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventAny which triggered this signal The ::unrealize signal is emitted when the #GdkWindow associated with @widget is destroyed, which means that gtk_widget_unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden). The ::visibility-notify-event will be emitted when the @widget's window is obscured or unobscured. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_VISIBILITY_NOTIFY_MASK mask. Modern composited windowing systems with pervasive transparency make it impossible to track the visibility of a window reliably, so this signal can not be guaranteed to provide useful information. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventVisibility which triggered this signal. The ::window-state-event will be emitted when the state of the toplevel window associated to the @widget changes. To receive this signal the #GdkWindow associated to the widget needs to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the #GdkEventWindowState which triggered this signal. The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a GtkWidgetClass pointer to be cast to a GObjectClass pointer. The signal to emit when a widget of this class is activated, gtk_widget_activate() handles the emission. Implementation of this signal is optional. a #GtkWidget a #GtkWidget a #GtkWidget a #GtkWidget a #GtkWidget a #GtkWidget a #GtkWidget a #GtkWidget a #GtkWidget position and size to be allocated to @widget a #GtkWidget the name of a child property installed on the class of @widget’s parent The #GtkSizeRequestMode preferred by @widget. a #GtkWidget instance a #GtkWidget instance location to store the minimum height, or %NULL location to store the natural height, or %NULL a #GtkWidget instance the height which is available for allocation location for storing the minimum width, or %NULL location for storing the natural width, or %NULL a #GtkWidget instance location to store the minimum width, or %NULL location to store the natural width, or %NULL a #GtkWidget instance the width which is available for allocation location for storing the minimum height, or %NULL location for storing the natural height, or %NULL %TRUE if the signal has been handled a #GtkWidget %TRUE if there are other widgets with the same mnemonic a #GtkWidget %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). a #GtkWidget direction of focus movement return from the event signal emission (%TRUE if the event was handled) a #GtkWidget a #GdkEvent the #AtkObject associated with @widget a #GtkWidget %TRUE if the accelerator can be activated. a #GtkWidget the ID of a signal installed on @widget a #GtkWidget instance the width which is available for allocation, or -1 if none location for storing the minimum height, or %NULL location for storing the natural height, or %NULL location for storing the baseline for the minimum height, or %NULL location for storing the baseline for the natural height, or %NULL a #GtkWidget region to draw Declares a @callback_symbol to handle @callback_name from the template XML defined for @widget_type. See gtk_builder_add_callback_symbol(). Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template(). A #GtkWidgetClass The name of the callback as expected in the template XML The callback symbol Automatically assign an object declared in the class template XML to be set to a location on a freshly built instance’s private data, or alternatively accessible via gtk_widget_get_template_child(). The struct can point either into the public instance, then you should use G_STRUCT_OFFSET(WidgetType, member) for @struct_offset, or in the private struct, then you should use G_PRIVATE_OFFSET(WidgetType, member). An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when #GObjectClass.dispose() runs on your instance and if a @struct_offset that is != 0 is specified, then the automatic location in your instance public or private data will be set to %NULL. You can however access an automated child pointer the first time your classes #GObjectClass.dispose() runs, or alternatively in #GtkWidgetClass.destroy(). If @internal_child is specified, #GtkBuildableIface.get_internal_child() will be automatically implemented by the #GtkWidget class so there is no need to implement it manually. The wrapper macros gtk_widget_class_bind_template_child(), gtk_widget_class_bind_template_child_internal(), gtk_widget_class_bind_template_child_private() and gtk_widget_class_bind_template_child_internal_private() might be more convenient to use. Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template(). A #GtkWidgetClass The “id” of the child defined in the template XML Whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML The structure offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer. Finds a style property of a widget class by name. the #GParamSpec of the style property or %NULL if @class has no style property with that name. a #GtkWidgetClass the name of the style property to find Gets the name used by this class for matching in CSS code. See gtk_widget_class_set_css_name() for details. the CSS name of the given class class to set the name on Installs a style property on a widget class. The parser for the style property is determined by the value type of @pspec. a #GtkWidgetClass the #GParamSpec for the property Installs a style property on a widget class. a #GtkWidgetClass the #GParamSpec for the style property the parser for the style property Returns all style properties of a widget class. a newly allocated array of #GParamSpec*. The array must be freed with g_free(). a #GtkWidgetClass location to return the number of style properties found Sets the default #AtkRole to be set on accessibles created for widgets of @widget_class. Accessibles may decide to not honor this setting if their role reporting is more refined. Calls to gtk_widget_class_set_accessible_type() will reset this value. In cases where you want more fine-grained control over the role of accessibles created for @widget_class, you should provide your own accessible type and use gtk_widget_class_set_accessible_type() instead. If @role is #ATK_ROLE_INVALID, the default role will not be changed and the accessible’s default role will be used instead. This function should only be called from class init functions of widgets. class to set the accessible role for The role to use for accessibles created for @widget_class Sets the type to be used for creating accessibles for widgets of @widget_class. The given @type must be a subtype of the type used for accessibles of the parent class. This function should only be called from class init functions of widgets. class to set the accessible type for The object type that implements the accessible for @widget_class For use in language bindings, this will override the default #GtkBuilderConnectFunc to be used when parsing GtkBuilder XML from this class’s template data. Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template(). A #GtkWidgetClass The #GtkBuilderConnectFunc to use when connecting signals in the class template The data to pass to @connect_func The #GDestroyNotify to free @connect_data, this will only be used at class finalization time, when no classes of type @widget_type are in use anymore. Sets the name to be used for CSS matching of widgets. If this function is not called for a given class, the name of the parent class is used. class to set the name on name to use This should be called at class initialization time to specify the GtkBuilder XML to be used to extend a widget. For convenience, gtk_widget_class_set_template_from_resource() is also provided. Note that any class that installs templates must call gtk_widget_init_template() in the widget’s instance initializer. A #GtkWidgetClass A #GBytes holding the #GtkBuilder XML A convenience function to call gtk_widget_class_set_template(). Note that any class that installs templates must call gtk_widget_init_template() in the widget’s instance initializer. A #GtkWidgetClass The name of the resource to load the template from Kinds of widget-specific help. Used by the ::show-help signal. Tooltip. What’s this. GtkWidgetPath 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 #GtkStyleContext 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 gtk_widget_get_path(), and the style context returned by gtk_widget_get_style_context() will be automatically updated on widget hierarchy changes. The widget path generation is generally simple: ## Defining a button within a window |[<!-- language="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 |[<!-- language="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. Returns an empty widget path. A newly created, empty, #GtkWidgetPath Appends the data from @widget to the widget hierarchy represented by @path. This function is a shortcut for adding information from @widget to the given @path. This includes setting the name or adding the style classes from @widget. the position where the data was inserted a widget path the widget to append to the widget path Appends a widget type to the widget hierarchy represented by @path. the position where the element was inserted a #GtkWidgetPath widget type to append Appends a widget type with all its siblings to the widget hierarchy represented by @path. Using this function instead of gtk_widget_path_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 gtk_widget_reset_style() on all involved widgets when the @siblings path changes. the position where the element was inserted. the widget path to append to a widget path describing a list of siblings. This path may not contain any siblings itself and it must not be modified afterwards. index into @siblings for where the added element is positioned. Returns a copy of @path a copy of @path a #GtkWidgetPath Decrements the reference count on @path, freeing the structure if the reference count reaches 0. a #GtkWidgetPath Returns the topmost object type, that is, the object type this path is representing. The object type a #GtkWidget Returns %TRUE if any of the parents of the widget represented in @path is of type @type, or any subtype of it. %TRUE if any parent is of type @type a #GtkWidgetPath widget type to check in parents Returns %TRUE if the widget type represented by this path is @type, or a subtype of it. %TRUE if the widget represented by @path is of type @type a #GtkWidgetPath widget type to match Adds the class @name to the widget at position @pos in the hierarchy defined in @path. See gtk_style_context_add_class(). a #GtkWidget position to modify, -1 for the path head a class name Adds the region @name to the widget at position @pos in the hierarchy defined in @path. See gtk_style_context_add_region(). Region names must only contain lowercase letters and “-”, starting always with a lowercase letter. The use of regions is deprecated. a #GtkWidgetPath position to modify, -1 for the path head region name flags affecting the region Removes all classes from the widget at position @pos in the hierarchy defined in @path. a #GtkWidget position to modify, -1 for the path head Removes all regions from the widget at position @pos in the hierarchy defined in @path. The use of regions is deprecated. a #GtkWidgetPath position to modify, -1 for the path head Returns the name corresponding to the widget found at the position @pos in the widget hierarchy defined by @path The widget name, or %NULL if none was set. a #GtkWidgetPath position to get the widget name for, -1 for the path head Returns the object name that is at position @pos in the widget hierarchy defined in @path. the name or %NULL a #GtkWidgetPath position to get the object name for, -1 for the path head Returns the object #GType that is at position @pos in the widget hierarchy defined in @path. a widget type a #GtkWidgetPath position to get the object type for, -1 for the path head Returns the index into the list of siblings for the element at @pos as returned by gtk_widget_path_iter_get_siblings(). If that function would return %NULL because the element at @pos has no siblings, this function will return 0. 0 or the index into the list of siblings for the element at @pos. a #GtkWidgetPath position to get the sibling index for, -1 for the path head Returns the list of siblings for the element at @pos. If the element was not added with siblings, %NULL is returned. %NULL or the list of siblings for the element at @pos. a #GtkWidgetPath position to get the siblings for, -1 for the path head Returns the state flags corresponding to the widget found at the position @pos in the widget hierarchy defined by @path The state flags a #GtkWidgetPath position to get the state for, -1 for the path head Returns %TRUE if the widget at position @pos has the class @name defined, %FALSE otherwise. %TRUE if the class @name is defined for the widget at @pos a #GtkWidgetPath position to query, -1 for the path head class name Returns %TRUE if the widget at position @pos has the name @name, %FALSE otherwise. %TRUE if the widget at @pos has this name a #GtkWidgetPath position to query, -1 for the path head a widget name See gtk_widget_path_iter_has_class(). This is a version that operates with GQuarks. %TRUE if the widget at @pos has the class defined. a #GtkWidgetPath position to query, -1 for the path head class name as a #GQuark See gtk_widget_path_iter_has_name(). This is a version that operates on #GQuarks. %TRUE if the widget at @pos has this name a #GtkWidgetPath position to query, -1 for the path head widget name as a #GQuark See gtk_widget_path_iter_has_region(). This is a version that operates with GQuarks. The use of regions is deprecated. %TRUE if the widget at @pos has the region defined. a #GtkWidgetPath position to query, -1 for the path head region name as a #GQuark return location for the region flags Returns %TRUE if the widget at position @pos has the class @name defined, %FALSE otherwise. The use of regions is deprecated. %TRUE if the class @name is defined for the widget at @pos a #GtkWidgetPath position to query, -1 for the path head region name return location for the region flags Returns a list with all the class names defined for the widget at position @pos in the hierarchy defined in @path. The list of classes, This is a list of strings, the #GSList contents are owned by GTK+, but you should use g_slist_free() to free the list itself. a #GtkWidgetPath position to query, -1 for the path head Returns a list with all the region names defined for the widget at position @pos in the hierarchy defined in @path. The use of regions is deprecated. The list of regions, This is a list of strings, the #GSList contents are owned by GTK+, but you should use g_slist_free() to free the list itself. a #GtkWidgetPath position to query, -1 for the path head Removes the class @name from the widget at position @pos in the hierarchy defined in @path. a #GtkWidgetPath position to modify, -1 for the path head class name Removes the region @name from the widget at position @pos in the hierarchy defined in @path. The use of regions is deprecated. a #GtkWidgetPath position to modify, -1 for the path head region name Sets the widget name for the widget found at position @pos in the widget hierarchy defined by @path. a #GtkWidgetPath position to modify, -1 for the path head widget name Sets the object name for a given position in the widget hierarchy defined by @path. When set, the object name overrides the object type when matching CSS. a #GtkWidgetPath position to modify, -1 for the path head object name to set or %NULL to unset Sets the object type for a given position in the widget hierarchy defined by @path. a #GtkWidgetPath position to modify, -1 for the path head object type to set Sets the widget name for the widget found at position @pos in the widget hierarchy defined by @path. 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 |[<!-- language="C" --> gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag); ]| ## Unsetting a flag |[<!-- language="C" --> gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag); ]| a #GtkWidgetPath position to modify, -1 for the path head state flags Returns the number of #GtkWidget #GTypes between the represented widget and its topmost container. the number of elements in the path a #GtkWidgetPath Prepends a widget type to the widget hierachy represented by @path. a #GtkWidgetPath widget type to prepend Increments the reference count on @path. @path itself. a #GtkWidgetPath 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. A new string describing @path. the path Decrements the reference count on @path, freeing the structure if the reference count reaches 0. a #GtkWidgetPath A GtkWindow 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,...). # GtkWindow as GtkBuildable The GtkWindow implementation of the #GtkBuildable interface supports a custom <accel-groups> element, which supports any number of <group> elements representing the #GtkAccelGroup objects you want to add to your window (synonymous with gtk_window_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: |[ <object class="GtkWindow"> <accel-groups> <group name="accelgroup1"/> </accel-groups> <initial-focus name="thunderclap"/> </object> ... <object class="GtkAccelGroup" id="accelgroup1"/> ]| The GtkWindow implementation of the #GtkBuildable interface supports setting a child as the titlebar by specifying “titlebar” as the “type” attribute of a <child> element. # CSS nodes |[<!-- language="plain" --> window.background ├── decoration ├── <titlebar child>.titlebar [.default-decoration] ╰── <child> ]| GtkWindow 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). GtkWindow 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. GtkWindow adds the .titlebar and .default-decoration style classes to the widget that is added as a titlebar child. Creates a new #GtkWindow, which is a toplevel window that can contain other widgets. Nearly always, the type of the window should be #GTK_WINDOW_TOPLEVEL. If you’re implementing something like a popup menu from scratch (which is a bad idea, just use #GtkMenu), you might use #GTK_WINDOW_POPUP. #GTK_WINDOW_POPUP is not for dialogs, though in some other toolkits dialogs are called “popups”. In GTK+, #GTK_WINDOW_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 gtk_window_set_decorated(), don’t use #GTK_WINDOW_POPUP. All top-level windows created by gtk_window_new() are stored in an internal top-level window list. This list can be obtained from gtk_window_list_toplevels(). Due to Gtk+ keeping a reference to the window internally, gtk_window_new() does not return a reference to the caller. To delete a #GtkWindow, call gtk_widget_destroy(). a new #GtkWindow. type of window Gets the value set by gtk_window_set_default_icon_list(). The list is a copy and should be freed with g_list_free(), but the pixbufs in the list have not had their reference count incremented. copy of default icon list Returns the fallback icon name for windows that has been set with gtk_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 gtk_window_set_default_icon_name(). the fallback icon name for windows 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. list of toplevel widgets By default, after showing the first #GtkWindow, 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. %TRUE to automatically do startup notification Sets an icon to be used as fallback for windows that haven't had gtk_window_set_icon() called on them from a pixbuf. the icon Sets an icon to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on them from a file on disk. Warns on failure if @err is %NULL. %TRUE if setting the icon succeeded. location of icon file Sets an icon list to be used as fallback for windows that haven't had gtk_window_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 gtk_window_set_icon_list() for more details. a list of #GdkPixbuf Sets an icon to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on them from a named themed icon, see gtk_window_set_icon_name(). the name of the themed icon Opens or closes the [interactive debugger][interactive-debugging], which offers access to the widget hierarchy of the application and to useful debugging tools. %TRUE to enable interactive debugging If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, 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 gtk_widget_grab_focus() instead of this function. a #GtkWindow widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. Activates the default widget for the window, unless the current focused widget has been configured to receive the default action (see gtk_widget_set_receives_default()), in which case the focused widget is activated. %TRUE if a widget got activated. a #GtkWindow Activates the current focused widget within the window. %TRUE if a widget got activated. a #GtkWindow Activates mnemonics and accelerators for this #GtkWindow. 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. %TRUE if a mnemonic or accelerator was found and activated. a #GtkWindow a #GdkEventKey Associate @accel_group with @window, such that calling gtk_accel_groups_activate() on @window will activate accelerators in @accel_group. window to attach accelerator group to a #GtkAccelGroup Adds a mnemonic to this window. a #GtkWindow the mnemonic the widget that gets activated by the mnemonic 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. a #GtkWindow mouse button that initiated the drag X position where the user clicked to initiate the drag, in root window coordinates Y position where the user clicked to initiate the drag timestamp from the click event that initiated the 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. a #GtkWindow position of the resize control mouse button that initiated the drag X position where the user clicked to initiate the drag, in root window coordinates Y position where the user clicked to initiate the drag timestamp from the click event that initiated the drag 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. a #GtkWindow Asks to deiconify (i.e. unminimize) the specified @window. 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 #GtkWidget. a #GtkWindow Asks to place @window 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 #GtkWidget. a #GtkWindow Asks to place @window 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 #GtkWidget. a #GtkWindow a #GdkScreen to draw to which monitor to go fullscreen on Gets the value set by gtk_window_set_accept_focus(). %TRUE if window should receive the input focus a #GtkWindow Gets the #GtkApplication associated with the window (if any). a #GtkApplication, or %NULL a #GtkWindow Fetches the attach widget for this window. See gtk_window_set_attached_to(). the widget where the window is attached, or %NULL if the window is not attached to any widget. a #GtkWindow Returns whether the window has been set to have decorations such as a title bar via gtk_window_set_decorated(). %TRUE if the window has been set to have decorations a #GtkWindow 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. a #GtkWindow location to store the default width, or %NULL location to store the default height, or %NULL Returns the default widget for @window. See gtk_window_set_default() for more details. the default widget, or %NULL if there is none. a #GtkWindow Returns whether the window has been set to have a close button via gtk_window_set_deletable(). %TRUE if the window has been set to have a close button a #GtkWindow Returns whether the window will be destroyed with its transient parent. See gtk_window_set_destroy_with_parent (). %TRUE if the window will be destroyed with its transient parent. a #GtkWindow 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. the currently focused widget, or %NULL if there is none. a #GtkWindow Gets the value set by gtk_window_set_focus_on_map(). %TRUE if window should receive the input focus when mapped. a #GtkWindow Gets the value of the #GtkWindow:focus-visible property. %TRUE if “focus rectangles” are supposed to be visible in this window. a #GtkWindow Gets the value set by gtk_window_set_gravity(). window gravity a #GtkWindow Returns the group for @window or the default group, if @window is %NULL or if @window does not have an explicit window group. the #GtkWindowGroup for a window or the default group a #GtkWindow, or %NULL Determines whether the window may have a resize grip. Resize grips have been removed. %TRUE if the window has a resize grip a #GtkWindow Returns whether the window has requested to have its titlebar hidden when maximized. See gtk_window_set_hide_titlebar_when_maximized (). %TRUE if the window has requested to have its titlebar hidden when maximized a #GtkWindow Gets the value set by gtk_window_set_icon() (or if you've called gtk_window_set_icon_list(), gets the first icon in the icon list). icon for window or %NULL if none a #GtkWindow Retrieves the list of icons set by gtk_window_set_icon_list(). The list is copied, but the reference count on each member won’t be incremented. copy of window’s icon list a #GtkWindow Returns the name of the themed icon for the window, see gtk_window_set_icon_name(). the icon name or %NULL if the window has no themed icon a #GtkWindow Returns the mnemonic modifier for this window. See gtk_window_set_mnemonic_modifier(). the modifier mask used to activate mnemonics on this window. a #GtkWindow Gets the value of the #GtkWindow:mnemonics-visible property. %TRUE if mnemonics are supposed to be visible in this window. a #GtkWindow Returns whether the window is modal. See gtk_window_set_modal(). %TRUE if the window is set to be modal and establishes a grab when shown a #GtkWindow Fetches the requested opacity for this window. See gtk_window_set_opacity(). Use gtk_widget_get_opacity instead. the requested opacity for this window. a #GtkWindow This function returns the position you need to pass to gtk_window_move() to keep @window in its current position. This means that the meaning of the returned value varies with window gravity. See gtk_window_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_NORTH_WEST. This means that gtk_window_get_position() gets the position of the top-left corner of the window manager frame for the window. gtk_window_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 gtk_window_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. a #GtkWindow return location for X coordinate of gravity-determined reference point, or %NULL return location for Y coordinate of gravity-determined reference point, or %NULL Gets the value set by gtk_window_set_resizable(). %TRUE if the user can resize the window a #GtkWindow If a window has a resize grip, this will retrieve the grip position, width and height into the specified #GdkRectangle. Resize grips have been removed. %TRUE if the resize grip’s area was retrieved a #GtkWindow a pointer to a #GdkRectangle which we should store the resize grip area Returns the role of the window. See gtk_window_set_role() for further explanation. the role of the window if set, or %NULL. The returned is owned by the widget and must not be modified or freed. a #GtkWindow Returns the #GdkScreen associated with @window. a #GdkScreen. a #GtkWindow. Obtains the current size of @window. If @window 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: gtk_window_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 gtk_window_resize(); additionally, since gtk_window_resize() may be implemented as an asynchronous operation, GTK+ cannot guarantee in any way that this code: |[<!-- language="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 #GtkWindow, 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 gtk_window_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 #GtkWidget::size-allocate signal, or inside a handler for the #GtkWidget::configure-event signal: |[<!-- language="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 #GtkWidget::size-allocate signal, you should not use the dimensions of the #GtkAllocation 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 gtk_window_set_type_hint(), which allows the window manager to e.g. center dialogs. Also, if you set the transient parent of dialogs with gtk_window_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: gtk_window_set_position(). a #GtkWindow return location for width, or %NULL return location for height, or %NULL Gets the value set by gtk_window_set_skip_pager_hint(). %TRUE if window shouldn’t be in pager a #GtkWindow Gets the value set by gtk_window_set_skip_taskbar_hint() %TRUE if window shouldn’t be in taskbar a #GtkWindow Retrieves the title of the window. See gtk_window_set_title(). the title of the window, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a #GtkWindow Returns the custom titlebar that has been set with gtk_window_set_titlebar(). the custom titlebar, or %NULL a #GtkWindow Fetches the transient parent for this window. See gtk_window_set_transient_for(). the transient parent for this window, or %NULL if no transient parent has been set. a #GtkWindow Gets the type hint for this window. See gtk_window_set_type_hint(). the type hint for @window. a #GtkWindow Gets the value set by gtk_window_set_urgency_hint() %TRUE if window is urgent a #GtkWindow Gets the type of the window. See #GtkWindowType. the type of the window a #GtkWindow Returns whether @window has an explicit window group. %TRUE if @window has an explicit window group. Since 2.22 a #GtkWindow Returns whether the input focus is within this GtkWindow. For real toplevel windows, this is identical to gtk_window_is_active(), but for embedded windows, like #GtkPlug, the results will differ. %TRUE if the input focus is within this GtkWindow a #GtkWindow Asks to iconify (i.e. minimize) the specified @window. 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 #GtkWidget. a #GtkWindow 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 #GtkPlug 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 gtk_window_has_toplevel_focus() %TRUE if the window part of the current active window. a #GtkWindow Retrieves the current maximized state of @window. 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 gtk_window_maximize() or gtk_window_unmaximize(). whether the window has a maximized state. a #GtkWindow Asks to maximize @window, 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 #GtkWidget, or by listening to notifications on the #GtkWindow:is-maximized property. a #GtkWindow Activates the targets associated with the mnemonic. %TRUE if the activation is done. a #GtkWindow the mnemonic the modifiers Asks the [window manager][gtk-X11-arch] to move @window 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_NORTH_WEST, so the reference point is simply the @x, @y supplied to gtk_window_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_NORTH_WEST) and move the window to 0,0. To position a window at the bottom right corner of the screen, you would set #GDK_GRAVITY_SOUTH_EAST, 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 gtk_window_get_position() documentation may also be relevant. a #GtkWindow X coordinate to move window to Y coordinate to move window to Parses a standard X Window System geometry string - see the manual page for X (type “man X”) for details on this. gtk_window_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, gtk_window_parse_geometry() returns %TRUE and calls gtk_window_set_default_size() and/or gtk_window_move() to resize/move the window. If gtk_window_parse_geometry() returns %TRUE, it will also set the #GDK_HINT_USER_POS and/or #GDK_HINT_USER_SIZE 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 gtk_window_parse_geometry() to work as expected, it has to be called when the window has its “final” size, i.e. after calling gtk_widget_show_all() on the contents and gtk_window_set_geometry_hints() on the window. |[<!-- language="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; } ]| Geometry handling in GTK is deprecated. %TRUE if string was parsed successfully a #GtkWindow geometry string 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. a #GtkWindow 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 @window is hidden, this function calls gtk_widget_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 gtk_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. a #GtkWindow the timestamp of the user interaction (typically a button or key press event) which triggered this call 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. %TRUE if a widget in the focus chain handled the event. a #GtkWindow a #GdkEventKey Reverses the effects of gtk_window_add_accel_group(). a #GtkWindow a #GtkAccelGroup Removes a mnemonic from this window. a #GtkWindow the mnemonic the widget that gets activated by the mnemonic Hides @window, then reshows it, resetting the default size and position of the window. Used by GUI builders only. GUI builders can call gtk_widget_hide(), gtk_widget_unrealize() and then gtk_widget_show() on @window themselves, if they still need this functionality. a #GtkWindow 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 gtk_widget_set_size_request() to set the window's request to a smaller value. If gtk_window_resize() is called before showing a window for the first time, it overrides any default size set with gtk_window_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 gtk_window_resize() is issued. If the GtkWindow has a titlebar widget (see gtk_window_set_titlebar()), then typically, gtk_window_resize() will compensate for the height of the titlebar widget only if the height is known when the resulting GtkWindow configuration is issued. For example, if new widgets are added after the GtkWindow configuration and cause the titlebar widget to grow in height, this will result in a window content smaller that specified by gtk_window_resize() and not a larger window. a #GtkWindow width in pixels to resize the window to height in pixels to resize the window to Determines whether a resize grip is visible for the specified window. Resize grips have been removed. %TRUE if a resize grip exists and is visible a #GtkWindow Like gtk_window_resize(), but @width and @height are interpreted in terms of the base size and increment set with gtk_window_set_geometry_hints. This function does nothing. Use gtk_window_resize() and compute the geometry yourself. a #GtkWindow width in resize increments to resize the window to height in resize increments to resize the window to Windows may set a hint asking the desktop environment not to receive the input focus. This function sets this hint. a #GtkWindow %TRUE to let this window receive input focus Sets or unsets the #GtkApplication associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_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 %NULL. This is equivalent to calling gtk_application_remove_window() and/or gtk_application_add_window() on the old/new applications as relevant. a #GtkWindow a #GtkApplication, or %NULL to unset Marks @window 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 @window as if it was a children of @attach_widget. Examples of places where specifying this relation is useful are for instance a #GtkMenu created by a #GtkComboBox, a completion popup window created by #GtkEntry or a typeahead search entry created by #GtkTreeView. Note that this function should not be confused with gtk_window_set_transient_for(), which specifies a window manager relation between two toplevels instead. Passing %NULL for @attach_widget detaches the window. a #GtkWindow a #GtkWidget, or %NULL 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 gtk_widget_show(). On Windows, this function always works, since there’s no window manager policy involved. a #GtkWindow %TRUE to decorate the window 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 #GtkWindow. When setting (rather than unsetting) the default widget it’s generally easier to call gtk_widget_grab_default() on the widget. Before making a widget the default widget, you must call gtk_widget_set_can_default() on the widget you’d like to make the default. a #GtkWindow widget to be the default, or %NULL to unset the default widget for the toplevel Like gtk_window_set_default_size(), but @width and @height are interpreted in terms of the base size and increment set with gtk_window_set_geometry_hints. This function does nothing. If you want to set a default size, use gtk_window_set_default_size() instead. a #GtkWindow width in resize increments, or -1 to unset the default width height in resize increments, or -1 to unset the default height 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 (gtk_window_set_geometry_hints() can be used to set these explicitly), the default size will be clamped to the nearest permitted size. Unlike gtk_widget_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 gtk_window_set_geometry_hints(). For some uses, gtk_window_resize() is a more appropriate function. gtk_window_resize() changes the current size of the window, rather than the size to be used on initial display. gtk_window_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 gtk_window_get_size(). Using the window allocation directly will not work in all circumstances and can lead to growing or shrinking windows. a #GtkWindow width in pixels, or -1 to unset the default width height in pixels, or -1 to unset the default height 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 gtk_widget_show(). On Windows, this function always works, since there’s no window manager policy involved. a #GtkWindow %TRUE to decorate the window as deletable If @setting is %TRUE, then destroying the transient parent of @window will also destroy @window itself. This is useful for dialogs that shouldn’t persist beyond the lifetime of the main window they're associated with, for example. a #GtkWindow whether to destroy @window with its transient parent If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, 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 gtk_widget_grab_focus() instead of this function. a #GtkWindow widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. 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. a #GtkWindow %TRUE to let this window receive input focus on map Sets the #GtkWindow:focus-visible property. a #GtkWindow the new value 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 #GdkGeometry struct. a #GtkWindow widget the geometry hints used to be applied to or %NULL. Since 3.20 this argument is ignored and GTK behaves as if %NULL was set. struct containing geometry information or %NULL mask indicating which struct fields should be paid attention to Window gravity defines the meaning of coordinates passed to gtk_window_move(). See gtk_window_move() and #GdkGravity for more details. The default window gravity is #GDK_GRAVITY_NORTH_WEST which will typically “do what you mean.” a #GtkWindow window gravity Sets whether @window has a corner resize grip. Note that the resize grip is only shown if the window is actually resizable and not maximized. Use gtk_window_resize_grip_is_visible() to find out if the resize grip is currently shown. Resize grips have been removed. a #GtkWindow %TRUE to allow a resize grip Tells GTK+ whether to drop its extra reference to the window when gtk_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. a #GtkWindow the new value If @setting is %TRUE, then @window 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 gtk_window_set_titlebar() are not affected by this. The application is in full control of their content and visibility anyway. a #GtkWindow whether to hide the titlebar when @window is maximized Sets up the icon representing a #GtkWindow. 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 gtk_window_set_icon_list(). Then the best size will be used. This function is equivalent to calling gtk_window_set_icon_list() with a 1-element list. See also gtk_window_set_default_icon_list() to set the icon for all windows in your application in one go. a #GtkWindow icon image, or %NULL Sets the icon for @window. Warns on failure if @err is %NULL. This function is equivalent to calling gtk_window_set_icon() with a pixbuf created by loading the image from @filename. %TRUE if setting the icon succeeded. a #GtkWindow location of icon file Sets up the icon representing a #GtkWindow. 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. gtk_window_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 gtk_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 gtk_window_set_transient_for()) will inherit their icon from their transient parent. So there’s no need to explicitly set the icon on transient windows. a #GtkWindow list of #GdkPixbuf Sets the icon for the window from a named themed icon. See the docs for #GtkIconTheme 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. a #GtkWindow the name of the themed icon Asks to keep @window 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 #GtkWidget. 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. a #GtkWindow whether to keep @window above other windows Asks to keep @window 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 #GtkWidget. 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. a #GtkWindow whether to keep @window below other windows Sets the mnemonic modifier for this window. a #GtkWindow the modifier mask used to activate mnemonics on this window. Sets the #GtkWindow:mnemonics-visible property. a #GtkWindow the new value 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 gtk_window_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. a #GtkWindow whether the window is modal Request the windowing system to make @window partially transparent, with opacity 0 being fully transparent and 1 fully opaque. (Values of the opacity parameter are clamped to the [0,1] range.) On X11 this has any effect only on X screens with a compositing manager running. See gtk_widget_is_composited(). On Windows it should work always. Note that setting a window’s opacity after the window has been shown causes it to flicker once on Windows. Use gtk_widget_set_opacity instead. a #GtkWindow desired opacity, between 0 and 1 Sets a position constraint for this window. If the old or new constraint is %GTK_WIN_POS_CENTER_ALWAYS, this will also cause the window to be repositioned to satisfy the new constraint. a #GtkWindow. a position constraint. Sets whether the user can resize a window. Windows are user resizable by default. a #GtkWindow %TRUE if the user can resize this window 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. a #GtkWindow unique identifier for the window to be used when restoring a session Sets the #GdkScreen where the @window is displayed; if the window is already mapped, it will be unmapped, and then remapped on the new screen. a #GtkWindow. a #GdkScreen. 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.) a #GtkWindow %TRUE to keep this window from appearing in the pager Windows may set a hint asking the desktop environment not to display the window in the task bar. This function sets this hint. a #GtkWindow %TRUE to keep this window from appearing in the task bar 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 GdkWindow. 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 gtk_window_present() or any equivalent function generating a window map event. This function is only useful on X11, not with other GTK+ targets. a #GtkWindow a string with startup-notification identifier Sets the title of the #GtkWindow. 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. a #GtkWindow title of the window Sets a custom titlebar for @window. A typical widget used here is #GtkHeaderBar, 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 gtk_widget_show(). a #GtkWindow the widget to use as titlebar 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. gtk_dialog_new_with_buttons() and other convenience functions in GTK+ will sometimes call gtk_window_set_transient_for() on your behalf. Passing %NULL for @parent unsets the current transient window. On Wayland, this function can also be used to attach a new #GTK_WINDOW_POPUP to a #GTK_WINDOW_TOPLEVEL parent already mapped on screen so that the #GTK_WINDOW_POPUP will be created as a subsurface-based window #GDK_WINDOW_SUBSURFACE which can be positioned at will relatively to the #GTK_WINDOW_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. a #GtkWindow parent window, or %NULL 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. gtk_dialog_new_with_buttons() and other convenience functions in GTK+ will sometimes call gtk_window_set_type_hint() on your behalf. a #GtkWindow the window type Windows may set a hint asking the desktop environment to draw the users attention to the window. This function sets this hint. a #GtkWindow %TRUE to mark this window as urgent 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 gtk_window_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. a #GtkWindow window name hint window class hint Asks to stick @window, 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 #GtkWidget. a #GtkWindow Asks to toggle off the fullscreen state for @window. 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 #GtkWidget. a #GtkWindow Asks to unmaximize @window. 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 #GtkWidget. a #GtkWindow Asks to unstick @window, 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 #GtkWidget. a #GtkWindow Whether the window should receive the input focus. The #GtkApplication associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_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 %NULL. The widget to which this window is attached. See gtk_window_set_attached_to(). Examples of places where specifying this relation is useful are for instance a #GtkMenu created by a #GtkComboBox, a completion popup window created by #GtkEntry or a typeahead search entry created by #GtkTreeView. Whether the window should be decorated by the window manager. Whether the window frame should have a close button. Whether the window should receive the input focus when mapped. 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. The window gravity of the window. See gtk_window_move() and #GdkGravity for more details about window gravity. Whether the window has a corner resize grip. Note that the resize grip is only shown if the window is actually resizable and not maximized. Use #GtkWindow:resize-grip-visible to find out if the resize grip is currently shown. Resize grips have been removed. Whether the titlebar should be hidden during maximization. The :icon-name property specifies the name of the themed icon to use as the window icon. See #GtkIconTheme for more details. 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. Whether a corner resize grip is currently shown. Resize grips have been removed. The :startup-id is a write-only property for setting window's startup notification identifier. See gtk_window_set_startup_id() for more details. The transient parent of the window. See gtk_window_set_transient_for() for more details about transient windows. The ::activate-default signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the default widget of @window. The ::activate-focus signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user activates the currently focused widget of @window. The ::enable-debugging signal is a [keybinding signal][GtkBindingSignal] 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. %TRUE if the key binding was handled toggle the debugger The ::keys-changed signal gets emitted when the set of accelerators or mnemonics that are associated with @window changes. The parent class. a #GtkWindow widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. A #GtkWindowGroup 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. GtkWindowGroup objects are referenced by each window in the group, so once you have added all windows to a GtkWindowGroup, you can drop the initial reference to the window group with g_object_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. Creates a new #GtkWindowGroup object. Grabs added with gtk_grab_add() only affect windows within the same #GtkWindowGroup. a new #GtkWindowGroup. Adds a window to a #GtkWindowGroup. a #GtkWindowGroup the #GtkWindow to add Returns the current grab widget for @device, or %NULL if none. The grab widget, or %NULL a #GtkWindowGroup a #GdkDevice Gets the current grab widget of the given group, see gtk_grab_add(). the current grab widget of the group a #GtkWindowGroup Returns a list of the #GtkWindows that belong to @window_group. A newly-allocated list of windows inside the group. a #GtkWindowGroup Removes a window from a #GtkWindowGroup. a #GtkWindowGroup the #GtkWindow to remove Window placement can be influenced using this enumeration. Note that using #GTK_WIN_POS_CENTER_ALWAYS is almost always a bad idea. It won’t necessarily work well with all window managers or on all windowing systems. No influence is made on placement. Windows should be placed in the center of the screen. Windows should be placed at the current mouse position. Keep window centered as it changes size, etc. Center the window on its transient parent (see gtk_window_set_transient_for()). A #GtkWindow can be one of these types. Most things you’d consider a “window” should have type #GTK_WINDOW_TOPLEVEL; windows with this type are managed by the window manager and have a frame by default (call gtk_window_set_decorated() to toggle the frame). Windows with type #GTK_WINDOW_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). #GTK_WINDOW_POPUP is used to implement widgets such as #GtkMenu or tooltips that you normally don’t think of as windows per se. Nearly all windows should be #GTK_WINDOW_TOPLEVEL. In particular, do not use #GTK_WINDOW_POPUP just to turn off the window borders; use gtk_window_set_decorated() for that. A regular window, such as a dialog. A special window such as a tooltip. Describes a type of line wrapping. do not wrap lines; just make the text area wider 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()) wrap text, breaking lines in between words wrap text, breaking lines in between words, or if that is not enough, also between graphemes Finds the first accelerator in any #GtkAccelGroup attached to @object that matches @accel_key and @accel_mods, and activates that accelerator. %TRUE if an accelerator was activated and handled this keypress the #GObject, usually a #GtkWindow, on which to activate the accelerator accelerator keyval from a key event keyboard state mask from a key event Gets a list of all accel groups which are attached to @object. a list of all accel groups which are attached to @object a #GObject, usually a #GtkWindow Gets the modifier mask. The modifier mask determines which modifiers are considered significant for keyboard accelerators. See gtk_accelerator_set_default_mod_mask(). the default accelerator modifier mask Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user. a newly-allocated string representing the accelerator. accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a (possibly translated) string that can be displayed to a user, similarly to gtk_accelerator_get_label(), but handling keycodes. This is only useful for system-level components, applications should use gtk_accelerator_parse() instead. a newly-allocated string representing the accelerator. a #GdkDisplay or %NULL to use the default display accelerator keyval accelerator keycode accelerator modifier mask Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse(). For example, if you pass in #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”. If you need to display accelerators in the user interface, see gtk_accelerator_get_label(). a newly-allocated accelerator name accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse_with_keycode(), similarly to gtk_accelerator_name() but handling keycodes. This is only useful for system-level components, applications should use gtk_accelerator_parse() instead. a newly allocated accelerator name. a #GdkDisplay or %NULL to use the default display accelerator keyval accelerator keycode accelerator modifier mask Parses a string representing an accelerator. The format looks like “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is for key release). The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using gdk_keyval_from_name(). For character keys the name is not the symbol, but the lowercase name, e.g. one would use “<Ctrl>minus” instead of “<Ctrl>-”. If the parse fails, @accelerator_key and @accelerator_mods will be set to 0 (zero). string representing an accelerator return location for accelerator keyval, or %NULL return location for accelerator modifier mask, %NULL Parses a string representing an accelerator, similarly to gtk_accelerator_parse() but handles keycodes as well. This is only useful for system-level components, applications should use gtk_accelerator_parse() instead. If @accelerator_codes is given and the result stored in it is non-%NULL, the result must be freed with g_free(). If a keycode is present in the accelerator and no @accelerator_codes is given, the parse will fail. If the parse fails, @accelerator_key, @accelerator_mods and @accelerator_codes will be set to 0 (zero). string representing an accelerator return location for accelerator keyval, or %NULL return location for accelerator keycodes, or %NULL return location for accelerator modifier mask, %NULL Sets the modifiers that will be considered significant for keyboard accelerators. The default mod mask depends on the GDK backend in use, but will typically include #GDK_CONTROL_MASK | #GDK_SHIFT_MASK | #GDK_MOD1_MASK | #GDK_SUPER_MASK | #GDK_HYPER_MASK | #GDK_META_MASK. In other words, Control, Shift, Alt, Super, Hyper and Meta. Other modifiers will by default be ignored by #GtkAccelGroup. You must include at least the three modifiers Control, Shift and Alt in any value you pass to this function. The default mod mask should be changed on application startup, before using any accelerator groups. accelerator modifier mask Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the #GDK_KEY_a keyval plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. But, you can't, for instance, use the #GDK_KEY_Control_L keyval as an accelerator. %TRUE if the accelerator is valid a GDK keyval modifier mask Returns %TRUE if dialogs are expected to use an alternative button order on the screen @screen. See gtk_dialog_set_alternative_button_order() for more details about alternative button order. If you need to use this function, you should probably connect to the ::notify:gtk-alternative-button-order signal on the #GtkSettings object associated to @screen, in order to be notified if the button order setting changes. Deprecated Whether the alternative button order should be used a #GdkScreen, or %NULL to use the default screen Parses a signal description from @signal_desc and incorporates it into @binding_set. Signal descriptions may either bind a key combination to one or more signals: |[ bind "key" { "signalname" (param, ...) ... } ]| Or they may also unbind a key combination: |[ unbind "key" ]| Key combinations must be in a format that can be parsed by gtk_accelerator_parse(). %G_TOKEN_NONE if the signal was successfully parsed and added, the expected token otherwise a #GtkBindingSet a signal description Override or install a new key binding for @keyval with @modifiers on @binding_set. a #GtkBindingSet to add a signal to key value key modifier signal name to be bound list of #GtkBindingArg signal arguments Remove a binding previously installed via gtk_binding_entry_add_signal() on @binding_set. a #GtkBindingSet to remove an entry of key value of binding to remove key modifier of binding to remove Install a binding on @binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated. a #GtkBindingSet to skip an entry of key value of binding to skip key modifier of binding to skip This function returns the binding set named after the type name of the passed in class structure. New binding sets are created on demand by this function. the binding set corresponding to @object_class a valid #GObject class Find a binding set by its globally unique name. The @set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class(). %NULL or the specified binding set unique binding set name GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation. new binding set unique name of this binding set Find a key binding matching @keyval and @modifiers and activate the binding on @object. %TRUE if a binding was found and activated object to activate when binding found key value of the binding key modifier of the binding Looks up key bindings for @object to find one matching @event, and if one was found, activate it. %TRUE if a matching key binding was found a #GObject (generally must be a widget) a #GdkEventKey This function is supposed to be called in #GtkWidget::draw implementations for widgets that support multiple windows. @cr must be untransformed from invoking of the draw function. This function will return %TRUE if the contents of the given @window are supposed to be drawn and %FALSE otherwise. Note that when the drawing was not initiated by the windowing system this function will return %TRUE for all windows, so you need to draw the bottommost window first. Also, do not use “else if” statements to check which window should be drawn. %TRUE if @window should be drawn a cairo context the window to check. @window may not be an input-only window. Transforms the given cairo context @cr that from @widget-relative coordinates to @window-relative coordinates. If the @widget’s window is not an ancestor of @window, no modification will be applied. This is the inverse to the transformation GTK applies when preparing an expose event to be emitted with the #GtkWidget::draw signal. It is intended to help porting multiwindow widgets from GTK+ 2 to the rendering architecture of GTK+ 3. the cairo context to transform the widget the context is currently centered for the window to transform the context to Checks that the GTK+ library in use is compatible with the given version. Generally you would pass in the constants #GTK_MAJOR_VERSION, #GTK_MINOR_VERSION, #GTK_MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GTK+ the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version @required_major.required_minor.@required_micro. Second the running library must be binary compatible with the version @required_major.required_minor.@required_micro (same major version.) This function is primarily for GTK+ modules; the module can call this function to check that it wasn’t loaded into an incompatible version of GTK+. However, such a check isn’t completely reliable, since the module may be linked against an old version of GTK+ and calling the old version of gtk_check_version(), but still get loaded into an application using a newer version of GTK+. %NULL if the GTK+ library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GTK+ and should not be modified or freed. the required major version the required minor version the required micro version Adds a GTK+ grab on @device, so all the events on @device and its associated pointer or keyboard (if any) are delivered to @widget. If the @block_others parameter is %TRUE, any other devices will be unable to interact with @widget during the grab. a #GtkWidget a #GdkDevice to grab on. %TRUE to prevent other devices to interact with @widget. Removes a device grab from the given widget. You have to pair calls to gtk_device_grab_add() and gtk_device_grab_remove(). a #GtkWidget a #GdkDevice Prevents gtk_init(), gtk_init_check(), gtk_init_with_args() and gtk_parse_args() from automatically calling `setlocale (LC_ALL, "")`. You would want to use this function if you wanted to set the locale for your program to something other than the user’s locale, or if you wanted to set different values for different locale categories. Most programs should not need to call this function. Distributes @extra_space to child @sizes by bringing smaller children up to natural size first. The remaining space will be added to the @minimum_size member of the GtkRequestedSize struct. If all sizes reach their natural size then the remaining space is returned. The remainder of @extra_space after redistributing space to @sizes. Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation Number of requests to fit into the allocation An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation. Cancels an ongoing drag operation on the source side. If you want to be able to cancel a drag operation in this way, you need to keep a pointer to the drag context, either from an explicit call to gtk_drag_begin_with_coordinates(), or by connecting to #GtkWidget::drag-begin. If @context does not refer to an ongoing drag operation, this function does nothing. If a drag is cancelled in this way, the @result argument of #GtkWidget::drag-failed is set to @GTK_DRAG_RESULT_ERROR. a #GdkDragContext, as e.g. returned by gtk_drag_begin_with_coordinates() Informs the drag source that the drop is finished, and that the data of the drag will no longer be required. the drag context a flag indicating whether the drop was successful a flag indicating whether the source should delete the original data. (This should be %TRUE for a move) the timestamp from the #GtkWidget::drag-drop signal Determines the source widget for a drag. if the drag is occurring within a single application, a pointer to the source widget. Otherwise, %NULL. a (destination side) drag context Sets the icon for a particular drag to the default icon. the context for a drag (This must be called with a context for the source side of a drag) Sets the icon for a given drag from the given @icon. See the documentation for gtk_drag_set_icon_name() for more details about using icons in drag and drop. the context for a drag (This must be called with a context for the source side of a drag) a #GIcon the X offset of the hotspot within the icon the Y offset of the hotspot within the icon Sets the icon for a given drag from a named themed icon. See the docs for #GtkIconTheme for more details. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size #GTK_ICON_SIZE_DND), thus @hot_x and @hot_y have to be used with care. the context for a drag (This must be called with a context for the source side of a drag) name of icon to use the X offset of the hotspot within the icon the Y offset of the hotspot within the icon Sets @pixbuf as the icon for a given drag. the context for a drag (This must be called with a context for the source side of a drag) the #GdkPixbuf to use as the drag icon the X offset within @widget of the hotspot the Y offset within @widget of the hotspot Sets the icon for a given drag from a stock ID. Use gtk_drag_set_icon_name() instead. the context for a drag (This must be called with a context for the source side of a drag) the ID of the stock icon to use for the drag the X offset within the icon of the hotspot the Y offset within the icon of the hotspot Sets @surface as the icon for a given drag. GTK+ retains references for the arguments, and will release them when they are no longer needed. To position the surface relative to the mouse, use cairo_surface_set_device_offset() on @surface. The mouse cursor will be positioned at the (0,0) coordinate of the surface. the context for a drag (This must be called with a context for the source side of a drag) the surface to use as icon Changes the icon for drag operation to a given widget. GTK+ will not destroy the widget, so if you don’t want it to persist, you should connect to the “drag-end” signal and destroy it yourself. the context for a drag. (This must be called with a context for the source side of a drag) a widget to use as an icon the X offset within @widget of the hotspot the Y offset within @widget of the hotspot Draws a text caret on @cr at @location. This is not a style function but merely a convenience function for drawing the standard cursor shape. Use gtk_render_insertion_cursor() instead. a #GtkWidget cairo context to draw to location where to draw the cursor (@location->width is ignored) if the cursor should be the primary cursor color. whether the cursor is left-to-right or right-to-left. Should never be #GTK_TEXT_DIR_NONE %TRUE to draw a directional arrow on the cursor. Should be %FALSE unless the cursor is split. Checks if any events are pending. This can be used to update the UI and invoke timeouts etc. while doing some time intensive computation. ## Updating the UI during a long computation |[<!-- language="C" --> // computation going on... while (gtk_events_pending ()) gtk_main_iteration (); // ...computation continued ]| %TRUE if any events are pending, %FALSE otherwise Analogical to gtk_true(), this function does nothing but always returns %FALSE. %FALSE Registers an error quark for #GtkFileChooser if necessary. The error quark used for #GtkFileChooser errors. Returns the binary age as passed to `libtool` when building the GTK+ library the process is running against. If `libtool` means nothing to you, don't worry about it. the binary age of the GTK+ library Obtains a copy of the event currently being processed by GTK+. For example, if you are handling a #GtkButton::clicked signal, the current event will be the #GdkEventButton that triggered the ::clicked signal. a copy of the current event, or %NULL if there is no current event. The returned event must be freed with gdk_event_free(). If there is a current event and it has a device, return that device, otherwise return %NULL. a #GdkDevice, or %NULL If there is a current event and it has a state field, place that state field in @state and return %TRUE, otherwise return %FALSE. %TRUE if there was a current event and it had a state field a location to store the state of the current event If there is a current event and it has a timestamp, return that timestamp, otherwise return %GDK_CURRENT_TIME. the timestamp from the current event, or %GDK_CURRENT_TIME. Returns the GTK+ debug flags. This function is intended for GTK+ modules that want to adjust their debug output based on GTK+ debug flags. the GTK+ debug flags. Returns the #PangoLanguage for the default language currently in effect. (Note that this can change over the life of an application.) The default language is derived from the current locale. It determines, for example, whether GTK+ uses the right-to-left or left-to-right text direction. This function is equivalent to pango_language_get_default(). See that function for details. the default language as a #PangoLanguage, must not be freed If @event is %NULL or the event was not associated with any widget, returns %NULL, otherwise returns the widget that received the event originally. the widget that originally received @event, or %NULL a #GdkEvent Returns the interface age as passed to `libtool` when building the GTK+ library the process is running against. If `libtool` means nothing to you, don't worry about it. the interface age of the GTK+ library Get the direction of the current locale. This is the expected reading direction for text and UI. This function depends on the current locale being set with setlocale() and will default to setting the %GTK_TEXT_DIR_LTR direction otherwise. %GTK_TEXT_DIR_NONE will never be returned. GTK+ sets the default text direction according to the locale during gtk_init(), and you should normally use gtk_widget_get_direction() or gtk_widget_get_default_direction() to obtain the current direcion. This function is only needed rare cases when the locale is changed after GTK+ has already been initialized. In this case, you can use it to update the default text direction as follows: |[<!-- language="C" --> setlocale (LC_ALL, new_locale); direction = gtk_get_locale_direction (); gtk_widget_set_default_direction (direction); ]| the #GtkTextDirection of the current locale Returns the major version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 3.) This function is in the library, so it represents the GTK+ library your code is running against. Contrast with the #GTK_MAJOR_VERSION macro, which represents the major version of the GTK+ headers you have included when compiling your code. the major version number of the GTK+ library Returns the micro version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 5.) This function is in the library, so it represents the GTK+ library your code is are running against. Contrast with the #GTK_MICRO_VERSION macro, which represents the micro version of the GTK+ headers you have included when compiling your code. the micro version number of the GTK+ library Returns the minor version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 1.) This function is in the library, so it represents the GTK+ library your code is are running against. Contrast with the #GTK_MINOR_VERSION macro, which represents the minor version of the GTK+ headers you have included when compiling your code. the minor version number of the GTK+ library Returns a #GOptionGroup for the commandline arguments recognized by GTK+ and GDK. You should add this group to your #GOptionContext with g_option_context_add_group(), if you are using g_option_context_parse() to parse your commandline arguments. a #GOptionGroup for the commandline arguments recognized by GTK+ whether to open the default display when parsing the commandline arguments Queries the current grab of the default window group. The widget which currently has the grab or %NULL if no grab is active Looks up the icon size associated with @name. Use #GtkIconTheme instead. the icon size (#GtkIconSize) the name to look up. Gets the canonical name of the given icon size. The returned string is statically allocated and should not be freed. Use #GtkIconTheme instead. the name of the given icon size. a #GtkIconSize. Obtains the pixel size of a semantic icon size @size: #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_icon_theme_load_icon() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. %TRUE if @size was a valid size an icon size (#GtkIconSize) location to store icon width location to store icon height Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular #GtkSettings. Normally @size would be #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_widget_render_icon_pixbuf() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size. Use gtk_icon_size_lookup() instead. %TRUE if @size was a valid size a #GtkSettings object, used to determine which set of user preferences to used. an icon size (#GtkIconSize) location to store icon width location to store icon height Registers a new icon size, along the same lines as #GTK_ICON_SIZE_MENU, etc. Returns the integer value for the size. Use #GtkIconTheme instead. integer value representing the size (#GtkIconSize) name of the icon size the icon width the icon height Registers @alias as another name for @target. So calling gtk_icon_size_from_name() with @alias as argument will return @target. Use #GtkIconTheme instead. an alias for @target an existing icon size (#GtkIconSize) Call this function before using any other GTK+ functions in your GUI applications. It will initialize everything needed to operate the toolkit and parses some standard command line options. Although you are expected to pass the @argc, @argv parameters from main() to this function, it is possible to pass %NULL if @argv is not available or commandline handling is not required. @argc and @argv are adjusted accordingly so your own code will never see those standard arguments. Note that there are some alternative ways to initialize GTK+: if you are calling gtk_parse_args(), gtk_init_check(), gtk_init_with_args() or g_option_context_parse() with the option group returned by gtk_get_option_group(), you don’t have to call gtk_init(). And if you are using #GtkApplication, you don't have to call any of the initialization functions either; the #GtkApplication::startup handler does it for you. This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface you want to call gtk_init_check() instead. Since 2.18, GTK+ calls `signal (SIGPIPE, SIG_IGN)` during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after gtk_init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things. Address of the `argc` parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled. Address of the `argv` parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return. This function does the same work as gtk_init() with only a single change: It does not terminate the program if the commandline arguments couldn’t be parsed or the windowing system can’t be initialized. Instead it returns %FALSE on failure. This way the application can fall back to some other means of communication with the user - for example a curses or command line interface. Note that calling any GTK function or instantiating any GTK type after this function returns %FALSE results in undefined behavior. %TRUE if the commandline arguments (if any) were valid and the windowing system has been successfully initialized, %FALSE otherwise Address of the `argc` parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled. Address of the `argv` parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return. This function does the same work as gtk_init_check(). Additionally, it allows you to add your own commandline options, and it automatically generates nicely formatted `--help` output. Note that your program will be terminated after writing out the help output. %TRUE if the commandline arguments (if any) were valid and if the windowing system has been successfully initialized, %FALSE otherwise Address of the `argc` parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled. Address of the `argv` parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return. a string which is displayed in the first line of `--help` output, after `programname [OPTION...]` a %NULL-terminated array of #GOptionEntrys describing the options of your program a translation domain to use for translating the `--help` output for the options in @entries and the @parameter_string with gettext(), or %NULL Installs a key snooper function, which will get called on all key events before delivering them normally. Key snooping should not be done. Events should be handled by widgets. a unique id for this key snooper for use with gtk_key_snooper_remove(). a #GtkKeySnoopFunc data to pass to @snooper Removes the key snooper function with the given id. Key snooping should not be done. Events should be handled by widgets. Identifies the key snooper to remove Runs the main loop until gtk_main_quit() is called. You can nest calls to gtk_main(). In that case gtk_main_quit() will make the innermost invocation of the main loop return. Processes a single GDK event. This is public only to allow filtering of events between GDK and GTK+. You will not usually need to call this function directly. While you should not call this function directly, you might want to know how exactly events are handled. So here is what this function does with the event: 1. Compress enter/leave notify events. If the event passed build an enter/leave pair together with the next event (peeked from GDK), both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer. 2. Find the widget which got the event. If the widget can’t be determined the event is thrown away unless it belongs to a INCR transaction. 3. Then the event is pushed onto a stack so you can query the currently handled event with gtk_get_current_event(). 4. The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the grab widget are sent to the latter with a few exceptions: - Deletion and destruction events are still sent to the event widget for obvious reasons. - Events which directly relate to the visual representation of the event widget. - Leave events are delivered to the event widget if there was an enter event delivered to it before without the paired leave event. - Drag events are not redirected because it is unclear what the semantics of that would be. Another point of interest might be that all key events are first passed through the key snooper functions if there are any. Read the description of gtk_key_snooper_install() if you need this feature. 5. After finishing the delivery the event is popped from the event stack. An event to process (normally passed by GDK) Runs a single iteration of the mainloop. If no events are waiting to be processed GTK+ will block until the next event is noticed. If you don’t want to block look at gtk_main_iteration_do() or check if any events are pending with gtk_events_pending() first. %TRUE if gtk_main_quit() has been called for the innermost mainloop Runs a single iteration of the mainloop. If no events are available either return or block depending on the value of @blocking. %TRUE if gtk_main_quit() has been called for the innermost mainloop %TRUE if you want GTK+ to block if no events are pending Asks for the current nesting level of the main loop. the nesting level of the current invocation of the main loop Makes the innermost invocation of the main loop return when it regains control. Draws an arrow in the given rectangle on @cr using the given parameters. @arrow_type determines the direction of the arrow. Use gtk_render_arrow() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail the type of arrow to draw %TRUE if the arrow tip should be filled x origin of the rectangle to draw the arrow in y origin of the rectangle to draw the arrow in width of the rectangle to draw the arrow in height of the rectangle to draw the arrow in Draws a box on @cr with the given parameters. Use gtk_render_frame() and gtk_render_background() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the box y origin of the box the width of the box the height of the box Draws a box in @cr using the given style and state and shadow type, leaving a gap in one side. Use gtk_render_frame_gap() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the rectangle y origin of the rectangle width of the rectangle width of the rectangle side in which to leave the gap starting position of the gap width of the gap Draws a check button indicator in the given rectangle on @cr with the given parameters. Use gtk_render_check() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the check in y origin of the rectangle to draw the check in the width of the rectangle to draw the check in the height of the rectangle to draw the check in Draws a diamond in the given rectangle on @window using the given parameters. Use cairo instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the diamond in y origin of the rectangle to draw the diamond in width of the rectangle to draw the diamond in height of the rectangle to draw the diamond in Draws an expander as used in #GtkTreeView. @x and @y specify the center the expander. The size of the expander is determined by the “expander-size” style property of @widget. (If widget is not specified or doesn’t have an “expander-size” property, an unspecified default size will be used, since the caller doesn't have sufficient information to position the expander, this is likely not useful.) The expander is expander_size pixels tall in the collapsed position and expander_size pixels wide in the expanded position. Use gtk_render_expander() instead a #GtkStyle a #cairo_t a state the widget a style detail the x position to draw the expander at the y position to draw the expander at the style to draw the expander in; determines whether the expander is collapsed, expanded, or in an intermediate state. Draws an extension, i.e. a notebook tab. Use gtk_render_extension() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the extension y origin of the extension width of the extension width of the extension the side on to which the extension is attached Draws a flat box on @cr with the given parameters. Use gtk_render_frame() and gtk_render_background() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the box y origin of the box the width of the box the height of the box Draws a focus indicator around the given rectangle on @cr using the given style. Use gtk_render_focus() instead a #GtkStyle a #cairo_t a state the widget a style detail the x origin of the rectangle around which to draw a focus indicator the y origin of the rectangle around which to draw a focus indicator the width of the rectangle around which to draw a focus indicator the height of the rectangle around which to draw a focus indicator Draws a handle as used in #GtkHandleBox and #GtkPaned. Use gtk_render_handle() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the handle y origin of the handle with of the handle height of the handle the orientation of the handle Draws a horizontal line from (@x1, @y) to (@x2, @y) in @cr using the given style and state. Use gtk_render_line() instead a #GtkStyle a #caio_t a state the widget a style detail the starting x coordinate the ending x coordinate the y coordinate Draws a layout on @cr using the given parameters. Use gtk_render_layout() instead a #GtkStyle a #cairo_t a state whether to use the text or foreground graphics context of @style the widget a style detail x origin y origin the layout to draw Draws a radio button indicator in the given rectangle on @cr with the given parameters. Use gtk_render_option() instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the option in y origin of the rectangle to draw the option in the width of the rectangle to draw the option in the height of the rectangle to draw the option in Draws a resize grip in the given rectangle on @cr using the given parameters. Use gtk_render_handle() instead a #GtkStyle a #cairo_t a state the widget a style detail the edge in which to draw the resize grip the x origin of the rectangle in which to draw the resize grip the y origin of the rectangle in which to draw the resize grip the width of the rectangle in which to draw the resize grip the height of the rectangle in which to draw the resize grip Draws a shadow around the given rectangle in @cr using the given style and state and shadow type. Use gtk_render_frame() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the rectangle y origin of the rectangle width of the rectangle width of the rectangle Draws a shadow around the given rectangle in @cr using the given style and state and shadow type, leaving a gap in one side. Use gtk_render_frame_gap() instead a #GtkStyle a #cairo_t a state type of shadow to draw the widget a style detail x origin of the rectangle y origin of the rectangle width of the rectangle width of the rectangle side in which to leave the gap starting position of the gap width of the gap Draws a slider in the given rectangle on @cr using the given style and orientation. Use gtk_render_slider() instead a #GtkStyle a #cairo_t a state a shadow the widget a style detail the x origin of the rectangle in which to draw a slider the y origin of the rectangle in which to draw a slider the width of the rectangle in which to draw a slider the height of the rectangle in which to draw a slider the orientation to be used Draws a spinner on @window using the given parameters. Use gtk_render_icon() and the #GtkStyleContext you are drawing instead a #GtkStyle a #cairo_t a state the widget (may be %NULL) a style detail (may be %NULL) the nth step the x origin of the rectangle in which to draw the spinner the y origin of the rectangle in which to draw the spinner the width of the rectangle in which to draw the spinner the height of the rectangle in which to draw the spinner Draws an option menu tab (i.e. the up and down pointing arrows) in the given rectangle on @cr using the given parameters. Use cairo instead a #GtkStyle a #cairo_t a state the type of shadow to draw the widget a style detail x origin of the rectangle to draw the tab in y origin of the rectangle to draw the tab in the width of the rectangle to draw the tab in the height of the rectangle to draw the tab in Draws a vertical line from (@x, @y1_) to (@x, @y2_) in @cr using the given style and state. Use gtk_render_line() instead a #GtkStyle a #cairo_t a state the widget a style detail the starting y coordinate the ending y coordinate the x coordinate Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK+ and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated #GtkPaperSize objects whether to include custom paper sizes as defined in the page setup dialog Parses command line arguments, and initializes global attributes of GTK+, but does not actually open a connection to a display. (See gdk_display_open(), gdk_get_display_arg_name()) Any arguments used by GTK+ or GDK are removed from the array and @argc and @argv are updated accordingly. There is no need to call this function explicitly if you are using gtk_init(), or gtk_init_check(). Note that many aspects of GTK+ require a display connection to function, so this way of initializing GTK+ is really only useful for specialized use cases. %TRUE if initialization succeeded, otherwise %FALSE a pointer to the number of command line arguments a pointer to the array of command line arguments Registers an error quark for #GtkPrintOperation if necessary. The error quark used for #GtkPrintOperation errors. Runs a page setup dialog, letting the user modify the values from @page_setup. If the user cancels the dialog, the returned #GtkPageSetup is identical to the passed in @page_setup, otherwise it contains the modifications done in the dialog. Note that this function may use a recursive mainloop to show the page setup dialog. See gtk_print_run_page_setup_dialog_async() if this is a problem. a new #GtkPageSetup transient parent an existing #GtkPageSetup a #GtkPrintSettings Runs a page setup dialog, letting the user modify the values from @page_setup. In contrast to gtk_print_run_page_setup_dialog(), this function returns after showing the page setup dialog on platforms that support this, and calls @done_cb from a signal handler for the ::response signal of the dialog. transient parent, or %NULL an existing #GtkPageSetup, or %NULL a #GtkPrintSettings a function to call when the user saves the modified page setup user data to pass to @done_cb Sends an event to a widget, propagating the event to parent widgets if the event remains unhandled. Events received by GTK+ from GDK normally begin in gtk_main_do_event(). Depending on the type of event, existence of modal dialogs, grabs, etc., the event may be propagated; if so, this function is used. gtk_propagate_event() calls gtk_widget_event() on each widget it decides to send the event to. So gtk_widget_event() is the lowest-level function; it simply emits the #GtkWidget::event and possibly an event-specific signal on a widget. gtk_propagate_event() is a bit higher-level, and gtk_main_do_event() is the highest level. All that said, you most likely don’t want to use any of these functions; synthesizing events is rarely needed. There are almost certainly better ways to achieve your goals. For example, use gdk_window_invalidate_rect() or gtk_widget_queue_draw() instead of making up expose events. a #GtkWidget an event Adds a file to the list of files to be parsed at the end of gtk_init(). Use #GtkStyleContext with a custom #GtkStyleProvider instead the pathname to the file. If @filename is not absolute, it is searched in the current directory. Searches for a theme engine in the GTK+ search path. This function is not useful for applications and should not be used. Use #GtkCssProvider instead. The filename, if found (must be freed with g_free()), otherwise %NULL. name of a theme engine Looks up a file in pixmap path for the specified #GtkSettings. If the file is not found, it outputs a warning message using g_warning() and returns %NULL. Use #GtkCssProvider instead. the filename. a #GtkSettings Scanner used to get line number information for the warning message, or %NULL name of the pixmap file to locate. Retrieves the current list of RC files that will be parsed at the end of gtk_init(). Use #GtkStyleContext instead A %NULL-terminated array of filenames. This memory is owned by GTK+ and must not be freed by the application. If you want to store this information, you should make a copy. Obtains the path to the IM modules file. See the documentation of the `GTK_IM_MODULE_FILE` environment variable for more details. Use #GtkCssProvider instead. a newly-allocated string containing the name of the file listing the IM modules available for loading Obtains the path in which to look for IM modules. See the documentation of the `GTK_PATH` environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances. Use #GtkCssProvider instead. a newly-allocated string containing the path in which to look for IM modules. Returns a directory in which GTK+ looks for theme engines. For full information about the search for theme engines, see the docs for `GTK_PATH` in [Running GTK+ Applications][gtk-running]. Use #GtkCssProvider instead. the directory. (Must be freed with g_free()) Finds all matching RC styles for a given widget, composites them together, and then creates a #GtkStyle representing the composite appearance. (GTK+ actually keeps a cache of previously created styles, so a new style may not be created.) Use #GtkStyleContext instead the resulting style. No refcount is added to the returned style, so if you want to save this style around, you should add a reference yourself. a #GtkWidget Creates up a #GtkStyle from styles defined in a RC file by providing the raw components used in matching. This function may be useful when creating pseudo-widgets that should be themed like widgets but don’t actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas widget. The action of gtk_rc_get_style() is similar to: |[<!-- language="C" --> gtk_widget_path (widget, NULL, &path, NULL); gtk_widget_class_path (widget, NULL, &class_path, NULL); gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path, G_OBJECT_TYPE (widget)); ]| Use #GtkStyleContext instead A style created by matching with the supplied paths, or %NULL if nothing matching was specified and the default style should be used. The returned value is owned by GTK+ as part of an internal cache, so you must call g_object_ref() on the returned value if you want to keep a reference to it. a #GtkSettings object the widget path to use when looking up the style, or %NULL if no matching against the widget path should be done the class path to use when looking up the style, or %NULL if no matching against the class path should be done. a type that will be used along with parent types of this type when matching against class styles, or #G_TYPE_NONE Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.) Use #GtkCssProvider instead. The directory (must be freed with g_free()). Parses a given resource file. Use #GtkCssProvider instead. the filename of a file to parse. If @filename is not absolute, it is searched in the current directory. Parses a color in the format expected in a RC file. Note that theme engines should use gtk_rc_parse_color_full() in order to support symbolic colors. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found a #GScanner a pointer to a #GdkColor in which to store the result Parses a color in the format expected in a RC file. If @style is not %NULL, it will be consulted to resolve references to symbolic colors. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found a #GScanner a #GtkRcStyle, or %NULL a pointer to a #GdkColor in which to store the result Parses a #GtkPathPriorityType variable from the format expected in a RC file. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. a #GScanner (must be initialized for parsing an RC file) A pointer to #GtkPathPriorityType variable in which to store the result. Parses a #GtkStateType variable from the format expected in a RC file. Use #GtkCssProvider instead %G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. a #GScanner (must be initialized for parsing an RC file) A pointer to a #GtkStateType variable in which to store the result. Parses resource information directly from a string. Use #GtkCssProvider instead. a string to parse. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses borders in the form `"{ left, right, top, bottom }"` for integers left, right, top and bottom. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkBorder. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a color given either by its name or in the form `{ red, green, blue }` where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GdkColor. a #GParamSpec the #GString to be parsed a #GValue which must hold #GdkColor values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a single enumeration value. The enumeration value can be specified by its name, its nickname or its numeric value. For consistency with flags parsing, the value may be surrounded by parentheses. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GEnumValue. a #GParamSpec the #GString to be parsed a #GValue which must hold enum values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses flags. Flags can be specified by their name, their nickname or numerically. Multiple flags can be specified in the form `"( flag1 | flag2 | ... )"`. %TRUE if @gstring could be parsed and @property_value has been set to the resulting flags value. a #GParamSpec the #GString to be parsed a #GValue which must hold flags values. A #GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a requisition in the form `"{ width, height }"` for integers %width and %height. %TRUE if @gstring could be parsed and @property_value has been set to the resulting #GtkRequisition. a #GParamSpec the #GString to be parsed a #GValue which must hold boxed values. If the modification time on any previously read file for the default #GtkSettings has changed, discard all style information and then reread all previously read RC files. Use #GtkCssProvider instead. %TRUE if the files were reread. If the modification time on any previously read file for the given #GtkSettings has changed, discard all style information and then reread all previously read RC files. Use #GtkCssProvider instead. %TRUE if the files were reread. a #GtkSettings load whether or not anything changed This function recomputes the styles for all widgets that use a particular #GtkSettings object. (There is one #GtkSettings object per #GdkScreen, see gtk_settings_get_for_screen()); It 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 default font size set by the operating system changes. Note that this function doesn’t affect widgets that have a style set explicitly on them with gtk_widget_set_style(). Use #GtkCssProvider instead. a #GtkSettings Use #GtkCssProvider instead Sets the list of files that GTK+ will read at the end of gtk_init(). Use #GtkStyleContext with a custom #GtkStyleProvider instead A %NULL-terminated list of filenames. Renders an activity indicator (such as in #GtkSpinner). The state %GTK_STATE_FLAG_CHECKED determines whether there is activity going on. a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an arrow pointing to @angle. Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π:  a #GtkStyleContext a #cairo_t arrow angle from 0 to 2 * %G_PI, being 0 the arrow pointing to the north X origin of the render area Y origin of the render area square side for render area Renders the background of an element. Typical background rendering, showing the effect of `background-image`, `border-width` and `border-radius`:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Returns the area that will be affected (i.e. drawn to) when calling gtk_render_background() for the given @context and rectangle. a #GtkStyleContext X origin of the rectangle Y origin of the rectangle rectangle width rectangle height return location for the clip Renders a checkmark (as in a #GtkCheckButton). The %GTK_STATE_FLAG_CHECKED state determines whether the check is on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it should be marked as undefined. Typical checkmark rendering:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an expander (as used in #GtkTreeView and #GtkExpander) in the area defined by @x, @y, @width, @height. The state %GTK_STATE_FLAG_CHECKED determines whether the expander is collapsed or expanded. Typical expander rendering:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a extension (as in a #GtkNotebook tab) in the rectangle defined by @x, @y, @width, @height. The side where the extension connects to is defined by @gap_side. Typical extension rendering:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height side where the gap is Renders a focus indicator on the rectangle determined by @x, @y, @width, @height. Typical focus rendering:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a frame around the rectangle defined by @x, @y, @width, @height. Examples of frame rendering, showing the effect of `border-image`, `border-color`, `border-width`, `border-radius` and junctions:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a frame around the rectangle defined by (@x, @y, @width, @height), leaving a gap on one side. @xy0_gap and @xy1_gap will mean X coordinates for %GTK_POS_TOP and %GTK_POS_BOTTOM gap sides, and Y coordinates for %GTK_POS_LEFT and %GTK_POS_RIGHT. Typical rendering of a frame with a gap:  Use gtk_render_frame() instead. Themes can create gaps by omitting borders via CSS. a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height side where the gap is initial coordinate (X or Y depending on @gap_side) for the gap end coordinate (X or Y depending on @gap_side) for the gap Renders a handle (as in #GtkHandleBox, #GtkPaned and #GtkWindow’s resize grip), in the rectangle determined by @x, @y, @width, @height. Handles rendered for the paned and grip classes:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders the icon in @pixbuf at the specified @x and @y coordinates. This function will render the icon in @pixbuf at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities. You probably want to use gtk_render_icon_surface() instead, if you already have a Cairo surface. a #GtkStyleContext a #cairo_t a #GdkPixbuf containing the icon to draw X position for the @pixbuf Y position for the @pixbuf Renders the icon specified by @source at the given @size, returning the result in a pixbuf. Use gtk_icon_theme_load_icon() instead. a newly-created #GdkPixbuf containing the rendered icon a #GtkStyleContext the #GtkIconSource specifying the icon to render the size (#GtkIconSize) to render the icon at. A size of `(GtkIconSize) -1` means render at the size of the source and don’t scale. Renders the icon in @surface at the specified @x and @y coordinates. a #GtkStyleContext a #cairo_t a #cairo_surface_t containing the icon to draw X position for the @icon Y position for the @incon Draws a text caret on @cr at the specified index of @layout. a #GtkStyleContext a #cairo_t X origin Y origin the #PangoLayout of the text the index in the #PangoLayout the #PangoDirection of the text Renders @layout on the coordinates @x, @y a #GtkStyleContext a #cairo_t X origin Y origin the #PangoLayout to render Renders a line from (x0, y0) to (x1, y1). a #GtkStyleContext a #cairo_t X coordinate for the origin of the line Y coordinate for the origin of the line X coordinate for the end of the line Y coordinate for the end of the line Renders an option mark (as in a #GtkRadioButton), the %GTK_STATE_FLAG_CHECKED state will determine whether the option is on or off, and %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined. Typical option mark rendering:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a slider (as in #GtkScale) in the rectangle defined by @x, @y, @width, @height. @orientation defines whether the slider is vertical or horizontal. Typical slider rendering:  a #GtkStyleContext a #cairo_t X origin of the rectangle Y origin of the rectangle rectangle width rectangle height orientation of the slider Converts a color from RGB space to HSV. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Red Green Blue Return value for the hue component Return value for the saturation component Return value for the value component Appends a specified target to the list of supported targets for a given widget and selection. a #GtkWidget the selection target to add. A unsigned integer which will be passed back to the application. Prepends a table of targets to the list of supported targets for a given widget and selection. a #GtkWidget the selection a table of targets to add number of entries in @targets Remove all targets registered for the given selection for the widget. a #GtkWidget an atom representing a selection Requests the contents of a selection. When received, a “selection-received” signal will be generated. %TRUE if requested succeeded. %FALSE if we could not process request. (e.g., there was already a request in process for this widget). The widget which acts as requestor Which selection to get Form of information desired (e.g., STRING) Time of request (usually of triggering event) In emergency, you could use #GDK_CURRENT_TIME Claims ownership of a given selection for a particular widget, or, if @widget is %NULL, release ownership of the selection. %TRUE if the operation succeeded a #GtkWidget, or %NULL. an interned atom representing the selection to claim timestamp with which to claim the selection Claim ownership of a given selection for a particular widget, or, if @widget is %NULL, release ownership of the selection. TRUE if the operation succeeded the #GdkDisplay where the selection is set new selection owner (a #GtkWidget), or %NULL. an interned atom representing the selection to claim. timestamp with which to claim the selection Removes all handlers and unsets ownership of all selections for a widget. Called when widget is being destroyed. This function will not generally be called by applications. a #GtkWidget Sets the GTK+ debug flags. This is a convenience function for showing an application’s about box. The constructed dialog is associated with the parent window and reused for future invocations of this function. transient parent, or %NULL for none the name of the first property value of first property, followed by more properties, %NULL-terminated A convenience function for launching the default application to show the uri. Like gtk_show_uri_on_window(), but takes a screen as transient parent instead of a window. Note that this function is deprecated as it does not pass the necessary information for helpers to parent their dialog properly, when run from sandboxed applications for example. %TRUE on success, %FALSE on error screen to show the uri on or %NULL for the default screen the uri to show a timestamp to prevent focus stealing This is a convenience function for launching the default application to show the uri. The uri must be of a form understood by GIO (i.e. you need to install gvfs to get support for uri schemes such as http:// or ftp://, as only local files are handled by GIO itself). Typical examples are - `file:///home/gnome/pict.jpg` - `http://www.gnome.org` - `mailto:me@gnome.org` Ideally the timestamp is taken from the event triggering the gtk_show_uri() call. If timestamp is not known you can take %GDK_CURRENT_TIME. This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly. %TRUE on success, %FALSE on error parent window the uri to show a timestamp to prevent focus stealing Registers each of the stock items in @items. If an item already exists with the same stock ID as one of the @items, the old item gets replaced. The stock items are copied, so GTK+ does not hold any pointer into @items and @items can be freed. Use gtk_stock_add_static() if @items is persistent and GTK+ need not copy the array. a #GtkStockItem or array of items number of #GtkStockItem in @items Same as gtk_stock_add(), but doesn’t copy @items, so @items must persist until application exit. a #GtkStockItem or array of #GtkStockItem number of items Retrieves a list of all known stock IDs added to a #GtkIconFactory or registered with gtk_stock_add(). The list must be freed with g_slist_free(), and each string in the list must be freed with g_free(). a list of known stock IDs Fills @item with the registered values for @stock_id, returning %TRUE if @stock_id was known. %TRUE if @item was initialized a stock item name stock item to initialize with values Sets a function to be used for translating the @label of a stock item. If no function is registered for a translation domain, g_dgettext() is used. The function is used for all stock items whose @translation_domain matches @domain. Note that it is possible to use strings different from the actual gettext translation domain of your application for this, as long as your #GtkTranslateFunc uses the correct domain when calling dgettext(). This can be useful, e.g. when dealing with message contexts: |[<!-- language="C" --> GtkStockItem items[] = { { MY_ITEM1, NC_("odd items", "Item 1"), 0, 0, "odd-item-domain" }, { MY_ITEM2, NC_("even items", "Item 2"), 0, 0, "even-item-domain" }, }; gchar * my_translate_func (const gchar *msgid, gpointer data) { gchar *msgctxt = data; return (gchar*)g_dpgettext2 (GETTEXT_PACKAGE, msgctxt, msgid); } ... gtk_stock_add (items, G_N_ELEMENTS (items)); gtk_stock_set_translate_func ("odd-item-domain", my_translate_func, "odd items"); gtk_stock_set_translate_func ("even-item-domain", my_translate_func, "even items"); ]| the translation domain for which @func shall be used a #GtkTranslateFunc data to pass to @func a #GDestroyNotify that is called when @data is no longer needed This function frees a target table as returned by gtk_target_table_new_from_list() a #GtkTargetEntry array the number of entries in the array This function creates an #GtkTargetEntry array that contains the same targets as the passed %list. The returned table is newly allocated and should be freed using gtk_target_table_free() when no longer needed. the new table. a #GtkTargetList return location for the number ot targets in the table Determines if any of the targets in @targets can be used to provide a #GdkPixbuf. %TRUE if @targets include a suitable target for images, otherwise %FALSE. an array of #GdkAtoms the length of @targets whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format Determines if any of the targets in @targets can be used to provide rich text. %TRUE if @targets include a suitable target for rich text, otherwise %FALSE. an array of #GdkAtoms the length of @targets a #GtkTextBuffer Determines if any of the targets in @targets can be used to provide text. %TRUE if @targets include a suitable target for text, otherwise %FALSE. an array of #GdkAtoms the length of @targets Determines if any of the targets in @targets can be used to provide an uri list. %TRUE if @targets include a suitable target for uri lists, otherwise %FALSE. an array of #GdkAtoms the length of @targets Create a simple window with window title @window_title and text contents @dialog_text. The window will quit any running gtk_main()-loop when destroyed, and it will automatically be destroyed upon test function teardown. This testing infrastructure is phased out in favor of reftests. a widget pointer to the newly created GtkWindow. Title of the window to be displayed. Text inside the window to be displayed. This function wraps g_object_new() for widget types. It’ll automatically show all created non window widgets, also g_object_ref_sink() them (to keep them alive across a running test) and set them up for destruction during the next test teardown phase. This testing infrastructure is phased out in favor of reftests. a newly created widget. a valid widget type. Name of first property to set or %NULL value to set the first property to, followed by more name-value pairs, terminated by %NULL Create a window with window title @window_title, text contents @dialog_text, and a number of buttons, according to the paired argument list given as @... parameters. Each button is created with a @label and a ::clicked signal handler that incremrents the integer stored in @nump. The window will be automatically shown with gtk_widget_show_now() after creation, so when this function returns it has already been mapped, resized and positioned on screen. The window will quit any running gtk_main()-loop when destroyed, and it will automatically be destroyed upon test function teardown. This testing infrastructure is phased out in favor of reftests. a widget pointer to the newly created GtkWindow. Title of the window to be displayed. Text inside the window to be displayed. %NULL terminated list of (const char *label, int *nump) pairs. This function will search @widget and all its descendants for a GtkLabel widget with a text string matching @label_pattern. The @label_pattern may contain asterisks “*” and question marks “?” as placeholders, g_pattern_match() is used for the matching. Note that locales other than "C“ tend to alter (translate” label strings, so this function is genrally only useful in test programs with predetermined locales, see gtk_test_init() for more details. a GtkLabel widget if any is found. Valid label or container widget. Shell-glob pattern to match a label string. This function will search siblings of @base_widget and siblings of its ancestors for all widgets matching @widget_type. Of the matching widgets, the one that is geometrically closest to @base_widget will be returned. The general purpose of this function is to find the most likely “action” widget, relative to another labeling widget. Such as finding a button or text entry widget, given its corresponding label widget. a widget of type @widget_type if any is found. Valid widget, part of a widget hierarchy Type of a aearched for sibling widget This function will search the descendants of @widget for a widget of type @widget_type that has a label matching @label_pattern next to it. This is most useful for automated GUI testing, e.g. to find the “OK” button in a dialog and synthesize clicks on it. However see gtk_test_find_label(), gtk_test_find_sibling() and gtk_test_widget_click() for possible caveats involving the search of such widgets and synthesizing widget events. a valid widget if any is found or %NULL. Container widget, usually a GtkWindow. Shell-glob pattern to match a label string. Type of a aearched for label sibling widget. This function is used to initialize a GTK+ test program. It will in turn call g_test_init() and gtk_init() to properly initialize the testing framework and graphical toolkit. It’ll also set the program’s locale to “C” and prevent loading of rc files and Gtk+ modules. This is done to make tets program environments as deterministic as possible. Like gtk_init() and g_test_init(), any known arguments will be processed and stripped from @argc and @argv. Address of the `argc` parameter of the main() function. Changed if any arguments were handled. Address of the `argv` parameter of main(). Any parameters understood by g_test_init() or gtk_init() are stripped before return. currently unused Return the type ids that have been registered after calling gtk_test_register_all_types(). 0-terminated array of type ids location to store number of types Force registration of all core Gtk+ and Gdk object types. This allowes to refer to any of those object types via g_type_from_name() after calling this function. Retrive the literal adjustment value for GtkRange based widgets and spin buttons. Note that the value returned by this function is anything between the lower and upper bounds of the adjustment belonging to @widget, and is not a percentage as passed in to gtk_test_slider_set_perc(). This testing infrastructure is phased out in favor of reftests. gtk_adjustment_get_value (adjustment) for an adjustment belonging to @widget. valid widget pointer. This function will adjust the slider position of all GtkRange based widgets, such as scrollbars or scales, it’ll also adjust spin buttons. The adjustment value of these widgets is set to a value between the lower and upper limits, according to the @percentage argument. This testing infrastructure is phased out in favor of reftests. valid widget pointer. value between 0 and 100. This function will generate a @button click in the upwards or downwards spin button arrow areas, usually leading to an increase or decrease of spin button’s value. This testing infrastructure is phased out in favor of reftests. whether all actions neccessary for the button click simulation were carried out successfully. valid GtkSpinButton widget. Number of the pointer button for the event, usually 1, 2 or 3. %TRUE for upwards arrow click, %FALSE for downwards arrow click. Retrive the text string of @widget if it is a GtkLabel, GtkEditable (entry and text widgets) or GtkTextView. This testing infrastructure is phased out in favor of reftests. new 0-terminated C string, needs to be released with g_free(). valid widget pointer. Set the text string of @widget to @string if it is a GtkLabel, GtkEditable (entry and text widgets) or GtkTextView. This testing infrastructure is phased out in favor of reftests. valid widget pointer. a 0-terminated C string This function will generate a @button click (button press and button release event) in the middle of the first GdkWindow found that belongs to @widget. For windowless widgets like #GtkButton (which returns %FALSE from gtk_widget_get_has_window()), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the button click location, see gdk_test_simulate_button() for details. This testing infrastructure is phased out in favor of reftests. whether all actions neccessary for the button click simulation were carried out successfully. Widget to generate a button click on. Number of the pointer button for the event, usually 1, 2 or 3. Keyboard modifiers the event is setup with. This function will generate keyboard press and release events in the middle of the first GdkWindow found that belongs to @widget. For windowless widgets like #GtkButton (which returns %FALSE from gtk_widget_get_has_window()), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the key press location, see gdk_test_simulate_key() for details. whether all actions neccessary for the key event simulation were carried out successfully. Widget to generate a key press and release on. A Gdk keyboard value. Keyboard modifiers the event is setup with. Enters the main loop and waits for @widget to be “drawn”. In this context that means it waits for the frame clock of @widget to have run a full styling, layout and drawing cycle. This function is intended to be used for syncing with actions that depend on @widget relayouting or on interaction with the display server. the widget to wait for Obtains a @tree_model and @path from selection data of target type %GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler. This function can only be used if @selection_data originates from the same process that’s calling this function, because a pointer to the tree model is being passed around. If you aren’t in the same process, then you'll get memory corruption. In the #GtkTreeDragDest drag_data_received handler, you can assume that selection data of type %GTK_TREE_MODEL_ROW is in from the current process. The returned path must be freed with gtk_tree_path_free(). %TRUE if @selection_data had target type %GTK_TREE_MODEL_ROW and is otherwise valid a #GtkSelectionData a #GtkTreeModel row in @tree_model Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-deleted signal. a #GObject the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::row-inserted signal. a #GObject the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the #GtkTreeModel::rows-reordered signal. a #GObject the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows Sets selection data of target type %GTK_TREE_MODEL_ROW. Normally used in a drag_data_get handler. %TRUE if the #GtkSelectionData had the proper target type to allow us to set a tree row some #GtkSelectionData a #GtkTreeModel a row in @tree_model All this function does it to return %TRUE. This can be useful for example if you want to inhibit the deletion of a window. Of course you should not do this as the user expects a reaction from clicking the close icon of the window... ## A persistent window |[<!-- language="C" --> #include <gtk/gtk.h> int main (int argc, char **argv) { GtkWidget *win, *but; const char *text = "Close yourself. I mean it!"; gtk_init (&argc, &argv); win = gtk_window_new (GTK_WINDOW_TOPLEVEL); g_signal_connect (win, "delete-event", G_CALLBACK (gtk_true), NULL); g_signal_connect (win, "destroy", G_CALLBACK (gtk_main_quit), NULL); but = gtk_button_new_with_label (text); g_signal_connect_swapped (but, "clicked", G_CALLBACK (gtk_object_destroy), win); gtk_container_add (GTK_CONTAINER (win), but); gtk_widget_show_all (win); gtk_main (); return 0; } ]| %TRUE Binds a callback function defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_callback_full() function. a #GtkWidgetClass the callback symbol Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName instance structure. a #GtkWidgetClass the type name of this widget name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class, and also makes it available as an internal child in GtkBuilder, under the name @member_name. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName instance structure. a #GtkWidgetClass the type name, in CamelCase name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class, and also makes it available as an internal child in GtkBuilder, under the name @member_name. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName private data structure. a #GtkWidgetClass the type name, in CamelCase name of the instance private member on the private struct for @data_type Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName private data structure (it uses G_PRIVATE_OFFSET(), so the private struct must be added with G_ADD_PRIVATE()). a #GtkWidgetClass the type name of this widget name of the instance private member in the private struct for @data_type