A <structname>GtkAllocation</structname> of a widget represents region
which has been allocated to the widget by its parent. It is a subregion
of its parents allocation. See <xref linkend="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 <literal>About</literal> option from
the <literal>Help</literal> menu. All parts of the dialog are optional.
About dialog often contain links and email addresses. GtkAboutDialog
displays these as clickable links. By default, it calls gtk_show_uri()
when a user clicks one. The behaviour can be overridden with the
#GtkAboutDialog::activate-link signal.
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 <literal>_("About %s")</literal>
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:
<informalexample><programlisting>
gtk_show_about_dialog (NULL,
"program-name", "ExampleCode",
"logo", example_logo,
"title" _("About ExampleCode"),
NULL);
</programlisting></informalexample>
Creates a new #GtkAboutDialog.
a newly created #GtkAboutDialog
Returns the string which are displayed in the artists tab
of the secondary credits dialog.
%NULL-terminated string array containing the artists. The array is
owned by the about dialog and must not be modified.
A
Returns the string which are displayed in the authors tab
of the secondary credits dialog.
%NULL-terminated string array containing the authors. The array is
owned by the about dialog and must not be modified.
A
Returns the comments string.
dialog and must not be modified.
The comments. The string is owned by the about
Returns the copyright string.
dialog and must not be modified.
The copyright string. The string is owned by the about
Returns the string which are displayed in the documenters
tab of the secondary credits dialog.
%NULL-terminated string array containing the documenters. The
array is owned by the about dialog and must not be modified.
A
Returns the license information.
dialog and must not be modified.
The license information. The string is owned by the about
Retrieves the license set using gtk_about_dialog_set_license_type()
a #GtkLicense value
Returns the pixbuf displayed as logo in the about dialog.
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.
the pixbuf displayed as logo. The
Returns the icon name displayed as logo in the about dialog.
owned by the dialog. If you want to keep a reference
to it, you have to call g_strdup() on it.
the icon name displayed as logo. The string is
Returns the program name displayed in the about dialog.
dialog and must not be modified.
The program name. The string is owned by the about
Returns the translator credits string which is displayed
in the translators tab of the secondary credits dialog.
owned by the about dialog and must not be modified.
The translator credits string. The string is
Returns the version string.
dialog and must not be modified.
The version string. The string is owned by the about
Returns the website URL.
dialog and must not be modified.
The website URL. The string is owned by the about
Returns the label used for the website link.
owned by the about dialog and must not be modified.
The label used for the website link. The string is
Returns whether the license text in @about is
automatically wrapped.
%TRUE if the license text is wrapped
Sets the strings which are displayed in the artists tab
of the secondary credits dialog.
a %NULL-terminated array of strings
Sets the strings which are displayed in the authors tab
of the secondary credits dialog.
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 comments string
Sets the copyright string to display in the about dialog.
This should be a short string of one or two lines.
(allow-none) the copyright string
Sets the strings which are displayed in the documenters tab
of the secondary credits dialog.
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.
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().
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 #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.
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().
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:
|[
gtk_about_dialog_set_translator_credits (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.
the translator credits
Sets the version string to display in the about dialog.
the version string
Sets the URL to use for the website link.
a URL string starting with "http://"
Sets the label to be used for the website link.
the label used for the website link
Sets whether the license text in @about is
automatically wrapped.
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 this is not set, it defaults to
gtk_window_get_default_icon_list().
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().
%TRUE if the link has been activated
the URI that is activated
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 <firstterm>accelerators</firstterm> are different from
<firstterm>mnemonics</firstterm>. 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
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.
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
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().
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 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
key value of the accelerator
modifier combination of the accelerator
Finds the first entry in an accelerator group for which
the key of the first entry passing
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().
%FALSE otherwise.
%TRUE if there are 1 or more locks on the @accel_group,
Gets a #GdkModifierType representing the mask for this
the modifier mask for this accel group.
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.
Queries an accelerator group for all entries matching @accel_key and
an array of owned by GTK+ and must not be freed.
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.
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 a #GtkAccelGroupEntry
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 #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an
accelerator key on the right of the label text, e.g. 'Ctl+S'.
It is commonly used in menus to show the keyboard short-cuts for commands.
The accelerator key to display is not set explicitly.
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 'Ctl+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 'Ctl+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.
<example>
<title>Creating a simple menu item with an accelerator key.</title>
<programlisting>
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_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
</programlisting>
</example>
Creates a new #GtkAccelLabel.
a new #GtkAccelLabel.
the label string. Must be non-%NULL.
Fetches the widget monitored by this accelerator label. See
gtk_accel_label_set_accel_widget().
the object monitored by the accelerator label, or %NULL.
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).
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.
Sets the closure to be monitored by this accelerator label. The closure
must be connected to an accelerator group; see gtk_accel_group_connect().
the closure to monitor for accelerator changes.
Sets the widget to be monitored by this accelerator label.
the widget to be monitored.
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.
Accelerator is uniquely defined by:
<itemizedlist>
<listitem><para>accelerator path</para></listitem>
<listitem><para>accelerator key</para></listitem>
<listitem><para>accelerator modifiers</para></listitem>
</itemizedlist>
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 <link
linkend="monitoring-changes">Monitoring changes</link> for additional
details.
<refsect2 id="manipulating-accelerators">
<title>Manipulating accelerators</title>
<para>
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().
</para>
</refsect2>
<refsect2 id="saving-and-loading">
<title>Saving and loading accelerator maps</title>
<para>
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().
</para>
</refsect2>
<refsect2 id="monitoring-changes">
<title>Monitoring changes</title>
<para>
#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.
</para>
</refsect2>
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().
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,
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
#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::<replaceable>accel_path</replaceable>.
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)
This function specifies the callback function to be called when the widget
corresponding to a GtkAccessible is destroyed.
This function specifies the callback function to be called when the widget
corresponding to a GtkAccessible is destroyed.
Gets the #GtkWidget corresponding to the #GtkAccessible. The returned widget
does not have a reference added, so you do not need to unref it.
the #GtkAccessible, or %NULL.
pointer to the #GtkWidget corresponding to
Sets the #GtkWidget corresponding to the #GtkAccessible.
a #GtkWidget
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:
<itemizedlist>
<listitem><para>a name (not translated, for path lookup)</para></listitem>
<listitem><para>a label (translated, for display)</para></listitem>
<listitem><para>an accelerator</para></listitem>
<listitem><para>whether label indicates a stock id</para></listitem>
<listitem><para>a tooltip (optional, translated)</para></listitem>
<listitem><para>a toolbar label (optional, shorter than label)</para></listitem>
</itemizedlist>
The action will also have some state information:
<itemizedlist>
<listitem><para>visible (shown/hidden)</para></listitem>
<listitem><para>sensitive (enabled/disabled)</para></listitem>
</itemizedlist>
Apart from regular actions, there are <link linkend="GtkToggleAction">toggle
actions</link>, which can be toggled between two states and <link
linkend="GtkRadioAction">radio actions</link>, 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 <xref linkend="XML-UI"/> for information on allowed action
names.
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.
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.
action, or %NULL.
the menu item provided by the
Creates a menu item widget that proxies for the given action.
a menu item connected to the action.
Creates a toolbar item widget that proxies for the given action.
a toolbar item connected to the action.
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.
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).
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.
This function is intended for use by action implementations to
create icons displayed in the proxy widgets.
a widget that displays the icon for this action.
the size of the icon 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.
action, or %NULL.
the menu item provided by the
Creates a menu item widget that proxies for the given action.
a menu item connected to the action.
Creates a toolbar item widget that proxies for the given action.
a toolbar item connected to the action.
Undoes the effect of one call to gtk_action_connect_accelerator().
Returns the accel closure for this action.
returned closure is owned by GTK+ and must not be unreffed
or modified.
the accel closure for this action. The
Returns the accel path for this action.
if none is set. The returned string is owned by GTK+
and must not be freed or modified.
the accel path for this action, or %NULL
Returns whether @action<!-- -->'s menu item proxies will ignore the
#GtkSettings:gtk-menu-images setting and always show their image,
if available.
%TRUE if the menu item proxies will always show their image
Gets the gicon of @action.
The action's #GIcon if one is set.
Gets the icon name of @action.
the icon name
Checks whether @action is important or not
whether @action is important
Gets the label text of @action.
the label text
Returns the name of the action.
be freed.
the name of the action. The string belongs to GTK+ and should not
Returns the proxy widgets for an action.
See also gtk_activatable_get_related_action().
and must not be modified.
a #GSList of proxy widgets. The list is owned by GTK+
Returns whether the action itself is sensitive. Note that this doesn't
necessarily mean effective sensitivity. See gtk_action_is_sensitive()
for that.
%TRUE if the action itself is sensitive.
Gets the short label text of @action.
the short label text.
Gets the stock id of @action.
the stock id
Gets the tooltip text of @action.
the tooltip text
Returns whether the action itself is visible. Note that this doesn't
necessarily mean effective visibility. See gtk_action_is_sensitive()
for that.
%TRUE if the action itself is visible.
Checks whether @action is visible when horizontal
whether @action is visible when horizontal
Checks whether @action is visible when horizontal
whether @action is visible when horizontal
Returns whether the action is effectively sensitive.
are both sensitive.
%TRUE if the action and its associated action group
Returns whether the action is effectively visible.
are both visible.
%TRUE if the action and its associated action group
Sets the #GtkAccelGroup in which the accelerator for this action
will be installed.
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().
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.
%TRUE if menuitem proxies should always show their image
Sets the icon of @action.
the #GIcon to set
Sets the icon name on @action
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.
%TRUE to make the action important
Sets the label of @action.
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.
%TRUE to make the action sensitive
Sets a shorter label text on @action.
the label text to set
Sets the stock id on @action
the stock id
Sets the tooltip text on @action
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.
%TRUE to make the action visible
Sets whether @action is visible when horizontal
whether the action is visible horizontally
Sets whether @action is visible when vertical
whether the action is visible vertically
Reenable activation signals from the action
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.
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.
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.
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.
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.
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.
When %TRUE, toolitem proxies for this action are represented in the
toolbar overflow menu.
The "activate" signal is emitted when the action is activated.
a menu item connected to the action.
a toolbar item connected to the action.
the menu item provided by the
#GtkActionEntry structs are used with gtk_action_group_add_actions() to
construct actions.
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.
</para>
<para id="Action-Accel">
Accelerators are handled by the GTK+ accelerator map. All actions are
assigned an accelerator path (which normally has the form
<literal><Actions>/group-name/action-name</literal>)
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.
<refsect2 id="GtkActionGroup-BUILDER-UI">
<title>GtkActionGroup as GtkBuildable</title>
<para>
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.
</para>
<example>
<title>A #GtkDialog UI definition fragment.</title>
<programlisting><![CDATA[
<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>
]]></programlisting>
</example>
</refsect2>
Creates a new #GtkActionGroup object. The name of the action group
is used when associating <link linkend="Action-Accel">keybindings</link>
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 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
<literal>gtk_action_group_add_action_with_accel (..., NULL)</literal>.
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
<literal><Actions>/<replaceable>group-name</replaceable>/<replaceable>action-name</replaceable></literal>.
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
<literal><Actions>/<replaceable>group-name</replaceable>/<replaceable>action-name</replaceable></literal>.
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.
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
<literal><Actions>/<replaceable>group-name</replaceable>/<replaceable>action-name</replaceable></literal>.
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.
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
<literal><Actions>/<replaceable>group-name</replaceable>/<replaceable>action-name</replaceable></literal>.
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.
an array of toggle action descriptions
the number of entries
data to pass to the action callbacks
destroy notification callback for @user_data
Looks up an action in the action group by name.
the action, or %NULL if no action by that name exists
the name of the action
Gets the name of the action group.
the name of 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.
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.
Lists the actions in the action group.
an allocated list of the action objects in the action group
Removes an action object from the action group.
an action
Changes the sensitivity of @action_group
new sensitivity
Sets a function to be used for translating the @label and @tooltip of
#GtkActionGroupEntry<!-- -->s 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 #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
gtk_action_group_add_actions().
If you're not using gettext() for localization, see
gtk_action_group_set_translate_func().
the translation domain to use for g_dgettext() calls
Changes the visible of @action_group.
new visiblity
Translates a string using the specified translate_func(). This
is mainly intended for language bindings.
the translation of @string
a string
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
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
This is intended for #GtkUIManager to proxy the signal and provide global
notification just before any action is activated.
the action
the action, or %NULL if no action by that name exists
the name of the action
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.
<refsect2>
<title>Implementing GtkActivatable</title>
<para>
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.
</para>
<example>
<title>A class fragment implementing #GtkActivatable</title>
<programlisting><![CDATA[
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));
...
}]]></programlisting>
</example>
</refsect2>
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.
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.
<note><para>Be careful to call this before setting the local
copy of the #GtkAction property, since this function uses
gtk_activatable_get_action() to retrieve the previous action</para></note>
the #GtkAction to set
Gets the related #GtkAction for @activatable.
the related #GtkAction if one is set.
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.
Sets the related action on the @activatable object.
<note><para>#GtkActivatable implementors need to handle the #GtkActivatable:related-action
property and call gtk_activatable_do_set_related_action() when it changes.</para></note>
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
<note><para>#GtkActivatable implementors need to handle the
#GtkActivatable:use-action-appearance property and call
gtk_activatable_sync_action_properties() to update @activatable
if needed.</para></note>
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.
the related #GtkAction or %NULL
The action that this activatable will activate and receive
updates from for various states and possibly appearance.
<note><para>#GtkActivatable implementors need to handle the this property and
call gtk_activatable_do_set_related_action() when it changes.</para></note>
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.
<note><para>#GtkActivatable implementors need to handle this property
and call gtk_activatable_sync_action_properties() on the activatable
widget when it changes.</para></note>
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
#GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale).
The #GtkAdjustment object does not update the value itself. Instead
it is left up to the owner of the #GtkAdjustment to control the value.
The owner of the #GtkAdjustment typically calls the
gtk_adjustment_value_changed() and gtk_adjustment_changed() functions
after changing the value and its bounds. This results in the emission of the
#GtkAdjustment::value_changed or #GtkAdjustment::changed signal respectively.
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 fields other than the 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 field.
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 fields other than the value.
Updates the #GtkAdjustment #GtkAdjustment.value 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::changed signal will be emitted if the value is changed.
the lower value.
the upper value.
Sets all properties of the adjustment at once.
Use this function to avoid multiple emissions of the "changed"
signal. See gtk_adjustment_set_lower() for an alternative way
of compressing multiple emissions of "changed" into one.
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.
Retrieves the page increment of the adjustment.
The current page increment of the adjustment.
Retrieves the page size of the adjustment.
The current page size of the adjustment.
Retrieves the step increment of the adjustment.
The current step increment of the adjustment.
Retrieves the maximum value of the adjustment.
The current maximum value of the adjustment.
Gets the current value of the adjustment. See
gtk_adjustment_set_value ().
The current value of the adjustment.
Sets the minimum value of the adjustment.
When setting multiple adjustment properties via their individual
setters, multiple "changed" signals will be emitted. However, since
the emission of the "changed" signal is tied to the emission of the
"GObject::notify" signals of the changed properties, it's possible
to compress the "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 "changed" emissions.
the new minimum value
Sets the page increment of the adjustment.
See gtk_adjustment_set_lower() about how to compress multiple
emissions of the "changed" signal when setting multiple adjustment
properties.
the new page increment
Sets the page size of the adjustment.
See gtk_adjustment_set_lower() about how to compress multiple
emissions of the "changed" signal when setting multiple adjustment
properties.
the new page size
Sets the step increment of the adjustment.
See gtk_adjustment_set_lower() about how to compress multiple
emissions of the "changed" signal when setting multiple adjustment
properties.
the new step increment
Sets the maximum value of the adjustment.
Note that values will be restricted by
<literal>upper - page-size</literal> if the page-size
property is nonzero.
See gtk_adjustment_set_lower() about how to compress multiple
emissions of the "changed" signal when setting multiple adjustment
properties.
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.
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 field.
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
<literal>upper - page-size</literal> if the page-size
property is nonzero.
The value of the adjustment.
Emitted when one or more of the #GtkAdjustment fields have been changed,
other than the value field.
Emitted when the #GtkAdjustment value field has been changed.
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.
The #GtkAlignment widget controls the alignment and size of its child widget.
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.
<note>
<para>
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 #GtkAlignment should not be used in new code.
</para>
</note>
Creates a new #GtkAlignment.
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 ().
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.
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.
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.
The padding to insert at the left of the widget.
The padding to insert at the right of the widget.
The padding to insert at the top of the widget.
#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.
Returns the currently selected application.
application, or %NULL if none is selected. Free with g_object_unref()
a #GAppInfo for the currently selected
Returns the current value of the #GtkAppChooser:content-type property.
the content type of @self. Free with g_free()
Reloads the list of applications.
The content type of the #GtkAppChooser object.
The #GtkAppChooserButton is a widget that lets the user select
an application. It implements the #GtkAppChooser interface.
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 ::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().
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.
Returns the text to display at the top of the dialog.
case a default text is displayed
the text to display at the top of the dialog, or %NULL, in which
Returns the current value of the #GtkAppChooserButton:show-dialog-item
property.
the value of #GtkAppChooserButton:show-dialog-item
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.
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 string containing Pango markup
Sets whether the dropdown menu of this button should show an
entry to trigger a #GtkAppChooserDialog.
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-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
#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.
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.
case a default text is displayed
the text to display at the top of the dialog, or %NULL, in which
Returns the #GtkAppChooserWidget of this dialog.
the #GtkAppChooserWidget of @self
Sets the text to display at the top of the dialog.
If the heading is not set, the dialog displays a default text.
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.
#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.
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
Returns the current value of the #GtkAppChooserWidget:show-all
property.
the value of #GtkAppChooserWidget:show-all
Returns the current value of the #GtkAppChooserWidget:show-default
property.
the value of #GtkAppChooserWidget:show-default
Returns the current value of the #GtkAppChooserWidget:show-fallback
property.
the value of #GtkAppChooserWidget:show-fallback
Returns the current value of the #GtkAppChooserWidget:show-other
property.
the value of #GtkAppChooserWidget:show-other
Returns the current value of the #GtkAppChooserWidget:show-recommended
property.
the value of #GtkAppChooserWidget:show-recommended
Sets the text that is shown if there are not applications
that can handle the content type.
the new value for #GtkAppChooserWidget:default-text
Sets whether the app chooser should show all applications
in a flat list.
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.
the new value for #GtkAppChooserWidget:show-default
Sets whether the app chooser should show related applications
for the content type in a separate section.
the new value for #GtkAppChooserWidget:show-fallback
Sets whether the app chooser should show applications
which are unrelated to the content type.
the new value for #GtkAppChooserWidget:show-other
Sets whether the app chooser should show recommended applications
for the content type in a separate section.
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 related applications. If %FALSE, the
related 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
#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, provides some basic scriptability by exporting 'actions',
and manages a list of toplevel windows whose life-cycle is automatically
tied to the life-cycle of your application.
<example id="gtkapplication"><title>A simple application</title>
<programlisting>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bloatpad.c">
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
</xi:include>
</programlisting>
</example>
Creates a new #GtkApplication instance.
This function calls g_type_init() for you. gtk_init() is called
as soon as the application gets registered as the primary instance.
The application id must be valid. See g_application_id_is_valid().
a new #GtkApplication instance
the application id
the application flags
Adds a window from @application.
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 #GtkWindow
Gets a list of the #GtkWindow<!-- -->s associated with @application.
The list that is returned should not be modified in any way.
a #GList of #GtkWindow
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 #GtkWindow
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
ammended 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().
Creates a new #GtkArrow widget.
the new #GtkArrow widget.
a valid #GtkArrowType.
a valid #GtkShadowType.
Sets the direction and style of the #GtkArrow, @arrow.
a valid #GtkArrowType.
a valid #GtkShadowType.
Used to specify the placement of scroll arrows in scrolling menus.
Used to indicate the direction in which a #GtkArrow should point.
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.
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 (left aligned) to 1.0 (right 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.
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 (left aligned) to 1.0 (right aligned)
The desired aspect ratio.
If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child.
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 <link linkend="GtkAssistantPageType">type</link> of each page, in
addition to state information like the page
<link linkend="gtk-assistant-set-page-complete">completion</link> and
<link linkend="gtk-assistant-commit">committed</link> 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.
<refsect2 id="GtkAssistant-BUILDER-UI">
<title>GtkAssistant as GtkBuildable</title>
<para>
The GtkAssistant implementation of the GtkBuildable interface exposes the
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.
</para>
</refsect2>
Creates a new #GtkAssistant.
a newly created #GtkAssistant
Adds a widget to the action area of a #GtkAssistant.
a #GtkWidget
Appends a page to the @assistant.
the index (starting at 0) of the inserted page
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.
Returns the page number of the current page
page in the @assistant, if the @assistant has no pages,
-1 will be returned
The index (starting from 0) of the current
Returns the number of pages in the @assistant
the number of pages in the @assistant
Returns the child widget contained in page number @page_num.
if @page_num is out of bounds
the child widget, or %NULL
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 page of @assistant
Gets the header image for @page.
or %NULL if there's no header image for the page
the header image for @page,
a page of @assistant
Gets the header image for @page.
or %NULL if there's no side image for the page
the side image for @page,
a page of @assistant
Gets the title for @page.
the title for @page
a page of @assistant
Gets the page type of @page.
the page type of @page
a page of @assistant
Inserts a page in the @assistant at a given position.
the index (starting from 0) of the inserted page
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.
Prepends a page to the @assistant.
the index (starting at 0) of the inserted page
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.
Removes a widget from the action area of a #GtkAssistant.
a #GtkWidget
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().
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.
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 page of @assistant
the completeness status of the page
Sets a header image for @page.
This image is displayed in the header area of the assistant
when @page is the current page.
a page of @assistant
the new header image @page
Sets a header image for @page.
This image is displayed in the side area of the assistant
when @page is the current page.
a page of @assistant
the new header 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 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 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.
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 preparation which are necessary before showing @page.
the current page
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.
Denotes the expansion properties that a widget will have when it (or its
parent) is resized.
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.
pointer to child of the #GtkBin
A #GtkBindingArg holds the data associated with
an argument for a key binding signal emission as
stored in #GtkBindingSignal.
Each key binding element of a binding sets binding list is
represented by a GtkBindingEntry.
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.
Find a key binding matching @keyval and @modifiers within
%TRUE if a binding was found and activated
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.
path type the pattern applies to
the actual match pattern
binding priority
<anchor id="keybinding-signals"/>
A GtkBindingSignal stores the necessary information to
activate a widget in response to a key press via a signal
emission.
A struct that specifies a border around a rectangular area
that can be of different width on each side.
Allocates a new #GtkBorder structure and initializes its elements to zero.
a newly allocated #GtkBorder. Free with gtk_border_free()
Copies a #GtkBorder structure.
a copy of @border_.
Frees a #GtkBorder structure.
Describes how the border of a UI element should be rendered.
GtkBox is an widget which encapsulates functionality for a
particular kind of container, one that organizes a variable number of
widgets into a rectangular area. GtkBox has a number of derived
classes, e.g. #GtkHBox and #GtkVBox.
The rectangular area of a GtkBox is organized into either a single row
or a single column of child widgets depending upon whether the box is
of type #GtkHBox or #GtkVBox, respectively. Thus, all children of a
GtkBox are allocated one dimension in common, which is the height of a
row, or the width of a column.
GtkBox uses a notion of <emphasis>packing</emphasis>. Packing
refers to adding widgets with reference to a particular position in a
#GtkContainer. For a GtkBox, there are two reference positions: the
<emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.
For a #GtkVBox, the start is defined as the top of the box and the end is
defined as the bottom. For a #GtkHBox 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 #GtkBox:expand and #GtkBox:fill.
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 <emphasis>between</emphasis> the children, while
padding added by gtk_box_pack_start() or gtk_box_pack_end() is added
<emphasis>on either side</emphasis> 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 #GtkBox:expand,
#GtkBox:fill and #GtkBox:padding child properties.
Use gtk_box_query_child_packing() to query these fields.
<note>
<para>
Note that a single-row or single-column #GtkGrid provides exactly the
same functionality as #GtkBox.
</para>
</note>
Creates a new #GtkBox.
a new #GtkBox.
the box's orientation.
the number of pixels to place by default between children.
Returns whether the box is homogeneous (all children are the
same size). See gtk_box_set_homogeneous().
%TRUE if the box is homogeneous.
Gets the value set by gtk_box_set_spacing().
spacing between children
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.
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 #GtkHBox and the full width of a #GtkVBox. 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
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.
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 #GtkHBox and the full width of a #GtkVBox. 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
Obtains information about how @child is packed into @box.
the #GtkWidget of the child to query
pointer to return location for #GtkBox:expand child property
pointer to return location for #GtkBox:fill child property
pointer to return location for #GtkBox:padding child property
pointer to return location for #GtkBox:pack-type child property
Moves @child to a new @position in the list of @box children.
The list is the <structfield>children</structfield> field of
#GtkBox-struct, and contains both 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.
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 way @child is packed into @box.
the #GtkWidget of the child to set
the new value of the #GtkBox:expand child property
the new value of the #GtkBox:fill child property
the new value of the #GtkBox:padding child property
the new value of the #GtkBox: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 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.
the number of pixels to put between children
GtkBuildable allows objects to extend and customize thier deserialization
from <link linkend="BUILDER-UI">GtkBuilder UI descriptions</link>.
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
<function>gtk_buildable_...</function> functions.
<note><para>An object only needs to implement this interface if it needs
to extend the #GtkBuilder format or run any extra routines at deserialization time</para></note>
Adds a child to @buildable. @type is an optional string
describing how the child should be added.
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
#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 #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.
#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>.
if it doesn't.
%TRUE if a object has a custom implementation, %FALSE
a #GtkBuilder used to construct this object
child object or %NULL for non-child tags
name of tag
a #GMarkupParser structure 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 #GtkBuilder
name of child
Gets the name of the @buildable object.
#GtkBuilder sets the name based on the the
<link linkend="BUILDER-UI">GtkBuilder UI definition</link>
used to construct the @buildable.
the name set with gtk_buildable_set_name()
Called when the builder finishes the parsing of a
<link linkend="BUILDER-UI">GtkBuilder UI definition</link>.
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 #GtkBuilder
Sets the property name @name to @value on the @buildable object.
a #GtkBuilder
name of property
value of property
Sets the name of the @buildable object.
name to set
Adds a child to @buildable. @type is an optional string
describing how the child should be added.
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
#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 #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.
#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>.
if it doesn't.
%TRUE if a object has a custom implementation, %FALSE
a #GtkBuilder used to construct this object
child object or %NULL for non-child tags
name of tag
a #GMarkupParser structure 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 #GtkBuilder
name of child
Gets the name of the @buildable object.
#GtkBuilder sets the name based on the the
<link linkend="BUILDER-UI">GtkBuilder UI definition</link>
used to construct the @buildable.
the name set with gtk_buildable_set_name()
Called when the builder finishes the parsing of a
<link linkend="BUILDER-UI">GtkBuilder UI definition</link>.
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 #GtkBuilder
Sets the property name @name to @value on the @buildable object.
a #GtkBuilder
name of property
value of property
Sets the name of the @buildable object.
name to set
The GtkBuildableIface interface contains method that are
necessary to allow #GtkBuilder to construct an object from
a GtkBuilder UI definition.
name to set
the name set with gtk_buildable_set_name()
a #GtkBuilder
child to add
kind of child or %NULL
a #GtkBuilder
name of property
value of property
the constructed child
#GtkBuilder used to construct this object
name of child to construct
%TRUE if a object has a custom implementation, %FALSE
a #GtkBuilder used to construct this object
child object or %NULL for non-child tags
name of tag
a #GMarkupParser structure to fill in
return location for user data that will be passed in to parser functions
#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 #GtkBuilder
child object or %NULL for non-child tags
the name of the tag
user data created in custom_tag_start
a #GtkBuilder
the internal child of the buildable object
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 pass a
description to a GtkBuilder, call gtk_builder_add_from_file() or
gtk_builder_add_from_string(). These functions can be called multiple
times; the builder merges the content of all descriptions.
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.
<refsect2 id="BUILDER-UI">
<title>GtkBuilder UI Definitions</title>
<para>
GtkBuilder parses textual descriptions of user interfaces which are specified
in an XML format which can be roughly described by the DTD below. We refer to
these descriptions as <firstterm>GtkBuilder UI definitions</firstterm> or
just <firstterm>UI definitions</firstterm> if the context is clear. Do not
confuse GtkBuilder UI Definitions with
<link linkend="XML-UI">GtkUIManager UI Definitions</link>, which are more
limited in scope.
</para>
<programlisting><![CDATA[
<!ELEMENT interface (requires|object)* >
<!ELEMENT object (property|signal|child|ANY)* >
<!ELEMENT property PCDATA >
<!ELEMENT signal EMPTY >
<!ELEMENT requires EMPTY >
<!ELEMENT child (object|ANY*) >
<!ATTLIST interface domain #IMPLIED >
<!ATTLIST object id #REQUIRED
class #REQUIRED
type-func #IMPLIED
constructor #IMPLIED >
<!ATTLIST requires lib #REQUIRED
version #REQUIRED >
<!ATTLIST property name #REQUIRED
translatable #IMPLIED
comments #IMPLIED
context #IMPLIED >
<!ATTLIST signal name #REQUIRED
handler #REQUIRED
after #IMPLIED
swapped #IMPLIED
object #IMPLIED
last_modification_time #IMPLIED >
<!ATTLIST child type #IMPLIED
internal-child #IMPLIED >
]]></programlisting>
<para>
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 <function>_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
<function>_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 must 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.
</para>
<note><para>
Prior to 2.20, GtkBuilder was setting the "name" property of constructed widgets to the
"id" attribute. In GTK+ 2.20 or newer, you have to use gtk_buildable_get_name() instead
of gtk_widget_get_name() to obtain the "id", or set the "name" property in your UI
definition.
</para></note>
<para>
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
(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_color_parse()). Objects can be referred to by their name. Pixbufs can be
specified as a filename of an image file to load. In general, GtkBuilder
allows forward references to objects — 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.
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" propery 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.
</para>
<example>
<title>A GtkBuilder UI Definition</title>
<programlisting><![CDATA[
<interface>
<object class="GtkDialog" id="dialog1">
<child internal-child="vbox">
<object class="GtkVBox" id="vbox1">
<property name="border-width">10</property>
<child internal-child="action_area">
<object class="GtkHButtonBox" 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>
]]></programlisting>
</example>
<para>
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, see
<link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>,
<link linkend="GtkLabel-BUILDER-UI">GtkLabel</link>,
<link linkend="GtkWindow-BUILDER-UI">GtkWindow</link>,
<link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>,
<link linkend="GtkDialog-BUILDER-UI">GtkDialog</link>,
<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link>,
<link linkend="GtkColorSelectionDialog-BUILDER-UI">GtkColorSelectionDialog</link>,
<link linkend="GtkFontSelectionDialog-BUILDER-UI">GtkFontSelectionDialog</link>,
<link linkend="GtkExpander-BUILDER-UI">GtkExpander</link>,
<link linkend="GtkFrame-BUILDER-UI">GtkFrame</link>,
<link linkend="GtkListStore-BUILDER-UI">GtkListStore</link>,
<link linkend="GtkTreeStore-BUILDER-UI">GtkTreeStore</link>,
<link linkend="GtkNotebook-BUILDER-UI">GtkNotebook</link>,
<link linkend="GtkSizeGroup-BUILDER-UI">GtkSizeGroup</link>,
<link linkend="GtkTreeView-BUILDER-UI">GtkTreeView</link>,
<link linkend="GtkUIManager-BUILDER-UI">GtkUIManager</link>,
<link linkend="GtkActionGroup-BUILDER-UI">GtkActionGroup</link>.
<link linkend="GtkMenuItem-BUILDER-UI">GtkMenuItem</link>,
<link linkend="GtkMenuToolButton-BUILDER-UI">GtkMenuToolButton</link>,
<link linkend="GtkAssistant-BUILDER-UI">GtkAssistant</link>,
<link linkend="GtkScale-BUILDER-UI">GtkScale</link>,
<link linkend="GtkComboBoxText-BUILDER-UI">GtkComboBoxText</link>,
<link linkend="GtkRecentFilter-BUILDER-UI">GtkRecentFilter</link>,
<link linkend="GtkFileFilter-BUILDER-UI">GtkFileFilter</link>,
<link linkend="GtkTextTagTable-BUILDER-UI">GtkTextTagTable</link>.
</para>
</refsect2>
Creates a new builder object.
a new #GtkBuilder object
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.
if no type was found
the #GType found for @type_name or #G_TYPE_INVALID
type name to lookup
Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder
UI definition</link> and merges it 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.
A positive value on success, 0 if an error occurred
the name of the file to parse
Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder
UI definition</link> and merges it 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.
A positive value on success, 0 if an error occurred
the string to parse
the length of @buffer (may be -1 if @buffer is nul-terminated)
Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder
UI definition</link> 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.
<note><para>
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 explicitely list all of them in @object_ids.
</para></note>
A positive value on success, 0 if an error occurred
the name of the file to parse
nul-terminated array of objects to build
Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder
UI definition</link> 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.
<note><para>
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 explicitely list all of them in @object_ids.
</para></note>
A positive value on success, 0 if an error occurred
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 #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 will not work correctly if #GModule is not
supported on the platform.
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 pointer to a structure sent in as user data to 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.
the function used to connect the signals
arbitrary data that will be passed to the connection function
Gets the object named @name. Note that this function does not
increment the reference count of the returned object.
it could not be found in the object tree.
the object named @name or %NULL if
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.
constructed by the #GtkBuilder instance. It should be freed by
g_slist_free()
a newly-allocated #GSList containing all the objects
Gets the translation domain of @builder.
by the builder object and must not be modified or freed.
the translation domain. This string is owned
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.
if no type was found
the #GType found for @type_name or #G_TYPE_INVALID
type name to lookup
Sets the translation domain of @builder.
See #GtkBuilder:translation-domain.
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 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
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
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
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.
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.
The #GtkButton widget is generally used to attach a function to 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
most any other standard #GtkWidget. The most commonly used child is the
#GtkLabel.
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 #GtkButton containing the image and text from a stock item.
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()).
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.
Emits a #GtkButton::enter signal to the given #GtkButton.
Emits a #GtkButton::leave signal to the given #GtkButton.
Emits a #GtkButton::pressed signal to the given #GtkButton.
Emits a #GtkButton::released signal to the given #GtkButton.
Emits a #GtkButton::clicked signal to the given #GtkButton.
Emits a #GtkButton::enter signal to the given #GtkButton.
Gets the alignment of the child in the button.
return location for horizontal alignment
return location for vertical alignment
Returns the button's event window if it is realized, %NULL otherwise.
This function should be rarely needed.
@button's event window.
Returns whether the button grabs focus when it is clicked with the mouse.
See gtk_button_set_focus_on_click().
the mouse.
%TRUE if the button grabs focus when it is clicked with
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
Gets the position of the image relative to the text
inside the button.
the position
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.
by the widget and must not be modified or freed.
The text of the label widget. This string is owned
Returns the current relief style of the given #GtkButton.
The current #GtkReliefStyle
Returns whether the button label is a stock item.
select a stock item instead of being
used directly as the label text.
%TRUE if the button label is used to
Returns whether an embedded underline in the button label indicates a
mnemonic. See gtk_button_set_use_underline ().
indicates the mnemonic accelerator keys.
%TRUE if an embedded underline in the button label
Emits a #GtkButton::leave signal to the given #GtkButton.
Emits a #GtkButton::pressed signal to the given #GtkButton.
Emits a #GtkButton::released signal to the given #GtkButton.
Sets the alignment of the child. This property has no effect unless
the child is a #GtkMisc or a #GtkAlignment.
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
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.
whether the button grabs focus when clicked with the mouse
Set the image of @button to the given widget. Note that
it depends on the #GtkSettings:gtk-button-images setting whether the
image will be displayed or not, you don't have to call
gtk_widget_show() on @image yourself.
a widget to set as the image for the button
Sets the position of the image relative to the text
inside the button.
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 string
Sets the relief style of the edges of the given #GtkButton widget.
Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE.
The default style is, as one can guess, GTK_RELIEF_NORMAL.
<!-- FIXME: put pictures of each style -->
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.
%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.
%TRUE if underlines in the text indicate mnemonics
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.
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.
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.
Emitted when the pointer leaves the button.
Emitted when the button is pressed.
Emitted when the button is released.
Creates a new #GtkButtonBox.
a new #GtkButtonBox.
the box' orientation.
Returns whether @child should appear in a secondary group of children.
whether @child should appear in a secondary group of children.
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.
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 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.
the new layout style
Used to dictate the style that a #GtkButtonBox uses to layout the buttons it
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().
<note>
Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
and %GTK_BUTTONS_OK_CANCEL are discouraged by the
<ulink url="http://library.gnome.org/devel/hig-book/stable/">GNOME HIG</ulink>.
</note>
#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.
Obtains the selected date from 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.
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.
Queries the width of detail cells, in characters.
See #GtkCalendar:detail-width-chars.
The width of detail cells, in characters.
Returns the current display options of @calendar.
the display options.
Places a visual marker on a particular day.
the day number to mark between 1 and 31.
Selects a day from the current month.
the day number between 1 and 31, or 0 to unselect the currently selected day.
Shifts the calendar to a different month.
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 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.
detail height in rows.
Updates the width of detail cells.
See #GtkCalendar:detail-width-chars.
detail width in characters.
Sets display options (whether to display the heading and the month
headings).
the display options to set
Removes the visual marker from a particular day.
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.
for the specified day, or %NULL.
Newly allocated string with Pango markup with details
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.
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.
<refsect2 id="cell-area-geometry-management">
<title>Requesting area sizes</title>
<para>
As outlined in <link linkend="geometry-management">GtkWidget's
geometry management section</link>, 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:
<example>
<title>Requesting the width of a handful of GtkTreeModel rows</title>
<programlisting>
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);
</programlisting>
</example>
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:
<example>
<title>A typical get_preferred_width() implementation</title>
<programlisting>
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);
}
</programlisting>
</example>
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:
<example>
<title>Requesting the height for width of a handful of GtkTreeModel rows</title>
<programlisting>
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);
}
</programlisting>
</example>
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 the scrollbar
values while more and more height is required for the row heights
that are calculated in the background.
</para>
</refsect2>
<refsect2 id="cell-area-rendering">
<title>Rendering Areas</title>
<para>
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:
<example>
<title>Requesting the width of a handful of GtkTreeModel rows</title>
<programlisting>
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);
}
</programlisting>
</example>
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().
</para>
</refsect2>
<refsect2 id="cell-area-events-and-focus">
<title>Handling Events and Driving Keyboard Focus</title>
<para>
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:
<example>
<title>Implementing keyboard focus navigation</title>
<programlisting>
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;
}
</programlisting>
</example>
Note that the layouting widget is responsible for matching the
GtkDirectionType values to the way it lays out its cells.
</para>
</refsect2>
<refsect2 id="cell-properties">
<title>Cell Properties</title>
<para>
The #GtkCellArea introduces <emphasis>cell properties</emphasis>
for #GtkCellRenderers in very much the same way that #GtkContainer
introduces <link linkend="child-properties">child properties</link>
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().
</para>
</refsect2>
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.
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.
the #GtkCellRenderer to add to @area
Applies any connected attributes to the renderers in
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.
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.
Delegates event handling to a #GtkCellArea.
%TRUE if the event was handled by @area.
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.
the #GtkDirectionType
Calls @callback for every #GtkCellRenderer in @area.
the #GtkCellCallback to call
user provided data pointer
Calls @callback for every #GtkCellRenderer in @area with the
allocated rectangle inside @cell_area.
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.
when requesting sizes over an arbitrary number of rows, its 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.
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.
while calling gtk_cell_area_get_preferred_width(). It's important to
perform a series of gtk_cell_area_get_preferred_width() requests with
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().
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.
when requesting sizes over an arbitrary number of rows, its 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.
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.
while calling gtk_cell_area_get_preferred_height(). It's important to
perform a series of gtk_cell_area_get_preferred_height() requests with
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().
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.
Returns whether the area can do anything when activated,
after applying new attributes to @area.
whether @area can do anything when activated.
Removes @renderer from @area.
the #GtkCellRenderer to remove from @area
Renders @area's cells according to @area's layout onto @widget at
the given coordinates.
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.
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
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.
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.
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 #GtkCellRenderer to be placed inside @area
the name of the first cell property to set
Applies any connected attributes to the renderers in
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.
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.
the #GtkCellRenderer to disconnect an attribute for
the attribute name
Gets the values of one or more cell properties for @renderer in @area.
a #GtkCellRenderer which is inside @area
the name of the first cell property to get
Gets the value of a cell property for @renderer in @area.
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 #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 #GtkCellRenderer which is a cell inside @area
the name of the first cell property to set
Sets a cell property for @renderer in @area.
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 #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.
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.
Delegates event handling to a #GtkCellArea.
%TRUE if the event was handled by @area.
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.
the #GtkDirectionType
Calls @callback for every #GtkCellRenderer in @area.
the #GtkCellCallback to call
user provided data pointer
Calls @callback for every #GtkCellRenderer in @area with the
allocated rectangle inside @cell_area.
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.
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.
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.
attributes applied to @area. This string belongs to the area and
should not be freed.
The current #GtkTreePath string for the current
Gets the #GtkCellEditable widget currently used
to edit the currently edited cell.
The currently active #GtkCellEditable widget
Gets the #GtkCellRenderer in @area that is currently
being edited.
The currently edited #GtkCellRenderer
Retrieves the currently focused cell for @area
the currently focused cell in @area.
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.
is a sibling, or %NULL.
the #GtkCellRenderer for which @renderer
the #GtkCellRenderer
Gets the focus sibling cell renderers for @renderer.
The returned list is internal and should not be freed.
A #GList of #GtkCellRenderers.
the #GtkCellRenderer expected to have focus
Retrieves a cell area's initial minimum and natural height.
when requesting sizes over an arbitrary number of rows, its 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.
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.
while calling gtk_cell_area_get_preferred_width(). It's important to
perform a series of gtk_cell_area_get_preferred_width() requests with
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().
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.
when requesting sizes over an arbitrary number of rows, its 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.
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.
while calling gtk_cell_area_get_preferred_height(). It's important to
perform a series of gtk_cell_area_get_preferred_height() requests with
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().
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.
Checks if @area contains @renderer.
%TRUE if @renderer is in the @area.
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().
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.
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
the #GtkCellRenderer expected to have focus
the #GtkCellRenderer to check against @renderer's sibling list
Removes @renderer from @area.
the #GtkCellRenderer to remove from @area
Removes @sibling from @renderer's focus sibling list
(see gtk_cell_area_add_focus_sibling()).
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.
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.
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().
the #GtkCellRenderer to give focus to
Explicitly stops the editing of the currently
edited cell (see gtk_cell_area_get_edited_cell()).
If @canceled is %TRUE, the cell renderer will emit
the ::editing-canceled signal.
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 <emphasis>packing</emphasis>. Packing
refers to adding cell renderers with reference to a particular position
<emphasis>start</emphasis> and the <emphasis>end</emphasis> 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.
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.
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.
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.
the space to add between #GtkCellRenderers
The amount of space to reserve between cells.
the #GtkCellRenderer to add to @area
the #GtkCellRenderer to remove from @area
the #GtkCellCallback to call
user provided data pointer
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.
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.
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.
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 newly created #GtkCellAreaContext copy of @context.
the #GtkCellAreaContext to copy
The #GtkSizeRequestMode preferred by @area.
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
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
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
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.
the #GtkDirectionType
whether @area can do anything when activated.
Whether @area was successfully activated.
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.
or %NULL if @aclass has no child property with that name.
the #GParamSpec of the child property
the name of the child property to find
Installs a cell property on a cell area class.
the id for the property
the #GParamSpec for the property
Returns all cell properties of a cell area class.
allocated %NULL-terminated array of #GParamSpec*. The array
must be freed with g_free().
a newly
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 its 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
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 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 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
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
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.
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
its 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.
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 -1.
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 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 -1.
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 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.
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.
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
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().
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 proposed width for allocation
location to store the minimum height, or %NULL
location to store the natural height, or %NULL
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
when editing the contents of a #GtkTreeView cell.
Emits the #GtkCellEditable::editing-done signal.
Emits the #GtkCellEditable::remove-widget signal.
Begins editing on a @cell_editable. @event is the #GdkEvent that began
the editing process. It may be %NULL, in the instance that editing was
initiated through programatic means.
A #GdkEvent, or %NULL
Emits the #GtkCellEditable::editing-done signal.
Emits the #GtkCellEditable::remove-widget signal.
Begins editing on a @cell_editable. @event is the #GdkEvent that began
the editing process. It may be %NULL, in the instance that editing was
initiated through programatic means.
A #GdkEvent, or %NULL
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 is emitting it when the user presses Enter.
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 widget may now 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 #GdkEvent, or %NULL
#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 <emphasis>attributes</emphasis>. 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.
<refsect2 id="GtkCellLayout-BUILDER-UI">
<title>GtkCellLayouts as GtkBuildable</title>
<para>
Implementations of GtkCellLayout which also implement the GtkBuildable
interface (#GtkCellView, #GtkIconView, #GtkComboBox, #GtkComboBoxEntry,
#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.
<example>
<title>A UI definition fragment specifying attributes</title>
<programlisting><![CDATA[
<object class="GtkCellView">
<child>
<object class="GtkCellRendererText"/>
<attributes>
<attribute name="text">0</attribute>
</attributes>
</child>"
</object>
]]></programlisting>
</example>
Furthermore for implementations of GtkCellLayout that use a #GtkCellArea
to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea)
<link linkend="cell-properties">cell properties</link> 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.
<example>
<title>A UI definition fragment specifying cell properties</title>
<programlisting><![CDATA[
<object class="GtkTreeViewColumn">
<child>
<object class="GtkCellRendererText"/>
<cell-packing>
<property name="align">True</property>
<property name="expand">False</property>
</cell-packing>
</child>"
</object>
]]></programlisting>
</example>
</para>
</refsect2>
<refsect2>
<title>Subclassing GtkCellLayout implementations</title>
<para>
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
<informalexample><programlisting>
combo = g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL);
</programlisting></informalexample>
to use a custom cell area with a combo box. But construct properties
are only initialized <emphasis>after</emphasis> 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).
<informalexample><programlisting>
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);
}
</programlisting></informalexample>
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.
</para>
</refsect2>
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
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 #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.
Clears all existing attributes previously set with
gtk_cell_layout_set_attributes().
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.
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.
Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the
divided evenly between cells for which @expand is %TRUE.
Note that reusing the same cell renderer is not supported.
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 #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 #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.
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
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 #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.
Clears all existing attributes previously set with
gtk_cell_layout_set_attributes().
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.
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.
Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the
divided evenly between cells for which @expand is %TRUE.
Note that reusing the same cell renderer is not supported.
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 #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 #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 #GtkCellRenderer
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.
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 #GtkCellRenderer
%TRUE if @cell is to be given extra space allocated to @cell_layout
a #GtkCellRenderer
%TRUE if @cell is to be given extra space allocated to @cell_layout
a #GtkCellRenderer
an attribute on the renderer
the column position on the model to get the attribute from
a #GtkCellRenderer
the #GtkCellLayoutDataFunc to use, or %NULL
user data for @func
destroy notify for @func_data
a #GtkCellRenderer to clear the attribute mapping on
a #GtkCellRenderer to reorder
new position to insert @cell at
the cell area used by @cell_layout.
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 #GObject<!-- -->s 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 formost, its 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
<firstterm>activatable</firstterm> like #GtkCellRendererToggle,
which toggles when it gets activated by a mouse click, or it can be
<firstterm>editable</firstterm> like #GtkCellRendererText, which
allows the user to edit the text using a #GtkEntry.
To make a cell renderer activatable or editable, you have to
implement the #GtkCellRendererClass.activate or
#GtkCellRendererClass.start_editing virtual functions, respectively.
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 #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.
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.
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
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.
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
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.
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.
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
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
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
Passes an activate event to the cell renderer for possible processing.
A new #GtkCellEditable, or %NULL
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 #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.
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.
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.
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.
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.
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
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.
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.
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
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.
Returns the cell renderer's sensitivity.
%TRUE if the cell renderer is sensitive
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.
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 #GtkWidget, or %NULL
cell renderer state
Returns the cell renderer's visibility.
%TRUE if the cell renderer is visible
Checks whether the cell renderer can do something when activated.
%TRUE if the cell renderer can do anything when activated
Invokes the virtual render function of the #GtkCellRenderer. The three
passed-in rectangles are areas in @cr. Most renderers will draw within
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
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.
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.
the width of the cell renderer, or -1
the height of the cell renderer, or -1
Sets the renderer's padding.
the x padding of the cell renderer
the y padding of the cell renderer
Sets the cell renderer's sensitivity.
the sensitivity of the cell
Sets the cell renderer's visibility.
the visibility of the cell
Passes an activate event to the cell renderer for possible processing.
A new #GtkCellEditable, or %NULL
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.
%TRUE if the editing has been canceled
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.
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.
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:
|[
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
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.
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
The #GtkSizeRequestMode preferred by this renderer.
the #GtkWidget this cell will be rendering to
location to store the minimum size, or %NULL
location to store the natural size, or %NULL
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
the #GtkWidget this cell will be rendering to
location to store the minimum size, or %NULL
location to store the natural size, or %NULL
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
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.
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 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 #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, or %NULL
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
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,
<emphasis>not</emphasis> 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.
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.
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.
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".
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 rendererd.
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.
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 #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 #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 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
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.
Returns whether the cell renderer is active. See
gtk_cell_renderer_toggle_set_active().
%TRUE if the cell renderer is active.
Returns whether we're rendering radio toggles rather than checkboxes.
%TRUE if we're rendering radio toggles rather than checkboxes
Makes the cell renderer activatable.
the value to set.
Activates or deactivates a cell renderer.
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).
%TRUE to make the toggle look like a radio button
The ::toggled signal is emitted when the cell is toggled.
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).
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 <link linkend="PangoMarkupFormat">Pango text
markup language</link>.
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 its 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 its 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
Gets whether @cell_view is configured to draw all of its
cells in a sensitive state.
cells in a sensitive state
whether @cell_view draws all of its
Gets whether @cell_view is configured to request space
to fit the entire #GtkTreeModel.
the entire #GtkTreeModel.
whether @cell_view requests space to fit
Returns the model for @cell_view. If no model is used %NULL is
returned.
a #GtkTreeModel used or %NULL
Sets @requisition to the size needed by @cell_view to display
the model row pointed to by @path.
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 #GtkTreePath
return location for the size
Sets the background color of @view.
the new background color
Sets the background color of @cell_view.
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 #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.
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.
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 #GtkTreeModel
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
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
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 mnemonic character
Returns whether the check menu item is active. See
gtk_check_menu_item_set_active ().
%TRUE if the menu item is checked.
Returns whether @check_menu_item looks like a #GtkRadioMenuItem
Whether @check_menu_item looks like a #GtkRadioMenuItem
Retrieves the value set by gtk_check_menu_item_set_inconsistent().
%TRUE if inconsistent
Sets whether @check_menu_item is drawn like a #GtkRadioMenuItem
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.
%TRUE to display an "inconsistent" third state check
Returns the clipboard object for the given selection.
See gtk_clipboard_get_for_display() for complete details.
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.
the appropriate clipboard object. If no clipboard
a #GdkAtom which identifies the clipboard to use
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 <literal>gdk_atom_intern
("CLIPBOARD", FALSE)</literal>. See <ulink
url="http://www.freedesktop.org/Standards/clipboards-spec">
http://www.freedesktop.org/Standards/clipboards-spec</ulink>
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".
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 appropriate clipboard object. If no
the display 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.
Gets the #GdkDisplay associated with @clipboard
the #GdkDisplay associated with @clipboard
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().
otherwise %NULL.
the owner of the clipboard, if any;
Requests the contents of clipboard as the given target.
When the results of the result are later received the supplied callback
will be called.
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
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
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 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 #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 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
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 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 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.
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 #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 UTF-8 string.
length of @text, in bytes, or -1, in which case the length will be determined with <function>strlen()</function>.
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.
If setting the clipboard data failed the provided callback
functions will be ignored.
%TRUE if setting the clipboard data succeeded.
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.
If setting the clipboard data failed the provided callback
functions will be ignored.
%TRUE if setting the clipboard data succeeded.
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.
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.
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 newly-allocated #GtkSelectionData object or %NULL
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.
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 newly-allocated #GdkPixbuf
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.
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
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.
otherwise %FALSE.
%TRUE if any targets are present on the clipboard,
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.
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 newly-allocated UTF-8 string which must
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.
%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 newly-allocated
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.
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 #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 #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.
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.
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
The #GtkColorButton is a button which displays the currently selected
color an allows to open a color selection dialog to change the color.
It is suitable widget for selecting a color in a preference dialog.
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.
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.
an integer between 0 and 65535
Sets @color to be the current color in the #GtkColorButton widget.
a #GdkColor to fill in with the current color
Sets @rgba to be the current color in the #GtkColorButton widget.
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
Does the color selection dialog use the alpha channel ?
%TRUE if the color sample uses alpha channel, %FALSE if not
Sets the current opacity to be @alpha.
an integer between 0 and 65535
Sets the current color to be @color.
A #GdkColor to set the current color with
Sets the current color to be @rgba.
a #GdkRGBA to set the current color with
Sets the title for the color selection dialog.
String containing new window title
Sets whether or not the color button should use the alpha channel.
%TRUE if color button should use alpha channel, %FALSE if not
The selected opacity value (0 fully transparent, 65535 fully opaque).
The selected color.
The RGBA color.
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_color() and
gtk_color_button_get_alpha() (or gtk_color_button_get_rgba()) to
find out which color was just selected.
Note that this signal is only emitted when the <emphasis>user</emphasis>
changes the color. If you need to react to programmatic color changes
as well, use the notify::color signal.
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
Sets @color to be the current color in the GtkColorSelection widget.
a #GdkColor to fill in with the current color
Sets @rgba to be the current color in the GtkColorSelection widget.
a #GdkRGBA to fill in with the current color
Determines whether the colorsel has an opacity control.
%FALSE if it does't
%TRUE if the @colorsel has an opacity control,
Determines whether the color selector has a color palette.
%TRUE if the selector has a palette, %FALSE if it hasn't
Returns the previous alpha value.
an integer between 0 and 65535
Fills @color in with the original color value.
a #GdkColor to fill in with the original color value
Fills @rgba in with the original color value.
a #GdkRGBA to fill in with the original color value
Gets the current state of the @colorsel.
a color around, and %FALSE if the selection has stopped
%TRUE if the user is currently dragging
Sets the current opacity to be @alpha.
The first time this is called, it will also set
the original opacity to be @alpha too.
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.
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 #GdkRGBA to set the current color with
Sets the @colorsel to use or not use opacity.
%TRUE if @colorsel can set the opacity, %FALSE otherwise
Shows and hides the palette based upon the value of @has_palette.
%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.
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.
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 #GdkRGBA to set the previous color with
The current RGBA color.
This signal is emitted when the color changes in the #GtkColorSelection
according to its update policy.
Retrieves the #GtkColorSelection widget embedded in the dialog.
the embedded #GtkColorSelection
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.
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
<literal>gtk_tree_path_get_indices (path)[0]</literal>, where
<literal>path</literal> is the #GtkTreePath of the active item.
or -1 if there's no active item.
An integer which is the index of the currently active item,
Returns the ID of the active row of @combo_box. This value is taken
from the active row and the column specified by the '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 'id-column' property of @combo_box is not set or if no row is
selected then %NULL is returned.
the ID of the active row, or %NULL
Sets @iter to point to the current active item, if it exists.
%TRUE, if @iter was set
The uninitialized #GtkTreeIter
Gets the current value of the :add-tearoffs property.
the current value of the :add-tearoffs property.
Returns whether the combo box sets the dropdown button
sensitive or not when there are no items in the model.
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.
%GTK_SENSITIVITY_ON if the dropdown button
Returns the column with column span information for @combo_box.
the column span column.
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.
Returns whether the combo box grabs focus when it is clicked
with the mouse. See gtk_combo_box_set_focus_on_click().
clicked with the mouse.
%TRUE if the combo box grabs focus when it is
Returns whether the combo box has an entry.
whether there is an entry in @combo_box.
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.
Returns the #GtkTreeModel which is acting as data source for @combo_box.
during construction.
A #GtkTreeModel which was passed
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.
to the combo box's popup.
the accessible object corresponding
Gets whether the popup uses a fixed width matching
the allocated width of the combo box.
%TRUE if the popup uses a fixed width
Returns the current row separator function.
the current row separator function.
Returns the column with row span information for @combo_box.
the row span column.
Gets the current title of the menu in tearoff mode. See
gtk_combo_box_set_add_tearoffs().
string which must not be freed.
the menu's title in tearoff mode. This is an internal copy of the
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.
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.
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.
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 #GdkDevice<!-- -->s able to send events to it.
a #GdkDevice
Sets the active item of @combo_box to be the item at @index.
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 @id.
If the 'id-column' property of @combo_box is unset or if no row has
the given ID then nothing happens.
the ID of the row to select
Sets the current active item to be the one referenced by @iter, or
unsets the active item if @iter is %NULL.
The #GtkTreeIter, or %NULL
Sets whether the popup menu should have a tearoff
menu item.
%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).
specify the sensitivity of the dropdown button
Sets the column with column span information for @combo_box to be
how many columns an item should span.
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 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.
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 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 #GtkTreeModel
Specifies whether the popup's width should be a fixed width
matching the allocated width of the combo box.
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 #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 column in the model passed during construction.
Sets the menu's title in tearoff mode.
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.
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
<literal>gtk_tree_path_get_indices (path)[0]</literal>,
where <literal>path</literal> 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 values of that column are used to determine how many columns a value
in the list will span.
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 values of that column are used to determine how many rows a value in
the list will span. Therefore, the values in the model column pointed to
by this property must be greater than zero and not larger than wrap-width.
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, the list will be
displayed in multiple columns, the number of columns is
determined by 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.
The ::move-active signal is a
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted to move the active selection.
a #GtkScrollType
The ::popdown signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted to popup the combo box list.
The default binding for this signal is Alt+Down.
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.
<refsect2 id="GtkComboBoxText-BUILDER-UI">
<title>GtkComboBoxText as GtkBuildable</title>
<para>
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 supports the regular translation attributes "translatable",
"context" and "comments".
<example>
<title>A UI definition fragment specifying GtkComboBoxText items</title>
<programlisting><![CDATA[
<object class="GtkComboBoxText">
<items>
<item translatable="yes">Factory</item>
<item translatable="yes">Home</item>
<item translatable="yes">Subway</item>
</items>
</object>
]]></programlisting>
</example>
</para>
</refsect2>
Creates a new #GtkComboBoxText, which is a #GtkComboBox just displaying
strings. See gtk_combo_box_entry_new_with_text().
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 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 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).
active text. Must be freed with g_free().
a newly allocated string containing the currently
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.
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.
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 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 string
Removes the string at @position from @combo_box.
Index of the item to remove
Removes all the text entries from the combo box.
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 <emphasis>decorators</emphasis>, 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 <emphasis>layout</emphasis>. 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 #GtkTable arranges the widgets it contains
in a two-dimensional grid.
<refsect2 id="container-geometry-management">
<title>Height for width geometry management</title>
<para>
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:
<programlisting><![CDATA[
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) ...
}
}
]]></programlisting>
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:
<programlisting><![CDATA[
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 ...
}
}
]]></programlisting>
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 <function>get_preferred_height_for_width()</function> 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 <link linkend="geometry-management">GtkWidget's geometry management section</link>
to learn more about implementing height-for-width geometry management for widgets.
</para>
</refsect2>
<refsect2 id="child-properties">
<title>Child properties</title>
<para>
GtkContainer introduces <emphasis>child properties</emphasis>.
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().
</para>
</refsect2>
<refsect2 id="GtkContainer-BUILDER-UI">
<title>GtkContainer as GtkBuildable</title>
<para>
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.
<example>
<title>Child properties in UI definitions</title>
<programlisting><![CDATA[
<object class="GtkVBox">
<child>
<object class="GtkLabel"/>
<packing>
<property name="pack-type">start</property>
</packing>
</child>
</object>
]]></programlisting>
</example>
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.
</para>
</refsect2>
Adds @widget to @container. Typically used for simple containers
such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated
layout containers such as #GtkBox or #GtkTable, this function will
pick default packing parameters that may not be correct. So
consider functions such as gtk_box_pack_start() and
gtk_table_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.
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.
Returns a newly created widget path representing all the widget hierarchy
from the toplevel down to @child (this one not being included).
A newly created #GtkWidgetPath
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 while it's not inside
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 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
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 manualy set the focus to a specific widget.
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 #GtkTable, this function will
pick default packing parameters that may not be correct. So
consider functions such as gtk_box_pack_start() and
gtk_table_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.
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 widget to be placed inside @container
the name of the first child property to set
Gets the values of one or more child properties for @child and @container.
a widget which is a child of @container
the name of the first property to get
Gets the value of a child property for @child and @container.
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 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
Sets one or more child properties for @child and @container.
a widget which is a child of @container
the name of the first property to set
Sets a child property for @child and @container.
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 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.
Invokes @callback on each 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 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. Most applications should use
gtk_container_foreach(), rather than gtk_container_forall().
a callback
callback user data
Retrieves the border width of the container. See
gtk_container_set_border_width().
the current border width
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.
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
has been set explicitly.
%TRUE if the focus chain of the container
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().
focus inside @container when the @conatiner is focussed,
or %NULL if none is set.
The child widget which will receive the
Retrieves the horizontal focus adjustment for the container. See
gtk_container_set_focus_hadjustment ().
none has been set.
the horizontal focus adjustment, or %NULL if
Retrieves the vertical focus adjustment for the container. See
gtk_container_set_focus_vadjustment().
none has been set.
the vertical focus adjustment, or %NULL if
Returns a newly created widget path representing all the widget hierarchy
from the toplevel down to @child (this one not being included).
A newly created #GtkWidgetPath
a child of @container
Returns the resize mode for the container. See
gtk_container_set_resize_mode ().
the current resize mode
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 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 while it's not inside
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 current child of @container
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, one approach is to
create a #GtkAlignment widget, call gtk_widget_set_size_request()
to give it a size, and place it on the side of the container as
a spacer.
amount of blank space to leave <emphasis>outside</emphasis> 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.
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
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 manualy set the focus to a specific widget.
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.
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.
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.
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.
the new resize mode
Removes a focus chain explicitly set with gtk_container_set_focus_chain().
a widget to be placed inside @container
a current child of @container
a #GtkWidget, or %NULL
a #GType.
A newly created #GtkWidgetPath
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.
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.
Installs a child property on a container class.
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().
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.
GtkCssProvider is an object implementing the #GtkStyleProvider interface.
It is able to parse <ulink url="http://www.w3.org/TR/CSS2">CSS</ulink>-like
input in order to style widgets.
<refsect2 id="gtkcssprovider-files">
<title>Default files</title>
<para>
An application can cause GTK+ to parse a specific CSS style sheet by
calling gtk_css_provider_load_from_file() 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 <filename><envar>$XDG_CONFIG_HOME</envar>/gtk-3.0/gtk.css</filename>
is loaded if it exists. Then, GTK+ tries to load
<filename><envar>$HOME</envar>/.themes/<replaceable>theme-name</replaceable>/gtk-3.0/gtk.css</filename>,
falling back to
<filename><replaceable>datadir</replaceable>/share/themes/<replaceable>theme-name</replaceable>/gtk-3.0/gtk.css</filename>,
where <replaceable>theme-name</replaceable> is the name of the current theme
(see the #GtkSettings:gtk-theme-name setting) and <replaceable>datadir</replaceable>
is the prefix configured when GTK+ was compiled, unless overridden by the
<envar>GTK_DATA_PREFIX</envar> environment variable.
</para>
</refsect2>
<refsect2 id="gtkcssprovider-stylesheets">
<title>Style sheets</title>
<para>
The basic structure of the style sheets understood by this provider is
a series of statements, which are either rule sets or '@-rules', separated
by whitespace.
</para>
<para>
A rule set consists of a selector and a declaration block, which is
a series of declarations enclosed in curly braces ({ and }). The
declarations are separated by semicolons (;). Multiple selectors can
share the same declaration block, by putting all the separators in
front of the block, separated by commas.
</para>
<example><title>A rule set with two selectors</title>
<programlisting language="text">
GtkButton, GtkEntry {
}
</programlisting>
</example>
</refsect2>
<refsect2 id="gtkcssprovider-selectors">
<title>Selectors</title>
<para>
Selectors work very similar to the way they do in CSS, with widget class
names taking the role of element names, and widget names taking the role
of IDs. When used in a selector, widget names must be prefixed with a
'#' character. The '*' character represents the so-called universal
selector, which matches any widget.
</para>
<para>
To express more complicated situations, selectors can be combined in
various ways:
<itemizedlist>
<listitem><para>To require that a widget satisfies several conditions,
combine several selectors into one by concatenating them. E.g.
<literal>GtkButton#button1</literal> matches a GtkButton widget
with the name button1.</para></listitem>
<listitem><para>To only match a widget when it occurs inside some other
widget, write the two selectors after each other, separated by whitespace.
E.g. <literal>GtkToolBar GtkButton</literal> matches GtkButton widgets
that occur inside a GtkToolBar.</para></listitem>
<listitem><para>In the previous example, the GtkButton is matched even
if it occurs deeply nested inside the toolbar. To restrict the match
to direct children of the parent widget, insert a '>' character between
the two selectors. E.g. <literal>GtkNotebook > GtkLabel</literal> matches
GtkLabel widgets that are direct children of a GtkNotebook.</para></listitem>
</itemizedlist>
</para>
<example>
<title>Widget classes and names in selectors</title>
<programlisting language="text">
/* Theme labels that are descendants of a window */
GtkWindow GtkLabel {
}
/* Theme notebooks, and anything that's within these */
GtkNotebook {
}
/* Theme combo boxes, and entries that
are direct children of a notebook */
GtkComboBox,
GtkNotebook > GtkEntry {
}
/* Theme any widget within a GtkBin */
GtkBin * {
}
/* Theme a label named title-label */
GtkLabel#title-label {
}
/* Theme any widget named main-entry */
#main-entry {
}
</programlisting>
</example>
<para>
Widgets may also define style classes, which can be used for matching.
When used in a selector, style classes must be prefixed with a '.'
character.
</para>
<para>
Refer to the documentation of individual widgets to learn which
style classes they define and see <xref linkend="gtkstylecontext-classes"/>
for a list of all style classes used by GTK+ widgets.
</para>
<para>
Note that there is some ambiguity in the selector syntax when it comes
to differentiation widget class names from regions. GTK+ currently treats
a string as a widget class name if it contains any uppercase characters
(which should work for more widgets with names like GtkLabel).
</para>
<example>
<title>Style classes in selectors</title>
<programlisting language="text">
/* Theme all widgets defining the class entry */
.entry {
}
/* Theme spinbuttons' entry */
GtkSpinButton.entry {
}
</programlisting>
</example>
<para>
In complicated widgets like e.g. a GtkNotebook, it may be desirable
to style different parts of the widget differently. To make this
possible, container widgets may define regions, whose names
may be used for matching in selectors.
</para>
<para>
Some containers allow to further differentiate between regions by
applying so-called pseudo-classes to the region. For example, the
tab region in GtkNotebook allows to single out the first or last
tab by using the :first-child or :last-child pseudo-class.
When used in selectors, pseudo-classes must be prefixed with a
':' character.
</para>
<para>
Refer to the documentation of individual widgets to learn which
regions and pseudo-classes they define and see
<xref linkend="gtkstylecontext-classes"/> for a list of all regions
used by GTK+ widgets.
</para>
<example>
<title>Regions in selectors</title>
<programlisting language="text">
/* Theme any label within a notebook */
GtkNotebook GtkLabel {
}
/* Theme labels within notebook tabs */
GtkNotebook tab GtkLabel {
}
/* Theme labels in the any first notebook
tab, both selectors are equivalent */
GtkNotebook tab:nth-child(first) GtkLabel,
GtkNotebook tab:first-child GtkLabel {
}
</programlisting>
</example>
<para>
Another use of pseudo-classes is to match widgets depending on their
state. This is conceptually similar to the :hover, :active or :focus
pseudo-classes in CSS. The available pseudo-classes for widget states
are :active, :prelight (or :hover), :insensitive, :selected, :focused
and :inconsistent.
</para>
<example>
<title>Styling specific widget states</title>
<programlisting language="text">
/* Theme active (pressed) buttons */
GtkButton:active {
}
/* Theme buttons with the mouse pointer on it,
both are equivalent */
GtkButton:hover,
GtkButton:prelight {
}
/* Theme insensitive widgets, both are equivalent */
:insensitive,
*:insensitive {
}
/* Theme selection colors in entries */
GtkEntry:selected {
}
/* Theme focused labels */
GtkLabel:focused {
}
/* Theme inconsistent checkbuttons */
GtkCheckButton:inconsistent {
}
</programlisting>
</example>
<para>
Widget state pseudoclasses may only apply to the last element
in a selector.
</para>
<para>
To determine the effective style for a widget, all the matching rule
sets are merged. As in CSS, rules apply by specificity, so the rules
whose selectors more closely match a widget path will take precedence
over the others.
</para>
</refsect2>
<refsect2 id="gtkcssprovider-rules">
<title>@ Rules</title>
<para>
GTK+'s CSS supports the @import rule, in order to load another
CSS style sheet in addition to the currently parsed one.
</para>
<example>
<title>Using the @import rule</title>
<programlisting language="text">
@import url ("path/to/common.css");
</programlisting>
</example>
<para id="css-binding-set">
In order to extend key bindings affecting different widgets, GTK+
supports the @binding-set rule to parse a set of bind/unbind
directives, see #GtkBindingSet for the supported syntax. Note that
the binding sets defined in this way must be associated with rule sets
by setting the gtk-key-bindings style property.
</para>
<para>
Customized key bindings are typically defined in a separate
<filename>gtk-keys.css</filename> CSS file and GTK+ loads this file
according to the current key theme, which is defined by the
#GtkSettings:gtk-key-theme-name setting.
</para>
<example>
<title>Using the @binding rule</title>
<programlisting language="text">
@binding-set binding-set1 {
bind "<alt>Left" { "move-cursor" (visual-positions, -3, 0) };
unbind "End";
};
@binding-set binding-set2 {
bind "<alt>Right" { "move-cursor" (visual-positions, 3, 0) };
bind "<alt>KP_space" { "delete-from-cursor" (whitespace, 1)
"insert-at-cursor" (" ") };
};
GtkEntry {
}
</programlisting>
</example>
<para>
GTK+ also supports an additional @define-color rule, in order
to define a color name which may be used instead of color numeric
representations. Also see the #GtkSettings:gtk-color-scheme setting
for a way to override the values of these named colors.
</para>
<example>
<title>Defining colors</title>
<programlisting language="text">
@define-color bg_color #f9a039;
* {
}
</programlisting>
</example>
</refsect2>
<refsect2 id="gtkcssprovider-symbolic-colors">
<title>Symbolic colors</title>
<para>
Besides being able to define color names, the CSS parser is also able
to read different color expressions, which can also be nested, providing
a rich language to define colors which are derived from a set of base
colors.
</para>
<example>
<title>Using symbolic colors</title>
<programlisting language="text">
@define-color entry-color shade (@bg_color, 0.7);
GtkEntry {
}
GtkEntry:focused {
shade (#fff, 0.5),
0.8);
}
</programlisting>
</example>
<para>
The various ways to express colors in GTK+ CSS are:
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Explanation</entry>
<entry>Examples</entry>
</row>
</thead>
<tbody>
<row>
<entry>rgb(@r, @g, @b)</entry>
<entry>An opaque color; @r, @g, @b can be either integers between
0 and 255 or percentages</entry>
<entry><literallayout>rgb(128, 10, 54)
rgb(20%, 30%, 0%)</literallayout></entry>
</row>
<row>
<entry>rgba(@r, @g, @b, @a)</entry>
<entry>A translucent color; @r, @g, @b are as in the previous row,
<entry><literallayout>rgba(255, 255, 0, 0.5)</literallayout></entry>
</row>
<row>
<entry>#@xxyyzz</entry>
<entry>An opaque color; @xx, @yy, @zz are hexadecimal numbers
specifying @r, @g, @b variants with between 1 and 4
hexadecimal digits per component are allowed</entry>
<entry><literallayout>#ff12ab
#f0c</literallayout></entry>
</row>
<row>
<entry>@name</entry>
<entry>Reference to a color that has been defined with
@define-color
</entry>
<entry>@bg_color</entry>
</row>
<row>
<entry>mix(@color1, @color2, @f)</entry>
<entry>A linear combination of @color1 and @color2. @f is a
floating point number between 0 and 1.</entry>
<entry><literallayout>mix(#ff1e0a, @bg_color, 0.8)</literallayout></entry>
</row>
<row>
<entry>shade(@color, @f)</entry>
<entry>A lighter or darker variant of @color. @f is a
floating point number.
</entry>
<entry>shade(@fg_color, 0.5)</entry>
</row>
<row>
<entry>lighter(@color)</entry>
<entry>A lighter variant of @color</entry>
</row>
<row>
<entry>darker(@color)</entry>
<entry>A darker variant of @color</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect2>
<refsect2 id="gtkcssprovider-gradients">
<title>Gradients</title>
<para>
Linear or radial Gradients can be used as background images.
</para>
<para>
A linear gradient along the line from (@start_x, @start_y) to
(@end_x, @end_y) is specified using the syntax
<literallayout>-gtk-gradient (linear,
color-stop (@position, @color),
...)</literallayout>
where @start_x and @end_x can be either a floating point number between
0 and 1 or one of the special values 'left', 'right' or 'center', @start_y
and @end_y can be either a floating point number between 0 and 1 or one
of the special values 'top', 'bottom' or 'center', @position is a floating
point number between 0 and 1 and @color is a color expression (see above).
The color-stop can be repeated multiple times to add more than one color
stop. 'from (@color)' and 'to (@color)' can be used as abbreviations for
color stops with position 0 and 1, respectively.
</para>
<example>
<title>A linear gradient</title>
<inlinegraphic fileref="gradient1.png" format="PNG"/>
<para>This gradient was specified with
<literallayout>-gtk-gradient (linear,
left top, right bottom,
from(@yellow), to(@blue))</literallayout></para>
</example>
<example>
<title>Another linear gradient</title>
<inlinegraphic fileref="gradient2.png" format="PNG"/>
<para>This gradient was specified with
<literallayout>-gtk-gradient (linear,
0 0, 0 1,
color-stop(0, @yellow),
color-stop(0.2, @blue),
color-stop(1, #0f0))</literallayout></para>
</example>
<para>
A radial gradient along the two circles defined by (@start_x, @start_y,
syntax
<literallayout>-gtk-gradient (radial,
color-stop (@position, @color),
...)</literallayout>
where @start_radius and @end_radius are floating point numbers and
the other parameters are as before.
</para>
<example>
<title>A radial gradient</title>
<inlinegraphic fileref="gradient3.png" format="PNG"/>
<para>This gradient was specified with
<literallayout>-gtk-gradient (radial,
center center, 0,
center center, 1,
from(@yellow), to(@green))</literallayout></para>
</example>
<example>
<title>Another radial gradient</title>
<inlinegraphic fileref="gradient4.png" format="PNG"/>
<para>This gradient was specified with
<literallayout>-gtk-gradient (radial,
0.4 0.4, 0.1,
0.6 0.6, 0.7,
color-stop (0, #f00),
color-stop (0.1, #a0f),
color-stop (0.2, @yellow),
color-stop (1, @green))</literallayout></para>
</example>
</refsect2>
<refsect2 id="gtkcssprovider-slices">
<title>Border images</title>
<para>
Images can be used in 'slices' for the purpose of creating scalable
borders.
</para>
<inlinegraphic fileref="slices.png" format="PNG"/>
<para>
The syntax for specifying border images of this kind is:
<literallayout>url(@path) @top @right @bottom @left [repeat|stretch]? [repeat|stretch]?</literallayout>
The sizes of the 'cut off' portions are specified
with the @top, @right, @bottom and @left parameters.
The 'middle' sections can be repeated or stretched to create
the desired effect, by adding the 'repeat' or 'stretch' options after
the dimensions. If two options are specified, the first one affects
the horizontal behaviour and the second one the vertical behaviour.
If only one option is specified, it affects both.
</para>
<example>
<title>A border image</title>
<inlinegraphic fileref="border1.png" format="PNG"/>
<para>This border image was specified with
<literallayout>url("gradient1.png") 10 10 10 10</literallayout>
</para>
</example>
<example>
<title>A repeating border image</title>
<inlinegraphic fileref="border2.png" format="PNG"/>
<para>This border image was specified with
<literallayout>url("gradient1.png") 10 10 10 10 repeat</literallayout>
</para>
</example>
<example>
<title>A stretched border image</title>
<inlinegraphic fileref="border3.png" format="PNG"/>
<para>This border image was specified with
<literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout>
</para>
</example>
</refsect2>
<refsect2 id="gtkcssprovider-transitions">
<para>Styles can specify transitions that will be used to create a gradual
change in the appearance when a widget state changes. The following
syntax is used to specify transitions:
<literallayout>@duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?</literallayout>
The @duration is the amount of time that the animation will take for
a complete cycle from start to end. If the loop option is given, the
animation will be repated until the state changes again.
The option after the duration determines the transition function from a
small set of predefined functions.
<figure><title>Linear transition</title>
<graphic fileref="linear.png" format="PNG"/>
</figure>
<figure><title>Ease transition</title>
<graphic fileref="ease.png" format="PNG"/>
</figure>
<figure><title>Ease-in-out transition</title>
<graphic fileref="ease-in-out.png" format="PNG"/>
</figure>
<figure><title>Ease-in transition</title>
<graphic fileref="ease-in.png" format="PNG"/>
</figure>
<figure><title>Ease-out transition</title>
<graphic fileref="ease-out.png" format="PNG"/>
</figure>
</para>
</refsect2>
<refsect2 id="gtkcssprovider-properties">
<title>Supported properties</title>
<para>
Properties are the part that differ the most to common CSS,
not all properties are supported (some are planned to be
supported eventually, some others are meaningless or don't
map intuitively in a widget based environment).
</para>
<para>
There is also a difference in shorthand properties, for
example in common CSS it is fine to define a font through
the different @font-family, @font-style, @font-size
properties, meanwhile in GTK+'s CSS only the canonical
</para>
<para>
The currently supported properties are:
</para>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Property name</entry>
<entry>Syntax</entry>
<entry>Maps to</entry>
<entry>Examples</entry>
</row>
</thead>
<tbody>
<row>
<entry>engine</entry>
<entry>engine-name</entry>
<entry>#GtkThemingEngine</entry>
<entry>engine: clearlooks;
</row>
<row>
<entry>background-color</entry>
<entry morerows="2">color (see above)</entry>
<entry morerows="2">#GdkRGBA</entry>
<entry morerows="2"><literallayout>background-color: #fff;
</entry>
</row>
<row>
<entry>color</entry>
</row>
<row>
<entry>border-color</entry>
</row>
<row>
<entry>font</entry>
<entry>@family [@style] [@size]</entry>
<entry>#PangoFontDescription</entry>
<entry>font: Sans 15;</entry>
</row>
<row>
<entry>margin</entry>
<entry morerows="1"><literallayout>@width
</entry>
<entry morerows="1">#GtkBorder</entry>
<entry morerows="1"><literallayout>margin: 5;
</entry>
</row>
<row>
<entry>padding</entry>
</row>
<row>
<entry>background-image</entry>
<entry><literallayout>gradient (see above) or
url(@path)</literallayout></entry>
<entry>#cairo_pattern_t</entry>
<entry><literallayout>-gtk-gradient (linear,
left top, right top,
from (#fff), to (#000));
-gtk-gradient (linear, 0.0 0.5, 0.5 1.0,
from (#fff),
color-stop (0.5, #f00),
to (#000));
-gtk-gradient (radial,
center center, 0.2,
center center, 0.8,
color-stop (0.0, #fff),
color-stop (1.0, #000));
url ('background.png');</literallayout>
</entry>
</row>
<row>
<entry>border-width</entry>
<entry>integer</entry>
<entry>#gint</entry>
<entry>border-width: 5;</entry>
</row>
<row>
<entry>border-radius</entry>
<entry>integer</entry>
<entry>#gint</entry>
<entry>border-radius: 5;</entry>
</row>
<row>
<entry>border-style</entry>
<entry>[none|solid|inset|outset]</entry>
<entry>#GtkBorderStyle</entry>
<entry>border-style: solid;</entry>
</row>
<row>
<entry>border-image</entry>
<entry><literallayout>border image (see above)</literallayout></entry>
<entry>internal use only</entry>
<entry><literallayout>border-image: url("/path/to/image.png") 3 4 3 4 stretch;
</entry>
</row>
<row>
<entry>transition</entry>
<entry>transition (see above)</entry>
<entry>internal use only</entry>
<entry><literallayout>transition: 150ms ease-in-out;
</entry>
</row>
<row>
<entry>gtk-key-bindings</entry>
<entry>binding set name list</entry>
<entry>internal use only</entry>
<entry><literallayout>gtk-bindings: binding1, binding2, ...;</literallayout>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
GtkThemingEngines can register their own, engine-specific style properties
with the function gtk_theming_engine_register_property(). These properties
can be set in CSS like other properties, using a name of the form
<literallayout>-<replaceable>namespace</replaceable>-<replaceable>name</replaceable></literallayout>, where <replaceable>namespace</replaceable> is typically
the name of the theming engine, and <replaceable>name</replaceable> is the
name of the property. Style properties that have been registered by widgets
using gtk_widget_class_install_style_property() can also be set in this
way, using the widget class name for <replaceable>namespace</replaceable>.
</para>
<example>
<title>Using engine-specific style properties</title>
<programlisting>
* {
-GtkPaned-handle-size: 6;
-clearlooks-colorize-scrollbar: false;
}
</programlisting>
</example>
</refsect2>
Returns a newly created #GtkCssProvider.
A new #GtkCssProvider
Returns the provider containing the style settings used as a
fallback for all widgets.
This memory is owned by GTK+, and you must not free it.
The provider used for fallback styling.
Loads a theme from the usual theme paths
This memory is owned by GTK+, and you must not free it.
a #GtkCssProvider with the theme loaded.
A theme name
variant to load, for example, "dark", or %NULL for the default
Loads @data into @css_provider, making it clear any previously loaded
information.
%TRUE if the data could be loaded.
CSS data loaded in memory
the length of @data in bytes, or -1 for NUL terminated strings
Loads the data contained in @file into @css_provider, making it
clear any previously loaded information.
%TRUE if the data could be loaded.
#GFile pointing to a file to load
Loads the data contained in @path into @css_provider, making it clear
any previously loaded information.
%TRUE if the data could be loaded.
the path of a filename to load, in the GLib filename encoding
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
<structfield>action_area</structfield>. 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.
<example>
<title>Simple GtkDialog usage</title>
<programlisting>
/* Function to open a dialog box displaying the message provided. */
void
quick_message (gchar *message)
{
GtkWidget *dialog, *label, *content_area;
/* Create the widgets */
dialog = gtk_dialog_new_with_buttons ("Message",
main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_STOCK_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 to the dialog */
gtk_container_add (GTK_CONTAINER (content_area), label);
gtk_widget_show_all (dialog);
}
</programlisting>
</example>
<refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title>
<para>
The GtkDialog implementation of the #GtkBuildable interface exposes the
"action_area".
</para>
<para>
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).
</para>
<example>
<title>A <structname>GtkDialog</structname> UI definition fragment.</title>
<programlisting><![CDATA[
<object class="GtkDialog" id="dialog1">
<child internal-child="vbox">"
<object class="GtkVBox" id="vbox">
<child internal-child="action_area">
<object class="GtkHButtonBox" id="button_box">
<child>
<object class="GtkButton" id="button_cancel"/>
</child>
<child>
<object class="GtkButton" id="button_ok"/>
</child>
</object>
</child>
</object>
</child>
<action-widgets>
<action-widget response="3">button_ok</action-widget>
<action-widget response="-5">button_cancel</action-widget>
</action-widgets>
</object>
]]></programlisting>
</example>
</refsect2>
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 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,
#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:
|[
GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog",
main_app_window,
GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_STOCK_OK,
GTK_RESPONSE_ACCEPT,
GTK_STOCK_CANCEL,
GTK_RESPONSE_REJECT,
NULL);
]|
a new #GtkDialog
Title of the dialog, or %NULL
Transient parent of the dialog, or %NULL
from #GtkDialogFlags
stock ID or text to go in first button, or %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.
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.
an activatable widget
response ID for @child
Adds a button with the given text (or a stock button, if @button_text is a
stock ID) 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
text of button, or stock ID
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.
button text or stock ID
Returns the action area of @dialog.
the action area.
Returns the content area of @dialog.
the content area #GtkBox.
Gets the response id of a widget in the action area
of a dialog.
if @widget doesn't have a response id set.
the response id of @widget, or %GTK_RESPONSE_NONE
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
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.
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:
|[
gint 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, <emphasis>will</emphasis>
be triggered during a gtk_dialog_run() call.
response ID
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
<ulink url="http://library.gnome.org/devel/hig-book/stable/">Human
Interface Guidelines</ulink> with the affirmative button at the far
right, and the cancel button left of it. But the builtin GTK+ dialogs
and #GtkMessageDialog<!-- -->s 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:
|[
cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog),
GTK_STOCK_CANCEL,
GTK_RESPONSE_CANCEL);
ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog),
GTK_STOCK_OK,
GTK_RESPONSE_OK);
gtk_widget_grab_default (ok_button);
help_button = gtk_dialog_add_button (GTK_DIALOG (dialog),
GTK_STOCK_HELP,
GTK_RESPONSE_HELP);
gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog),
GTK_RESPONSE_OK,
GTK_RESPONSE_CANCEL,
GTK_RESPONSE_HELP,
-1);
]|
a response id used by one @dialog's buttons
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.
the number of response ids in @new_order
an array of response ids of
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 response ID
Calls <literal>gtk_widget_set_sensitive (widget, @setting)</literal>
for each widget in the dialog's action area with the given @response_id.
A convenient way to sensitize/desensitize dialog buttons.
a response ID
%TRUE for sensitive
The ::close signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
response ID
Flags used to influence dialog construction.
Gives an indication why a drag operation failed.
The value can by obtained by connecting to the
#GtkWidget::drag-failed signal.
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:
<itemizedlist>
<listitem>
<para>
Mouse and button press signals to respond to input from
the user. (Use gtk_widget_add_events() to enable events
you wish to receive.)
</para>
</listitem>
<listitem>
<para>
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.)
</para>
</listitem>
<listitem>
<para>
The #GtkWidget::configure-event signal to take any necessary
actions when the widget changes size.
</para>
</listitem>
<listitem>
<para>
The #GtkWidget::draw signal to handle redrawing the
contents of the widget.
</para>
</listitem>
</itemizedlist>
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 to the
background color before sending the expose event, and that
drawing is implicitly clipped to the exposed area.
<example>
<title>Simple GtkDrawingArea usage</title>
<programlisting>
gboolean
draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data)
{
guint width, height;
GdkRGBA color;
width = gtk_widget_get_allocated_width (widget);
height = gtk_widget_get_allocated_height (widget);
cairo_arc (cr,
width / 2.0, height / 2.0,
MIN (width, height) / 2.0,
0, 2 * G_PI);
gtk_style_context_get_color (gtk_widget_get_style_context (widget),
0,
&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);
</programlisting>
</example>
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 <link
linkend="gdk3-Cairo-Interaction">GDK Drawing Primitives</link> 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 #GtkText. 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 "insert_text", an application
can convert all entry into a widget into uppercase.
<example>
<title>Forcing entry to uppercase.</title>
<programlisting>
#include <ctype.h>
void
insert_text_handler (GtkEditable *editable,
const gchar *text,
gint length,
gint *position,
gpointer data)
{
int i;
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);
}
</programlisting>
</example>
Deletes a sequence of characters. The characters that are deleted are
those characters at positions from @start_pos up to, but not including
are those from @start_pos to the end of the text.
Note that the positions are specified in characters, not bytes.
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
are those from @start_pos to the end of the text.
Note that the positions are specified in characters, not bytes.
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.
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 the characters
retrieved are those characters from @start_pos to the end of the text.
Note that positions are specified in characters, not bytes.
string. This string is allocated by the #GtkEditable
implementation and should be freed by the caller.
a pointer to the contents of the widget as a
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
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
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.
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.
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 the
characters selected are those characters from @start_pos to
the end of the text.
Note that positions are specified in characters, not bytes.
start of region
end of region
Copies the contents of the currently selected content in the editable and
puts it on the clipboard.
Removes the contents of the currently selected content in the editable and
puts it on the clipboard.
Deletes the currently selected text of the editable.
This call doesn't do anything if there is no selected text.
Deletes a sequence of characters. The characters that are deleted are
those characters at positions from @start_pos up to, but not including
are those from @start_pos to the end of the text.
Note that the positions are specified in characters, not bytes.
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 the characters
retrieved are those characters from @start_pos to the end of the text.
Note that positions are specified in characters, not bytes.
string. This string is allocated by the #GtkEditable
implementation and should be freed by the caller.
a pointer to the contents of the widget as a
start of text
end of text
Retrieves whether @editable is editable. See
gtk_editable_set_editable().
%TRUE if @editable is editable.
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
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
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.
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.
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 the
characters selected are those characters from @start_pos to
the end of the text.
Note that positions are specified in characters, not bytes.
start of region
end of region
Determines if the user can edit the text in the editable
widget or not.
%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.
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.
the text to append
the length of the text in bytes, or -1
location of the position text will be inserted at
start position
end position
the text to append
the length of the text in bytes, or -1
location of the position text will be inserted at
start position
end position
a pointer to the contents of the widget as a
start of text
end of text
start of region
end of region
%TRUE if an area is selected, %FALSE otherwise
location to store the starting position, or %NULL
location to store the end position, or %NULL
the position of the cursor
the cursor position
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.
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
Gets the value set by gtk_entry_set_alignment().
the alignment
Get the #GtkEntryBuffer object which holds the text for
this widget.
A #GtkEntryBuffer object.
Returns the auxiliary completion object currently in use by @entry.
in use by @entry.
The auxiliary completion object currently
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.
DND operation, or -1.
index of the icon which is the source of the current
Retrieves the horizontal cursor adjustment for the entry.
See gtk_entry_set_cursor_hadjustment().
if none has been set.
the horizontal cursor adjustment, or %NULL
Gets the value set by gtk_entry_set_has_frame().
whether the entry has a beveled frame
Returns whether the icon is activatable.
%TRUE if the icon is activatable.
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,
See also gtk_entry_get_text_area()
Icon position
Return location for the icon's area
Finds the icon at the given position and return its index.
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
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).
or if the icon is not a #GIcon
A #GIcon, or %NULL if no icon is set
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).
wasn't set from an icon name
An icon name, or %NULL if no icon is set or if the icon
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.
set for this position.
A #GdkPixbuf, or %NULL if no icon is
Icon position
Returns whether the icon appears sensitive or insensitive.
%TRUE if the icon is sensitive.
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).
wasn't set from a stock id
A stock id, or %NULL if no icon is set or if the icon
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
Icon position
Gets the contents of the tooltip on the icon at the specified
position in @entry.
with g_free() when done.
the tooltip text, or %NULL. Free the returned string
the icon position
Gets the contents of the tooltip on the icon at the specified
position in @entry.
with g_free() when done.
the tooltip text, or %NULL. Free the returned string
the icon position
This function returns the entry's #GtkEntry:inner-border property. See
gtk_entry_set_inner_border() for more information.
the entry's #GtkBorder, or %NULL if none was set.
Retrieves the character displayed in place of the real characters
for entries with visibility set to false. See gtk_entry_set_invisible_char().
show invisible text at all.
the current invisible char, or 0, if the entry does not
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
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.
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
This is equivalent to:
<informalexample><programlisting>
gtk_entry_buffer_get_max_length (gtk_entry_get_buffer (entry));
</programlisting></informalexample>
in #GtkEntry, or 0 if there is no maximum.
the maximum allowed number of characters
Gets the value set by gtk_entry_set_overwrite_mode().
whether the text is overwritten when typing.
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
Retrieves the pulse step set with gtk_entry_set_progress_pulse_step().
a fraction from 0.0 to 1.0
Retrieves the contents of the entry widget.
See also gtk_editable_get_chars().
This is equivalent to:
<informalexample><programlisting>
gtk_entry_buffer_get_text (gtk_entry_get_buffer (entry));
</programlisting></informalexample>
string. This string points to internally allocated
storage in the widget and must not be freed, modified or
stored.
a pointer to the contents of the widget as a
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().
Return location for the text area.
Retrieves the current length of the text in
This is equivalent to:
<informalexample><programlisting>
gtk_entry_buffer_get_length (gtk_entry_get_buffer (entry));
</programlisting></informalexample>
in #GtkEntry, or 0 if there are none.
the current number of characters
Retrieves whether the text in @entry is visible. See
gtk_entry_set_visibility().
%TRUE if the text is currently visible
Gets the value set by gtk_entry_set_width_chars().
number of chars to request space for, or negative if unset
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.
the key event
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 contents
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()).
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.
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 #GtkWidget::activate signal.)
%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.
The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts
Set the #GtkEntryBuffer object which holds the text for
this widget.
a #GtkEntryBuffer
Sets @completion to be the auxiliary completion object to use with @entry.
All further configuration of the completion mechanism is done on
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.
an adjustment which should be adjusted when the cursor is moved, or %NULL
Sets whether the entry has a beveled frame around it.
new value
Sets whether the icon is activatable.
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.
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.
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.
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.
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.
Icon position
The name of the stock item, or %NULL
Sets the sensitivity for the specified icon.
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 <link linkend="PangoMarkupFormat">Pango text markup language</link>.
Use %NULL for @tooltip to remove an existing tooltip.
See also gtk_widget_set_tooltip_markup() and
gtk_enty_set_icon_tooltip_text().
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().
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.
a #GtkBorder, or %NULL
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 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:
<informalexample><programlisting>
gtk_entry_buffer_set_max_length (gtk_entry_get_buffer (entry), max);
</programlisting></informalexample>
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 whether the text is overwritten when typing in the #GtkEntry.
new value
Causes the entry's progress indicator to "fill in" the given
fraction of the bar. The fraction should be between 0.0 and 1.0,
inclusive.
fraction 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().
fraction between 0.0 and 1.0
Sets the text in the widget to the given
value, replacing the current contents.
See gtk_entry_buffer_set_text().
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().
%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
<emphasis>request</emphasis>, 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.
width in chars
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 layout text
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.
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.
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.
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.
If text is overwritten when typing in the #GtkEntry.
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.
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 <link linkend="PangoMarkupFormat">Pango text markup
language</link>.
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.
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 <link linkend="PangoMarkupFormat">Pango text markup
language</link>.
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.
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.
A <link linkend="keybinding-signals">keybinding signal</link>
which gets emitted when the user activates the entry.
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 all forms of the Enter key.
The ::backspace signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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 ::move-cursor signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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.
<itemizedlist>
<listitem>Arrow keys move by individual characters/lines</listitem>
<listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
<listitem>Home/End keys move to the ends of the buffer</listitem>
</itemizedlist>
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
<link linkend="keybinding-signals">keybinding signal</link>
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 menuitems to the @menu.
the menu 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
<link linkend="keybinding-signals">keybinding signal</link>
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.
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.
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.
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.
position at which to delete text
number of characters to delete
Used when subclassing #GtkEntryBuffer
position at which text was deleted
number of characters deleted
Used when subclassing #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.
Retrieves the length in characters of the buffer.
The number of characters in the buffer.
Retrieves the maximum allowed length of the text in
in #GtkEntryBuffer, or 0 if there is no maximum.
the maximum allowed number of characters
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.
string. This string points to internally allocated
storage in the buffer and must not be freed, modified or
stored.
a pointer to the contents of the widget as a
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.
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.
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.
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.
The number of characters actually inserted.
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.
position at which to delete text
number of characters to delete
#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.
Deletes the action at @index_ from @completion's action list.
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
Gets the entry @completion has been attached to.
The entry @completion has been attached to
Returns whether the common prefix of the possible completions should
be automatically inserted in the entry.
%TRUE if inline completion is turned on
Returns %TRUE if inline-selection mode is turned on.
%TRUE if inline-selection mode is on
Returns the minimum key length as set for @completion.
The currently used minimum key length
Returns the model the #GtkEntryCompletion is using as data source.
Returns %NULL if the model is unset.
is currently being used
A #GtkTreeModel, or %NULL if none
Returns whether the completions should be presented in a popup window.
%TRUE if popup completion is turned on
Returns whether the completion popup window will be resized to the
width of the entry.
the entry
%TRUE if the popup window will be resized to the width of
Returns whether the completion popup window will appear even if there is
only a single match.
number of matches
%TRUE if the popup window will appear regardless of the
Returns the column in the model of @completion to get strings from.
the column containing the strings
Inserts an action in @completion's action item list at position @index_
with markup @markup.
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().
the index of the item to insert
text of the item to insert
Requests a prefix insertion.
Sets whether the common prefix of the possible completions should
be automatically inserted in the entry.
%TRUE to do inline completion
Sets whether it is possible to cycle through the possible completions
inside the entry.
%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.
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
key takes a lot of time and will come up with meaningless results anyway
(ie, a too large dataset).
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.
the #GtkTreeModel
Sets whether the completions should be presented in a popup window.
%TRUE to do popup completion
Sets whether the completion popup window will be resized to be the same
width as the entry.
%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 <link linkend="GtkEntryCompletion--inline-completion">inline
completion</link>.
%TRUE if the popup should appear even for a single match
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.
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
<link linkend="GtkEntryCompletion--inline-completion">inline
completion</link>.
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
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
<literal>gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry (<!-- -->)))</literal>.
for @key
%TRUE if @iter should be displayed as a possible completion
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.
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.
window of its child
%TRUE if the event box window is above the
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
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.
%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.
<note><para>
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.
</para><para>
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.
</para></note>
%TRUE to make the event box have a visible window
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.
<refsect2 id="expander-special-usage">
<title>Special Usage</title>
<para>
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:
</para>
<informalexample>
<programlisting id="expander-callback-example">
expander = gtk_expander_new_with_mnemonic ("_More Options");
g_signal_connect (expander, "notify::expanded",
G_CALLBACK (expander_callback), NULL);
...
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 */
}
}
</programlisting>
</informalexample>
</refsect2>
<refsect2 id="GtkExpander-BUILDER-UI">
<title>GtkExpander as GtkBuildable</title>
<para>
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.
</para>
<example>
<title>A UI definition fragment with GtkExpander</title>
<programlisting><![CDATA[
<object class="GtkExpander">
<child type="label">
<object class="GtkLabel" id="expander-label"/>
</child>
<child>
<object class="GtkEntry" id="expander-content"/>
</child>
</object>
]]></programlisting>
</example>
</refsect2>
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
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.
by the widget and must not be modified or freed.
The text of the label widget. This string is owned
Returns whether the label widget will fill all available
horizontal space allocated to @expander.
available horizontal space
%TRUE if the label widget will fill all
Retrieves the label widget for the frame. See
gtk_expander_set_label_widget().
or %NULL if there is none
the label widget,
Gets the value set by gtk_expander_set_spacing().
spacing between the expander and child
Returns whether the label's text is interpreted as marked up with
the <link linkend="PangoMarkupFormat">Pango text markup
language</link>. See gtk_expander_set_use_markup().
%TRUE if the label's text will be parsed for markup
Returns whether an embedded underline in the expander label
indicates a mnemonic. See gtk_expander_set_use_underline().
label indicates the mnemonic accelerator keys
%TRUE if an embedded underline in the expander
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.
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 string
Sets whether the label widget should fill all available
horizontal space allocated to @expander.
%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.
the new label widget
Sets the spacing field of @expander, which is the number of
pixels to place between expander and the child.
distance between the expander and child in pixels
Sets whether the text of the label contains markup in <link
linkend="PangoMarkupFormat">Pango's text markup
language</link>. See gtk_label_set_markup().
%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.
%TRUE if underlines in the text indicate mnemonics
Used to specify the style of the expanders drawn by a #GtkTreeView.
#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:
<variablelist>
<varlistentry>
<term>Bookmarks</term>
<listitem>
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.
</listitem>
</varlistentry>
<varlistentry>
<term>Shortcuts</term>
<listitem>
can be provided by the application or by the underlying filesystem
abstraction (e.g. both the gnome-vfs and the Windows filesystems
provide "Desktop" shortcuts). Shortcuts cannot be modified by the
user.
</listitem>
</varlistentry>
<varlistentry>
<term>Volumes</term>
<listitem>
are provided by the underlying filesystem abstraction. They are
the "roots" of the filesystem.
</listitem>
</varlistentry>
</variablelist>
<refsect2 id="gtkfilechooser-encodings">
<title>File Names and Encodings</title>
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 <emphasis>always</emphasis> returned in
the character set specified by the
<envar>G_FILENAME_ENCODING</envar> environment variable.
Please see the Glib documentation for more details about this
variable.
<note>
This means that while you can pass the result of
gtk_file_chooser_get_filename() to
<function>open(2)</function> or
<function>fopen(3)</function>, 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.
</note>
</refsect2>
<refsect2 id="gtkfilechooser-preview">
<title>Adding a Preview Widget</title>
<para>
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.
</para>
<para>
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.
</para>
<example id="example-gtkfilechooser-preview">
<title>Sample Usage</title>
<programlisting>
{
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);
}
</programlisting>
</example>
</refsect2>
<refsect2 id="gtkfilechooser-extra">
<title>Adding Extra Widgets</title>
<para>
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.
</para>
<example id="example-gtkfilechooser-extra">
<title>Sample Usage</title>
<programlisting>
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);
}
</programlisting>
</example>
<note>
If you want to set more than one extra widget in the file
chooser, you can a container such as a #GtkVBox or a #GtkTable
and include your widgets in it. Then, set the container as
the whole extra widget.
</note>
</refsect2>
<refsect2 id="gtkfilechooser-key-bindings">
<title>Key Bindings</title>
<para>
Internally, GTK+ implements a file chooser's graphical user
interface with the private
<classname>GtkFileChooserDefaultClass</classname>. This
widget has several <link linkend="gtk-Bindings">key
bindings</link> and their associated signals. This section
describes the available key binding signals.
</para>
<example id="gtkfilechooser-key-binding-example">
<title>GtkFileChooser key binding example</title>
<para>
The default keys that activate the key-binding signals in
<classname>GtkFileChooserDefaultClass</classname> are as
follows:
</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>Signal name</entry>
<entry>Default key combinations</entry>
</row>
<row>
<entry>location-popup</entry>
<entry>
<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> (empty path);
<keycap>/</keycap> (path of "/")
<footnote>
Both the individual <keycap>/</keycap> key and the
numeric keypad's "divide" key are supported.
</footnote>;
<keycap>~</keycap> (path of "~")
</entry>
</row>
<row>
<entry>up-folder</entry>
<entry>
<keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>;
<keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Up</keycap></keycombo>
<footnote>
Both the individual Up key and the numeric
keypad's Up key are supported.
</footnote>;
<keycap>Backspace</keycap>
</entry>
</row>
<row>
<entry>down-folder</entry>
<entry>
<keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>;
<keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Down</keycap></keycombo>
<footnote>
Both the individual Down key and the numeric
keypad's Down key are supported.
</footnote>
</entry>
</row>
<row>
<entry>home-folder</entry>
<entry><keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo></entry>
</row>
<row>
<entry>desktop-folder</entry>
<entry><keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo></entry>
</row>
<row>
<entry>quick-bookmark</entry>
<entry><keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> through <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
You can change these defaults to something else. For
example, to add a <keycap>Shift</keycap> modifier to a few
of the default bindings, you can include the following
fragment in your <filename>.gtkrc-3.0</filename> file:
</para>
<programlisting>
binding "my-own-gtkfilechooser-bindings" {
bind "<Alt><Shift>Up" {
"up-folder" ()
}
bind "<Alt><Shift>Down" {
"down-folder" ()
}
bind "<Alt><Shift>Home" {
"home-folder" ()
}
}
class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
</programlisting>
</example>
<refsect3 id="GtkFileChooserDefault-location-popup">
<title>The "GtkFileChooserDefault::location-popup" signal</title>
<programlisting>
void user_function (GtkFileChooserDefault *chooser,
const char *path,
<link linkend="gpointer">gpointer</link> user_data);
</programlisting>
<para>
This is used to make the file chooser show a "Location"
dialog which the user can use to manually type the name of
the file he wishes to select. The
<parameter>path</parameter> argument is a string that gets
put in the text entry for the file name. By default this is bound to
<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
with a <parameter>path</parameter> string of "" (the empty
string). It is also bound to <keycap>/</keycap> with a
<parameter>path</parameter> string of "<literal>/</literal>"
(a slash): this lets you type <keycap>/</keycap> and
immediately type a path name. On Unix systems, this is bound to
<keycap>~</keycap> (tilde) with a <parameter>path</parameter> string
of "~" itself for access to home directories.
</para>
<variablelist role="params">
<varlistentry>
<term><parameter>chooser</parameter> :</term>
<listitem>
<simpara>
the object which received the signal.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>path</parameter> :</term>
<listitem>
<simpara>
default contents for the text entry for the file name
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user_data</parameter> :</term>
<listitem>
<simpara>
user data set when the signal handler was connected.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<note>
You can create your own bindings for the
#GtkFileChooserDefault::location-popup signal with custom
<parameter>path</parameter> strings, and have a crude form
of easily-to-type bookmarks. For example, say you access
the path <filename>/home/username/misc</filename> very
frequently. You could then create an <keycombo>
<keycap>Alt</keycap> <keycap>M</keycap> </keycombo>
shortcut by including the following in your
<filename>.gtkrc-3.0</filename>:
<programlisting>
binding "misc-shortcut" {
bind "<Alt>M" {
"location-popup" ("/home/username/misc")
}
}
class "GtkFileChooserDefault" binding "misc-shortcut"
</programlisting>
</note>
</refsect3>
<refsect3 id="GtkFileChooserDefault-up-folder">
<title>The "GtkFileChooserDefault::up-folder" signal</title>
<programlisting>
void user_function (GtkFileChooserDefault *chooser,
<link linkend="gpointer">gpointer</link> user_data);
</programlisting>
<para>
This is used to make the file chooser go to the parent of
the current folder in the file hierarchy. By default this
is bound to <keycap>Backspace</keycap> and
<keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
(the Up key in the numeric keypad also works).
</para>
<variablelist role="params">
<varlistentry>
<term><parameter>chooser</parameter> :</term>
<listitem>
<simpara>
the object which received the signal.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user_data</parameter> :</term>
<listitem>
<simpara>
user data set when the signal handler was connected.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 id="GtkFileChooserDefault-down-folder">
<title>The "GtkFileChooserDefault::down-folder" signal</title>
<programlisting>
void user_function (GtkFileChooserDefault *chooser,
<link linkend="gpointer">gpointer</link> user_data);
</programlisting>
<para>
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/<emphasis>bar/</emphasis>baz", then this will cause
the file chooser to switch to the "baz" subfolder. By
default this is bound to
<keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
(the Down key in the numeric keypad also works).
</para>
<variablelist role="params">
<varlistentry>
<term><parameter>chooser</parameter> :</term>
<listitem>
<simpara>
the object which received the signal.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user_data</parameter> :</term>
<listitem>
<simpara>
user data set when the signal handler was connected.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 id="GtkFileChooserDefault-home-folder">
<title>The "GtkFileChooserDefault::home-folder" signal</title>
<programlisting>
void user_function (GtkFileChooserDefault *chooser,
<link linkend="gpointer">gpointer</link> user_data);
</programlisting>
<para>
This is used to make the file chooser show the user's home
folder in the file list. By default this is bound to
<keycombo><keycap>Alt</keycap><keycap>Home</keycap></keycombo>
(the Home key in the numeric keypad also works).
</para>
<variablelist role="params">
<varlistentry>
<term><parameter>chooser</parameter> :</term>
<listitem>
<simpara>
the object which received the signal.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user_data</parameter> :</term>
<listitem>
<simpara>
user data set when the signal handler was connected.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 id="GtkFileChooserDefault-desktop-folder">
<title>The "GtkFileChooserDefault::desktop-folder" signal</title>
<programlisting>
void user_function (GtkFileChooserDefault *chooser,
<link linkend="gpointer">gpointer</link> user_data);
</programlisting>
<para>
This is used to make the file chooser show the user's Desktop
folder in the file list. By default this is bound to
<keycombo><keycap>Alt</keycap><keycap>D</keycap></keycombo>.
</para>
<variablelist role="params">
<varlistentry>
<term><parameter>chooser</parameter> :</term>
<listitem>
<simpara>
the object which received the signal.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user_data</parameter> :</term>
<listitem>
<simpara>
user data set when the signal handler was connected.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3 id="GtkFileChooserDefault-quick-bookmark">
<title>The "GtkFileChooserDefault::quick-bookmark" signal</title>
<programlisting>
void user_function (GtkFileChooserDefault *chooser,
gint bookmark_index,
<link linkend="gpointer">gpointer</link> user_data);
</programlisting>
<para>
This is used to make the file chooser switch to the bookmark
specified in the <parameter>bookmark_index</parameter> parameter.
For example, if you have three bookmarks, you can pass 0, 1, 2 to
this signal to switch to each of them, respectively. By default this is bound to
<keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo>,
<keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>,
etc. until
<keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo>. Note
that in the default binding,
that <keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo> is
actually defined to switch to the bookmark at index 0, and so on
successively;
<keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo> is
defined to switch to the bookmark at index 10.
</para>
<variablelist role="params">
<varlistentry>
<term><parameter>chooser</parameter> :</term>
<listitem>
<simpara>
the object which received the signal.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bookmark_indes</parameter> :</term>
<listitem>
<simpara>
index of the bookmark to switch to; the indices start at 0.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>user_data</parameter> :</term>
<listitem>
<simpara>
user data set when the signal handler was connected.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
</refsect2>
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 #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.
otherwise. In the latter case, the @error will be set as appropriate.
%TRUE if the folder could be added successfully, %FALSE
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.
otherwise. In the latter case, the @error will be set as appropriate.
%TRUE if the folder could be added successfully, %FALSE
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
Gets whether file choser will offer to create new folders.
See gtk_file_chooser_set_create_folders().
%TRUE if the New Folder button should be displayed.
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 <emphasis>not the same</emphasis>
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.
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.
the full path of the current folder,
Gets the current folder of @chooser as #GFile.
See gtk_file_chooser_get_current_folder_uri().
the #GFile for the current folder.
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 <emphasis>not the same</emphasis>
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.
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.
the URI for the current folder. Free with g_free(). This
Queries whether a file chooser is set to confirm for overwriting when the user
types a file name that already exists.
%FALSE otherwise.
%TRUE if the file chooser will present a confirmation dialog;
Gets the current preview widget; see
gtk_file_chooser_set_extra_widget().
the current extra widget, or %NULL
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.
use g_object_unref() to release it.
a selected #GFile. You own the returned file;
Gets the filename 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.
if no file is selected, or the selected file can't
be represented with a local filename. Free with g_free().
The currently selected filename, or %NULL
Lists all the selected files and subfolders in the current folder of
folder cannot be represented as local filenames they will be ignored. (See
gtk_file_chooser_get_uris())
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 #GSList
Lists all the selected files and subfolders in the current folder of @chooser
as #GFile. An internal function, see gtk_file_chooser_get_uris().
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 #GSList
Gets the current filter; see gtk_file_chooser_set_filter().
the current filter, or %NULL
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.
Gets the #GFile that should be previewed in a custom preview
Internal function, see gtk_file_chooser_get_preview_uri().
or %NULL if no file is selected. Free with g_object_unref().
the #GFile for the file to preview,
Gets the filename that should be previewed in a custom preview
widget. See gtk_file_chooser_set_preview_widget().
no file is selected, or if the selected file cannot be represented
as a local filename. Free with g_free()
the filename to preview, or %NULL if
Gets the URI that should be previewed in a custom preview
widget. See gtk_file_chooser_set_preview_widget().
selected. Free with g_free().
the URI for the file to preview, or %NULL if no file is
Gets the current preview widget; see
gtk_file_chooser_set_preview_widget().
the current preview widget, or %NULL
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.
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.
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.
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.
if no file is selected. Free with g_free()
The currently selected URI, or %NULL
Lists all the selected files and subfolders in the current folder of
files and subfolders in the current folder. Free the returned list
with g_slist_free(), and the filenames with g_free().
a #GSList containing the URIs of all selected
Gets whether a stock label should be drawn with the name of the previewed
file. See gtk_file_chooser_set_use_preview_label().
name of the previewed file, %FALSE otherwise.
%TRUE if the file chooser is set to display a label with the
Lists the current set of user-selectable filters; see
gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().
#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
Queries the list of shortcut folders in the file chooser, as set by
gtk_file_chooser_add_shortcut_folder_uri().
URIs, or %NULL if there are no shortcut folders. Free the returned
list with g_slist_free(), and the URIs with g_free().
A list of folder
Queries the list of shortcut folders in the file chooser, as set by
gtk_file_chooser_add_shortcut_folder().
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 list of
Removes @filter from the list of filters that the user can select between.
a #GtkFileFilter
Removes a folder from a file chooser's list of shortcut folders.
In the latter case, the @error will be set as appropriate.
%TRUE if the operation succeeds, %FALSE otherwise.
filename of the folder to remove
Removes a folder URI from a file chooser's list of shortcut folders.
In the latter case, the @error will be set as appropriate.
%TRUE if the operation succeeds, %FALSE otherwise.
URI of the folder to remove
Selects all the files in the current folder of a file chooser.
Selects the file referred to by @file. An internal function. See
_gtk_file_chooser_select_uri().
selected successfully, %FALSE otherwise.
%TRUE if both the folder could be changed and the path was
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.
selected successfully, %FALSE otherwise.
%TRUE if both the folder could be changed and the file was
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
selected successfully, %FALSE otherwise.
%TRUE if both the folder could be changed and the URI was
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.
the action that the file selector is performing
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.
%TRUE if the New 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.
otherwise.
%TRUE if the folder could be changed successfully, %FALSE
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().
otherwise.
%TRUE if the folder could be changed successfully, %FALSE
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.
otherwise.
%TRUE if the folder could be changed successfully, %FALSE
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.
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.
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.
Regardless of this setting, 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.
whether to confirm overwriting in save mode
Sets an application-supplied widget to provide extra options to the user.
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 <guimenuitem>File/Save As...</guimenuitem> 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 <guimenuitem>File/Save As...</guimenuitem> on it. 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:
|[
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);
}
]|
selected successfully, %FALSE otherwise.
%TRUE if both the folder could be changed and the file was
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. 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 <guimenuitem>File/Save As...</guimenuitem> 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 <guimenuitem>File/Save As...</guimenuitem> on it. 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:
|[
if (document_is_new)
{
/* the user just created a new document */
gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
gtk_file_chooser_set_current_name (chooser, "Untitled document");
}
else
{
/* the user edited an existing document */
gtk_file_chooser_set_filename (chooser, existing_filename);
}
]|
selected successfully, %FALSE otherwise.
%TRUE if both the folder could be changed and the file was
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 #GtkFileFilter
Sets whether only local files can be selected in the
file selector. If @local_only is %TRUE (the default),
then the selected file are files are guaranteed to be
accessible through the operating systems native file
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(),
%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
may display an internally generated preview of the current file or
it may display no preview at all.
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.
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.
%TRUE if multiple files can be selected.
Sets whether hidden files and folders are displayed in the file selector.
%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.
If the URI isn't in the current folder of @chooser, then the current folder
of @chooser will be changed to the folder containing @uri. This is equivalent
to a sequence of gtk_file_chooser_unselect_all() followed by
gtk_file_chooser_select_uri().
Note that the URI must exist, or nothing will be done except for the
directory change.
If you are implementing a <guimenuitem>File/Save As...</guimenuitem> 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 <guimenuitem>File/Save As...</guimenuitem> on it. 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:
|[
if (document_is_new)
{
/* the user just created a new document */
gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
gtk_file_chooser_set_current_name (chooser, "Untitled document");
}
else
{
/* the user edited an existing document */
gtk_file_chooser_set_uri (chooser, existing_uri);
}
]|
selected successfully, %FALSE otherwise.
%TRUE if both the folder could be changed and the URI was
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.
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.
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 #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.
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.
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.
<example id="gtkfilechooser-confirmation">
<title>Custom confirmation</title>
<programlisting>
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);
</programlisting>
</example>
action to take after emitting the signal.
a #GtkFileChooserConfirmation value that indicates which
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.
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 <keycap>Enter</keycap>.
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.
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.
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 <xref linkend="gtkfilechooser-preview"/>.
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.
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().
the mouse.
%TRUE if the button grabs focus when it is clicked with
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.
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.
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.
whether the button grabs focus when clicked with the mouse
Modifies the @title of the browse dialog used by @button.
the new browse dialog title.
Sets the width (in characters) that @button will use to @n_chars.
the new width, in characters.
Instance of the #GtkFileChooserDialog associated with the button.
Whether the #GtkFileChooserButton button grabs focus when it is clicked
with the mouse.
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 <emphasis>user</emphasis>
changes the file.
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.
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
These identify the various errors that can occur while calling
#GtkFileChooser functions.
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
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().
<refsect2 id="GtkFileFilter-BUILDER-UI">
<title>GtkFileFilter as GtkBuildable</title>
<para>
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> is the same
as calling gtk_recent_filter_add_mime_type() or gtk_recent_filter_add_pattern()
<example>
<title>A UI definition fragment specifying GtkFileFilter rules</title>
<programlisting><![CDATA[
<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>
]]></programlisting>
</example>
</para>
</refsect2>
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:
|[
GtkFileFilter *filter = gtk_file_filter_new ();
gtk_file_filter_add_pattern (filter, "*");
]|
a new #GtkFileFilter
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.
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.
name of a MIME type
Adds a rule allowing a shell style glob to a filter.
a shell style glob
Adds a rule allowing image files in the formats supported
by GdkPixbuf.
Tests whether a file should be displayed according to @filter.
The #GtkFileFilterInfo structure @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 #GtkFileFilterInfo structure containing information about a file.
Gets the human-readable name for the filter. See gtk_file_filter_set_name().
or %NULL. This value is owned by GTK+ and must not
be modified or freed.
The human-readable name of the filter,
Gets the fields that need to be filled in for the structure
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.
calling gtk_file_filter_filter()
bitfield of flags indicating needed fields when
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.
the human-readable-name for the filter, or %NULL to remove any existing name.
These flags indicate what parts of a #GtkFileFilterInfo struct
are filled or need to be filled.
The type of function that is used with custom filters, see
gtk_file_filter_add_custom().
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().
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:
<itemizedlist>
<listitem><para>
Themes, which may change widget sizes.
</para></listitem>
<listitem><para>
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 Windows or the framebuffer port of
GTK+, where different fonts are available.
</para></listitem>
<listitem><para>
Translation of text into other languages changes its size. Also,
display of non-English text will use a different font in many
cases.
</para></listitem>
</itemizedlist>
In addition, the fixed widget can't properly be mirrored in
right-to-left languages such as Hebrew and Arabic. i.e. normally
GTK+ will flip the interface to put labels to the right of the
thing they label, but it can't do that with #GtkFixed. So your
application will not be usable in right-to-left languages.
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.
Creates a new #GtkFixed.
a new #GtkFixed.
Moves a child of a #GtkFixed container to the given position.
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.
the widget to add.
the horizontal position to place the widget at.
the vertical position to place the widget at.
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 selection 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.
an internal copy of the font name which must not be freed.
Returns whether the font size will be shown in the label.
whether the font size will be shown in the label.
Returns whether the name of the font style will be shown in the label.
whether the font style will be shown in the label.
Retrieves the title of the font selection dialog.
an internal copy of the title string which must not be freed.
Returns whether the selected font is used in the label.
whether the selected font is used in the label.
Returns whether the selected size is used in the label.
whether the selected size is used in the label.
Sets or updates the currently-displayed font in font picker dialog.
font selection dialog exists, otherwise %FALSE.
Return value of gtk_font_selection_dialog_set_font_name() if the
Name of font to display in font selection dialog
If @show_size is %TRUE, the font size will be displayed along with the name of the selected font.
%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.
%TRUE if font style should be displayed in label.
Sets the title for the font selection dialog.
a string containing the font selection dialog title
If @use_font is %TRUE, the font name will be written using the selected font.
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.
If %TRUE, font name will be written using the selected size.
The name of the currently selected font.
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 selection 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_button_get_font_name()
to find out which font was just selected.
Note that this signal is only emitted when the <emphasis>user</emphasis>
changes the font. If you need to react to programmatic font changes
as well, use the notify::font-name signal.
Creates a new #GtkFontSelection.
a n ew #GtkFontSelection
Gets the #PangoFontFace representing the selected font group
details (i.e. family, slant, weight, width, etc).
selected font group details. The returned object is owned by
A #PangoFontFace representing the
This returns the #GtkTreeView which lists all styles available for
the selected font. For example, 'Regular', 'Bold', etc.
A #GtkWidget that is part of @fontsel
Gets the #PangoFontFamily representing the selected font family.
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 #PangoFontFamily representing the
This returns the #GtkTreeView that lists font families, for
example, 'Sans', 'Serif', etc.
A #GtkWidget that is part of @fontsel
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.
no font is selected. You must free this string with g_free().
A string with the name of the current font, or %NULL if
This returns the #GtkEntry used to display the font as a preview.
A #GtkWidget that is part of @fontsel
Gets the text displayed in the preview area.
This string is owned by the widget and should not be
modified or freed
the text displayed in the preview area.
The selected font size.
or -1 if no font size is selected.
A n integer representing the selected font size,
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.
A #GtkWidget that is part of @fontsel
This returns the #GtkTreeeView used to list font sizes.
A #GtkWidget that is part of @fontsel
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
such font exists or if the @fontsel doesn't belong to a particular
screen yet.
%TRUE if the font could be set successfully; %FALSE if no
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.
the text to display in the preview area
Creates a new #GtkFontSelectionDialog.
a new #GtkFontSelectionDialog
the title of the dialog window
Gets the 'Cancel' button.
for the 'Cancel' button.
the #GtkWidget used in the dialog
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.
font is selected. You must free this string with g_free().
A string with the name of the current font, or %NULL if no
Retrieves the #GtkFontSelection widget embedded in the dialog.
the embedded #GtkFontSelection
Gets the 'OK' button.
for the 'OK' button.
the #GtkWidget used in the dialog
Gets the text displayed in the preview area.
This string is owned by the widget and should not be
modified or freed
the text displayed in the preview area.
Sets the currently selected font.
%TRUE if the font selected in @fsd is now the
a font name like "Helvetica 12" or "Times Bold 18"
Sets the text displayed in the preview area.
the text to display in the preview area
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().)
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.
the text in the label, or %NULL if there
Retrieves the X and Y alignment of the frame's label. See
gtk_frame_set_label_align().
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.
Retrieves the shadow type of the frame. See
gtk_frame_set_shadow_type().
the current shadow type of the frame.
Sets the text of the label. If @label is %NULL,
the current label is removed.
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.
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 label widget for the frame. This is the widget that
will appear embedded in the top edge of the frame as a
title.
the new label widget
Sets the shadow type for @frame.
the new #GtkShadowType
GtkGradient is a boxed type that represents a gradient.
It is the result of parsing a
<link linkend="gtkcssprovider-gradients">gradient expression</link>.
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.
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().
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().
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.
offset for the color stop
color to use
Increases the reference count of @gradient.
The same @gradient
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.
%TRUE if the gradient has been resolved
#GtkStyleProperties to use when resolving named colors
return location for the resolved pattern
Decreases the reference count of @gradient, freeing its memory
if the reference count reaches 0.
GtkGrid is a container which arranges its child widgets in
rows and columns. It is a very similar to #GtkTable and #GtkBox,
but it consistently uses #GtkWidget's #GtkWidget:margin and #GtkWidget:expand
properties instead of custom child properties, and it fully supports
<link linkend="geometry-management">height-for-width geometry management</link>.
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().
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.
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
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
the widget to add
the child of @grid that @child will be placed next to
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 whether all columns of @grid have the same width.
whether all columns of @grid have the same width.
Returns the amount of space between the columns of @grid.
the column spacing of @grid
Returns whether all rows of @grid have the same height.
whether all rows of @grid have the same height.
Returns the amount of space between the rows of @grid.
the row spacing of @grid
Sets whether all columns of @grid will have the same width.
%TRUE to make columns homogeneous
Sets the amount of space between columns of @grid.
the amount of space to insert between columns
Sets whether all rows of @grid will have the same height.
%TRUE to make rows homogeneous
Sets the amount of space between rows of @grid.
the amount of space to insert between rows
#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.
Creates a new #GtkHBox.
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 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.
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.
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.
since they may be transitory, or %FALSE if they should consider
the color value status to be final.
%TRUE if clients can ignore changes to the color value,
Sets the current color in an HSV color selector.
Color component values must be in the [0.0, 1.0] range.
Hue
Saturation
Value
Sets the size and ring width of an HSV color selector.
Diameter for the hue ring
Width of the hue ring
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.
a new #GtkHScale
minimum value
maximum value
step increment (tick size) used with keyboard shortcuts
Creates a new horizontal scrollbar.
the new #GtkHScrollbar
the #GtkAdjustment to use, or %NULL to create a new adjustment
Whether the handlebox's child is currently detached.
%TRUE if the child is currently detached, otherwise %FALSE
Gets the handle position of the handle box. See
gtk_handle_box_set_handle_position().
the current handle position.
Gets the type of shadow drawn around the handle box. See
gtk_handle_box_set_shadow_type().
the type of shadow currently drawn around the handle box.
Gets the edge used for determining reattachment of the handle box. See
gtk_handle_box_set_snap_edge().
is determined (as per default) from the handle position.
the edge used for determining reattachment, or (GtkPositionType)-1 if this
#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 user may change the current input method via a context menu, unless the
#GtkSettings:gtk-show-input-method-menu GtkSettings property is set to FALSE.
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 #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:
<informalexample><programlisting>
void im_module_init(#GTypeModule *module);
</programlisting></informalexample>
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.
<informalexample><programlisting>
void im_module_exit(void);
</programlisting></informalexample>
Here goes any cleanup code your input method might require on module unload.
<informalexample><programlisting>
void im_module_list(const #GtkIMContextInfo ***contexts, int *n_contexts)
{
*contexts = info_list;
*n_contexts = G_N_ELEMENTS (info_list);
}
</programlisting></informalexample>
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.
<informalexample><programlisting>
#GtkIMContext * im_module_create(const #gchar *context_id);
</programlisting></informalexample>
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 <filename>gtk.immodules</filename> needs to be
regenerated by <link linkend="gtk-query-immodules-3.0">gtk-query-immodules-3.0</link>,
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.
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.
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.
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.
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.
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.
you must free the result stored in *text.
%TRUE if surrounding text was provided; in this case
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().
(out) 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.
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.
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.
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.
text surrounding the insertion point, as UTF-8. the preedit string should not be included within
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.
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.
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.
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.
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.
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.
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.
you must free the result stored in *text.
%TRUE if surrounding text was provided; in this case
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().
(out) 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.
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.
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.
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.
text surrounding the insertion point, as UTF-8. the preedit string should not be included within
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.
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.
offset from cursor position in chars; a negative value means start before the cursor.
number of characters to delete.
the client window. This may be %NULL to indicate that the previous client window no longer exists.
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.
the key event
new location
whether the IM context should use the preedit string.
text surrounding the insertion point, as UTF-8. the preedit string should not be included within
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
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().
(out) location to store byte index of the insertion cursor within @text.
Bookkeeping information about a loadable input method.
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.)
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.
a #GtkMenuShell
Gets the id of the currently active slave of the @context.
the id of the currently active slave
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.
the id to use
Creates a new #GtkIconFactory. An icon factory manages a collection
of #GtkIconSet<!-- -->s; 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<!-- -->s 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.
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.
a #GtkIconSet, or %NULL
an icon name
Adds the given @icon_set to the icon factory, under the name
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.
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.
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.
icon set of @stock_id.
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.
Creates a #GtkIconInfo for a #GdkPixbuf.
a #GtkIconInfo
a #GtkIconTheme
the pixbuf to wrap in a #GtkIconInfo
Make a copy of a #GtkIconInfo.
the new GtkIconInfo
Free a #GtkIconInfo and associated information
Fetches the set of attach points for an icon. An attach point
is a location in the icon that can be used as anchor points for attaching
emblems or overlays to the icon.
%TRUE if there are any attach points for the icon.
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 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.
size is known for the icon.
the base size, or 0, if no base
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().
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.
the built-in image pixbuf, or %NULL. No
Gets the display name for an icon. A display name is a
string to be used in place of the icon name in a user
visible context like a list of icons.
the icon doesn't have a specified display name. This value
is owned @icon_info and must not be modified or free.
the display name for the icon or %NULL, if
Gets the coordinates of a rectangle within the icon
that can be used for display of information such
as a preview of the contents of a text file.
See gtk_icon_info_set_raw_coordinates() for further
information about the coordinate system.
%TRUE if the icon has an embedded rectangle
#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().
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.
the filename for the icon, or %NULL
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.
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.
the rendered icon; this may be a newly
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 <ulink url="http://www.freedesktop.org/wiki/SymbolicIcons">Symbolic Icons spec</ulink>
for more information about symbolic icons.
a #GdkPixbuf representing the loaded 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)
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 #GtkStyleContext
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.
a #GdkPixbuf representing the loaded icon
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.
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()
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.
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.
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.
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.
a #GtkIconSource
Copies @icon_set by value.
a new #GtkIconSet identical to the first.
Obtains a list of icon sizes this icon set can render. The returned
array must be freed with g_free().
return location for array of sizes
location to store number of elements in returned array
Increments the reference count on @icon_set.
@icon_set.
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.
a #GdkPixbuf to be displayed
a #GtkStyle associated with @widget, or %NULL
text direction
widget state
icon size. 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.
a #GdkPixbuf to be displayed
a #GtkStyleContext
icon size. A size of (GtkIconSize)-1 means render at the size of the source and don't scale.
Decrements the reference count on @icon_set, and frees memory
if the reference count reaches 0.
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.
a new #GtkIconSource
Creates a copy of @source; mostly useful for language bindings.
a new #GtkIconSource
Frees a dynamically-allocated icon source, along with its
filename, size, and pixbuf fields if those are not %NULL.
Obtains the text direction this icon source applies to. The return
value is only useful/meaningful if the text direction is <emphasis>not</emphasis>
wildcarded.
text direction this source matches
Gets the value set by gtk_icon_source_set_direction_wildcarded().
%TRUE if this icon source is a base for any text direction variant
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.
be modified or freed.
image filename. This string must not
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.
icon name. This string must not be modified or freed.
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.
source pixbuf
Obtains the icon size this source applies to. The return value
is only useful/meaningful if the icon size is <emphasis>not</emphasis> wildcarded.
icon size this source matches.
Gets the value set by gtk_icon_source_set_size_wildcarded().
%TRUE if this icon source is a base for any icon size variant
Obtains the widget state this icon source applies to. The return
value is only useful/meaningful if the widget state is <emphasis>not</emphasis>
wildcarded.
widget state this source matches
Gets the value set by gtk_icon_source_set_state_wildcarded().
%TRUE if this icon source is a base for any widget state variant
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.
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.
%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.
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.
name of icon to use
Sets a pixbuf to use as a base image when creating icon variants
for #GtkIconSet.
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.
icon size 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.
%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.
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.
%TRUE to wildcard the widget state
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().
the name of the icon to register
the size 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().
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.
A unique #GtkIconTheme associated with
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.
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 unique #GtkIconTheme associated with
a #GdkScreen
Appends a directory to the search path.
See gtk_icon_theme_set_search_path().
directory name to append to the icon path
Looks up a named icon and returns a structure 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.
about the icon, or %NULL if the icon wasn't found. Free with
gtk_icon_info_free()
a #GtkIconInfo structure containing information
%NULL-terminated array of icon names to lookup
desired icon size
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.)
Free with g_free().
the name of an example icon or %NULL.
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.
describing the sizes at which the icon is available. The array
should be freed with g_free() when it is no longer needed.
An newly allocated array
the name of an icon
Gets the current search path. See gtk_icon_theme_set_search_path().
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.
icon for @icon_name.
%TRUE if @icon_theme includes an
the name of an icon
Gets the list of contexts available within the current
hierarchy of icon themes
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 #GList list
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".
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 #GList list
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.
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.
the rendered icon; this may be a
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 and returns a structure containing
information such as the filename of the icon.
The icon can then be rendered into a pixbuf using
gtk_icon_info_load_icon().
information about the icon, or %NULL if the icon
wasn't found. Free with gtk_icon_info_free()
a #GtkIconInfo structure containing
the #GIcon to look up
desired icon size
flags modifying the behavior of the icon lookup
Looks up a named icon and returns a structure 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.)
about the icon, or %NULL if the icon wasn't found. Free with
gtk_icon_info_free()
a #GtkIconInfo structure containing information
the name of the icon to lookup
desired icon size
flags modifying the behavior of the icon lookup
Prepends a directory to the search path.
See gtk_icon_theme_set_search_path().
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.
to be reloaded.
%TRUE if the icon theme has changed and needed
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().
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 #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. (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
(This is legacy feature, and new icons should be put
into the default icon theme, which is called DEFAULT_THEME_NAME,
rather than directly on the icon path.)
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.
Error codes for GtkIconTheme operations.
#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.
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.
The #GtkTreePath to be activated
Selects all the icons. @icon_view must has its selection mode set
to #GTK_SELECTION_MULTIPLE.
Unselects all the icons.
Converts widget coordinates to coordinates for the bin_window,
as expected by e.g. gtk_icon_view_get_path_at_pos().
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 #GtkTreePath in @icon_view
Turns @icon_view into a drop destination for automatic DND. Calling this
method sets #GtkIconView:reorderable to %FALSE.
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.
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
Returns the value of the ::column-spacing property.
the space between columns
Returns the value of the ::columns property.
the number of columns, or -1
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.
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.
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.
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
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
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
Returns the value of the ::item-padding property.
the padding around items
Gets the row in which the item @path is currently
displayed. Row numbers start at 0.
The row in which the item is displayed
the #GtkTreePath of the item
Returns the value of the ::item-width property.
the width of a single item, or -1
Returns the value of the ::margin property.
the space at the borders
Returns the column with markup text for @icon_view.
the markup column, or -1 if it's unset.
Returns the model the #GtkIconView is based on. Returns %NULL if the
model is unset.
currently being used.
A #GtkTreeModel, or %NULL if none is
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.
if no icon exists at that position.
The #GtkTreePath corresponding to the icon or %NULL
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.
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.
Returns the value of the ::row-spacing property.
the space between rows
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 #GtkTreeRowReference<!-- -->s.
To do this, you can use gtk_tree_row_reference_new().
To free the return value, use:
|[
g_list_foreach (list, (GFunc)gtk_tree_path_free, NULL);
g_list_free (list);
]|
A #GList containing a #GtkTreePath for each selected row.
Gets the selection mode of the @icon_view.
the current selection mode
Returns the value of the ::spacing property.
the space between cells
Returns the column with text for @icon_view.
the text column, or -1 if it's unset.
Returns the column of @icon_view's model which is being used for
displaying tooltips on @icon_view's rows.
used, or -1 if this is disabled.
the index of the tooltip column that is currently being
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
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
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
Return location for start of region, or %NULL
Return location for end of region, or %NULL
Activates the item determined by @path.
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 #GtkTreePath to check selection on.
Moves the alignments of @icon_view to the position specified by @path.
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.
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.
Selects the row at @path.
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.
The function to call for each selected icon.
User data to pass to the function.
Sets the ::column-spacing property which specifies the space
which is inserted between the columns of the icon view.
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.
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 <literal>gtk_widget_grab_focus
(icon_view)</literal> in order to give keyboard focus to the widget.
Please note that editing can only happen when the widget is realized.
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.
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.
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.
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.
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.
the margin
Sets the column with markup information for @icon_view to be
If the markup column is set to something, it overrides
the text column set by gtk_icon_view_set_text_column().
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.
The model.
Sets the column with pixbufs for @icon_view to be @column. The pixbuf
column must be of type #GDK_TYPE_PIXBUF
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.
%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.
the row spacing
Sets the selection mode of the @icon_view.
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.
the spacing
Sets the column with text for @icon_view to be @column. The text
column must be of type #G_TYPE_STRING.
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 #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
Note that the signal handler sets the text with gtk_tooltip_set_markup(),
so &, <, etc have to be escaped in the text.
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 #GtkTooltip
a #GtkTreePath
Unselects all the icons.
Unselects the row at @path.
The #GtkTreePath to be unselected.
Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this
method sets #GtkIconView:reorderable to %FALSE.
Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this
method sets #GtkIconView:reorderable to %FALSE.
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 <link linkend="keybinding-signals">keybinding signal</link>
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 or the user double
clicks an item. It is also emitted when a non-editable item
pressed.
the #GtkTreePath for the activated item
The ::move-cursor signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
<itemizedlist>
<listitem>Arrow keys which move by individual steps</listitem>
<listitem>Home/End keys which move to the first/last item</listitem>
<listitem>PageUp/PageDown which move by "pages"</listitem>
</itemizedlist>
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 <link linkend="keybinding-signals">keybinding signal</link>
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 <link linkend="keybinding-signals">keybinding signal</link>
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 <link linkend="keybinding-signals">keybinding signal</link>
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 <link linkend="keybinding-signals">keybinding signal</link>
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.
The #GtkTreePath to be activated
An enum for determining where a dropped item goes.
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:
<informalexample><programlisting>
GtkWidget *image;
image = gtk_image_new_from_file ("myfile.png");
</programlisting></informalexample>
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.
<example>
<title>Handling button press events on a
<structname>GtkImage</structname>.</title>
<programlisting>
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;
}
</programlisting>
</example>
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 <application>gdk-pixbuf-csource</application>. This program
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().
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
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
a stock icon size
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.
a new #GtkImage
a #GtkIconSet
a stock icon size
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_set().
a new #GtkImage
a #GdkPixbuf, or %NULL
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().
a new #GtkImage displaying the stock icon
a stock icon name
a stock icon size
Resets the image to be empty.
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 image is empty
the displayed animation, or %NULL if
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.
place to store a #GIcon, or %NULL
place to store an icon size, 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.
place to store an icon name, or %NULL
place to store an icon size, 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()).
location to store a #GtkIconSet, or %NULL
location to store a stock icon size, 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 image is empty
the displayed pixbuf, or %NULL if
Gets the pixel size used for named icons.
the pixel size used for named icons.
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.
place to store a stock icon name, or %NULL
place to store a stock icon size, 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
Causes the #GtkImage to display the given animation (or display
nothing, if you set the animation to %NULL).
the #GdkPixbufAnimation
See gtk_image_new_from_file() for details.
a filename or %NULL
See gtk_image_new_from_gicon() for details.
an icon
an icon size
See gtk_image_new_from_icon_name() for details.
an icon name
an icon size
See gtk_image_new_from_icon_set() for details.
a #GtkIconSet
a stock icon size
See gtk_image_new_from_pixbuf() for details.
a #GdkPixbuf or %NULL
See gtk_image_new_from_stock() for details.
a stock icon name
a stock icon size
Sets the pixel size to use for named icons. If the pixel size is set
to a value != -1, it is used instead of the icon size set by
gtk_image_set_from_icon_name().
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.
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.
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.
Creates a new #GtkImageMenuItem with an empty label.
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.
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.
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.
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
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
Checks whether the label set in the menuitem is used as a
stock id to select the stock item for the item.
stock id to select the stock item for the item
%TRUE if the label set in the menuitem is used as a
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()).
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.
%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 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.
%TRUE if the menuitem should use a stock item
The Accel Group to use for stock accelerator keys
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.
If %TRUE, the label set in the menuitem is used as a
stock id to select the stock item for the item.
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.
#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 horizontal action area at the bottom, #GtkInfoBar has a
vertical 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+ uses the message type
to determine the background color of the message area.
<example>
<title>Simple GtkInfoBar usage.</title>
<programlisting>
/* set up info bar */
info_bar = gtk_info_bar_new ();
gtk_widget_set_no_show_all (info_bar, TRUE);
message_label = gtk_label_new ("");
gtk_widget_show (message_label);
content_area = gtk_info_bar_get_content_area (GTK_INFO_BAR (info_bar));
gtk_container_add (GTK_CONTAINER (content_area), message_label);
gtk_info_bar_add_button (GTK_INFO_BAR (info_bar),
GTK_STOCK_OK, GTK_RESPONSE_OK);
g_signal_connect (info_bar, "response",
G_CALLBACK (gtk_widget_hide), NULL);
gtk_table_attach (GTK_TABLE (table),
info_bar,
0, 1, 2, 3,
GTK_EXPAND | GTK_FILL, 0,
0, 0);
/* ... */
/* show an error message */
gtk_label_set_text (GTK_LABEL (message_label), error_message);
gtk_info_bar_set_message_type (GTK_INFO_BAR (info_bar),
GTK_MESSAGE_ERROR);
gtk_widget_show (info_bar);
</programlisting>
</example>
<refsect2 id="GtkInfoBar-BUILDER-UI">
<title>GtkInfoBar as GtkBuildable</title>
<para>
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".
</para>
<para>
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).
</para>
</refsect2>
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
Emits the 'response' signal with the given @response_id.
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.
an activatable widget
response ID for @child
Adds a button with the given text (or a stock button, if button_text
is a stock ID) 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
text of button, or stock ID
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.
button text or stock ID
Returns the action area of @info_bar.
the action area
Returns the content area of @info_bar.
the content area
Returns the message type of the message area.
the message type of the message area.
Emits the 'response' signal with the given @response_id.
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 response ID
Sets the message type of the message area.
GTK+ uses this type to determine what color to use
when drawing the message area.
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 response ID
TRUE for sensitive
The type of the message.
The type is used to determine the colors to use in the info bar.
The following symbolic color names can by used to customize
these colors:
"info_fg_color", "info_bg_color",
"warning_fg_color", "warning_bg_color",
"question_fg_color", "question_bg_color",
"error_fg_color", "error_bg_color".
"other_fg_color", "other_bg_color".
If the type is #GTK_MESSAGE_OTHER, no info bar is painted but the
colors are still set.
The ::close signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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 response ID
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.
Sets the #GdkScreen where the #GtkInvisible object will be displayed.
a #GdkScreen.
Describes how a rendered element connects to adjacent elements.
Used for justifying the text inside a #GtkLabel widget. (See also
#GtkAlignment).
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()
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
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)).
if none was set.
the attribute list, or %NULL
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.
not be freed or modified.
the currently active URI. The string is owned by GTK+ and must
Returns the ellipsizing position of the label. See gtk_label_set_ellipsize().
#PangoEllipsizeMode
Returns the justification of the label. See gtk_label_set_justify().
#GtkJustification
Fetches the text from a label widget including any embedded
underlines indicating mnemonics and Pango markup. (See
gtk_label_get_text()).
owned by the widget and must not be modified or freed.
the text of the label widget. This string is
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
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 a #GTK_NO_WINDOW widget. Remember
when using the #PangoLayout functions you need to convert to
and from pixels using PANGO_PIXELS() or #PANGO_SCALE.
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.
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.
Retrieves the desired maximum width of @label, in characters. See
gtk_label_set_width_chars().
the maximum width of the label in characters.
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_VoidSymbol.
GDK keyval usable for accelerators, or #GDK_VoidSymbol
Retrieves the target of the mnemonic (keyboard shortcut) of this
label. See gtk_label_set_mnemonic_widget().
or %NULL if none has been set and the default algorithm will be used.
the target of the label's mnemonic,
Gets the value set by gtk_label_set_selectable().
%TRUE if the user can copy text from the label
Gets the selected range of characters in the label, returning %TRUE
if there's a selection.
%TRUE if selection is non-empty
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.
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())
string used by the label, and must not be modified.
the text in the label widget. This is the internal
Returns whether the label is currently keeping track
of clicked links.
%TRUE if clicked links are remembered
Returns whether the label's text is interpreted as marked up with
the <link linkend="PangoMarkupFormat">Pango text markup
language</link>. See gtk_label_set_use_markup ().
%TRUE if the label's text will be parsed for markup.
Returns whether an embedded underline in the label indicates a
mnemonic. See gtk_label_set_use_underline().
the mnemonic accelerator keys.
%TRUE whether an embedded underline in the label indicates
Retrieves the desired width of @label, in characters. See
gtk_label_set_width_chars().
the width of the label in characters.
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
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.
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.
<note><para>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.</para></note>
a #PangoAttrList
if there is not enough space to render the entire string.
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_misc_set_alignment() instead. gtk_label_set_justify() has no
effect on labels containing only a single line.
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.
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().
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.
the line wrapping mode
Parses @str which is marked up with the <link
linkend="PangoMarkupFormat">Pango text markup language</link>, 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()<!-- -->:
|[
char *markup;
markup = g_markup_printf_escaped ("<span style=\"italic\">%s</span>", str);
gtk_label_set_markup (GTK_LABEL (label), markup);
g_free (markup);
]|
a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
Parses @str which is marked up with the
<link linkend="PangoMarkupFormat">Pango text markup language</link>,
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 markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
Sets the desired maximum width in characters of @label to @n_chars.
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.
the target #GtkWidget
Selectable labels allow the user to select text from the label, for
copy-and-paste.
%TRUE to allow selecting text in the label
Sets whether the label is in single line mode.
%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 will also clear any previously set mnemonic accelerators.
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 string
Sets whether the label should keep track of clicked
links (and use a different color for them).
%TRUE to track visited links
Sets whether the text of the label contains markup in <link
linkend="PangoMarkupFormat">Pango's text markup
language</link>. See gtk_label_set_markup().
%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.
%TRUE if underlines in the text indicate mnemonics
Sets the desired width in characters of @label to @n_chars.
the new desired width, in characters.
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, wrapped, or ellipsized.
The preferred place to ellipsize the string, if the label does
not have enough room to display the entire string, specified as a
#PangoEllisizeMode.
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 tab's #GtkNotebook:tab-expand 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 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 <link linkend="label-text-layout">text layout</link>
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 clicked. It will then apply the ::visited-link-color
color, instead of ::link-color.
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 <link linkend="label-text-layout">text layout</link>
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.
A <link linkend="keybinding-signals">keybinding signal</link>
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().
%TRUE if the link has been activated
the URI that is activated
The ::copy-clipboard signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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.
<itemizedlist>
<listitem>Arrow keys move by individual characters/lines</listitem>
<listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
<listitem>Home/End keys move to the ends of the buffer</listitem>
</itemizedlist>
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 but paint a blank background by default. It's
different in that it supports scrolling natively (you can add it to a
#GtkScrolledWindow), and it can contain child widgets, since it's a
#GtkContainer. However if you're just going to draw, a #GtkDrawingArea
is a better choice since it has lower overhead.
When handling expose events on a #GtkLayout, you must draw to
GTK_LAYOUT (layout)->bin_window, rather than to
GTK_WIDGET (layout)->window, as you would for a drawing
area.
Creates a new #GtkLayout. Unless you have a specific adjustment
you'd like the layout to use for scrolling, pass %NULL for
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
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.
horizontal scroll adjustment
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 ().
location to store the width set on
location to store the height set on
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.
vertical scroll adjustment
Moves a current child of @layout to a new position.
a current child of @layout
X position to move to
Y position to move to
Adds @child_widget to @layout, at position (@x,@y).
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.
new scroll adjustment
Sets the size of the scrollable area of the layout.
width of entire scrollable area
height of entire scrollable area
Sets the vertical scroll adjustment for the layout.
See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details.
new scroll adjustment
The type of license for an application.
This enumeration can be expanded at later date.
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() 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.
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().
and should not be modified or freed.
a valid URI. The returned string is owned by the link button
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
Sets @uri as the URI where the #GtkLinkButton points. As a side-effect
this unsets the 'visited' state of the button.
a valid URI
Sets the 'visited' state of the URI where the #GtkLinkButton
points. See gtk_link_button_get_visited() for more details.
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() 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 <structname>GtkLinkButtonClass</structname> structure contains only
private data.
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, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
GDK_TYPE_PIXBUF);</literal> 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
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().
An unset #GtkTreeIter to set to the appended row
Removes all rows from the list store.
Creates a new row at @position. @iter will be changed to point to this new
row. If @position 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().
An unset #GtkTreeIter to set to the new row
position to insert the new row
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().
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().
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 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
<literal>gtk_list_store_insert_with_values(list_store, iter, position...)</literal>
has the same effect as calling
|[
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.
An unset #GtkTreeIter to set to the new row, or %NULL.
position to insert the new row
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.
An unset #GtkTreeIter to set to the new row, or %NULL.
position to insert the new row
an array of column numbers
an array of GValues
the length of the @columns and @values arrays
<warning>This function is slow. Only use it for debugging and/or testing
purposes.</warning>
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 #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 #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 #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().
An unset #GtkTreeIter to set to the prepend row
Removes the given row from the list store. After being removed,
to the last row in @list_store.
%TRUE if @iter is valid, %FALSE if not.
A valid #GtkTreeIter
Reorders @store to follow the order indicated by @new_order. Note that
this function only works with unsorted stores.
an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. @new_order<literal>[newpos] = oldpos</literal>.
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 <literal>gtk_list_store_set (store, iter,
0, "Foo", -1)</literal>.
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.
row iterator
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.
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 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 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 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 #GtkTreeIter.
Another #GtkTreeIter.
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 #GtkOptionMenu.
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.
<example>
<title>Connecting the popup signal handler.</title>
<programlisting>
/<!---->* connect our handler which will popup the menu *<!---->/
g_signal_connect_swapped (window, "button_press_event",
G_CALLBACK (my_popup_handler), menu);
</programlisting>
</example>
<example>
<title>Signal handler which displays a popup menu.</title>
<programlisting>
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 == 3)
{
gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
event_button->button, event_button->time);
return TRUE;
}
}
return FALSE;
}
</programlisting>
</example>
Creates a new #GtkMenu
a new #GtkMenu
Returns a list of the menus which are attached to this widget.
This list is owned by GTK+ and must not be modified.
of menus attached to his widget.
the list
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,
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 #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.
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.
Gets the #GtkAccelGroup which holds global accelerators for the
menu. See gtk_menu_set_accel_group().
the #GtkAccelGroup associated with the menu
Retrieves the accelerator path set on the menu.
the accelerator path set on the menu.
Returns the selected menu item from the menu. This is used by the
#GtkOptionMenu.
in the menu. If a selection has not yet been made, the
first menu item is selected.
the #GtkMenuItem that was last selected
Returns the #GtkWidget that the menu is attached to.
the #GtkWidget that the menu is attached to
Retrieves the number of the monitor on which to show the menu.
be popped up or -1, if no monitor has been set
the number of the monitor on which the menu should
Returns whether the menu reserves space for toggles and
icons, regardless of their actual presence.
Whether the menu reserves toggle space
Returns whether the menu is torn off.
See gtk_menu_set_tearoff_state().
%TRUE if the menu is currently torn off.
Returns the title of the menu. See gtk_menu_set_title().
has no title set on it. This string is owned by GTK+
and should not be modified or freed.
the title of the menu, or %NULL if the menu
Removes the menu from the screen.
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,
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,
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.
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 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,
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,
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.
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.
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.
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.
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
<literal>gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File");</literal>
has been called, assign its items the accel paths:
<literal>"<Gnumeric-Sheet>/File/New"</literal> and <literal>"<Gnumeric-Sheet>/File/Exit"</literal>.
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 accelerator path
Selects the specified menu item within the menu. This is used by
the #GtkOptionMenu and should not be used by anyone else.
the index of the menu item to select. Iindex values are from 0 to n-1
Informs GTK+ on which monitor a menu should be popped up.
See gdk_screen_get_monitor_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.
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.
whether to reserve size for toggles
Sets the #GdkScreen on which the menu will be displayed.
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.
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 string containing the title for the menu
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.
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 monitor the menu will be popped up on.
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 #GtkScrollType
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.
Creates a new #GtkMenuBar
the new menu bar, as a #GtkWidget
Retrieves the current child pack direction of the menubar.
See gtk_menu_bar_set_child_pack_direction().
the child pack direction
Retrieves the current pack direction of the menubar.
See gtk_menu_bar_set_pack_direction().
the pack direction
Sets how widgets should be packed inside the children of a menubar.
a new #GtkPackDirection
Sets how items should be packed inside a menubar.
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.
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.
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
Sets @text on the @menu_item label
string used by the label, and must not be modified.
The text in the @menu_item label. This is the internal
Sets @text on the @menu_item label
the text you want to set
Retrieve the accelerator path that was previously set on @menu_item.
See gtk_menu_item_set_accel_path() for details.
item's functionality, or %NULL if not set
the accelerator path corresponding to this menu
Sets @text on the @menu_item label
string used by the label, and must not be modified.
The text in the @menu_item label. This is the internal
Returns whether the @menu_item reserves space for
the submenu indicator, regardless if it has a submenu
or not.
submenu indicator
%TRUE if @menu_item always reserves space for the
Gets whether the menu item appears justified at the right
side of the menu bar.
far right if added to a menu bar.
%TRUE if the menu item will appear at the
Gets the submenu underneath this menu item, if any.
See gtk_menu_item_set_submenu().
submenu for this menu item, or %NULL if none
Checks if an underline in the text indicates the next character
should be used for the mnemonic accelerator key.
indicates the mnemonic accelerator key.
%TRUE if an embedded underline in the label
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().
accelerator path, corresponding to this menu item's functionality, or %NULL to unset the current path.
Sets @text on the @menu_item label
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.
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 %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.
the submenu, or %NULL
If true, an underline in the text indicates the next character
should be used for the mnemonic accelerator key.
%TRUE if underlines in the text indicate mnemonics
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.
the text you want to set
The text in the @menu_item label. This is the internal
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()
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.
Cancels the selection within the menu shell.
Deactivates the menu shell.
Typically this results in the menu shell being erased
from the screen.
Adds a new #GtkMenuItem to the menu shell's item list
at the position indicated by @position.
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.
The #GtkMenuItem to select
Activates the menu item within the menu shell.
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.
The #GtkMenuItem to add
Cancels the selection within the menu shell.
Deactivates the menu shell.
Typically this results in the menu shell being erased
from the screen.
Deselects the currently selected item from the menu shell,
if any.
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
Gets the currently selected item.
the currently selected item
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.
Adds a new #GtkMenuItem to the menu shell's item list
at the position indicated by @position.
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.
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.
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.
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 explicitely.
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()
%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.
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.
The #GtkMenuItem to select
The #GtkMenuItem to add
The position in the item list where @child is added. Positions are numbered from 0 to n-1
Creates a new #GtkMenuToolButton using @icon_widget as icon and
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.
the new #GtkMenuToolButton
the name of a stock item
Gets the #GtkMenu associated with #GtkMenuToolButton.
with #GtkMenuToolButton
the #GtkMenu associated
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.
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.
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.
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_get_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.
#GtkMessageDialog presents a dialog with an image representing the type of
message (Error, Question, etc.) alongside 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.
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.
<example>
<title>A modal dialog.</title>
<programlisting>
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_MESSAGE_ERROR,
GTK_BUTTONS_CLOSE,
"Error loading file '%s': %s",
filename, g_strerror (errno));
gtk_dialog_run (GTK_DIALOG (dialog));
gtk_widget_destroy (dialog);
</programlisting>
</example>
You might do a non-modal #GtkMessageDialog as follows:
<example>
<title>A non-modal dialog.</title>
<programlisting>
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_MESSAGE_ERROR,
GTK_BUTTONS_CLOSE,
"Error loading file '%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);
</programlisting>
</example>
<refsect2 id="GtkMessageDialog-BUILDER-UI">
<title>GtkMessageDialog as GtkBuildable</title>
<para>
The GtkMessageDialog implementation of the GtkBuildable interface exposes
the message area as an internal child with the name "message_area".
</para>
</refsect2>
Creates a new message dialog, which is a simple dialog with an icon
indicating the dialog type (error, warning, etc.) and 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
Creates a new message dialog, which is a simple dialog with an icon
indicating the dialog type (error, warning, etc.) and some text which
is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
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.
|[
GtkWidget *dialog;
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
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
Sets the secondary text of the message dialog to be @message_format (with
printf()-style), which is marked up with the
<link linkend="PangoMarkupFormat">Pango text markup language</link>.
Note that setting a secondary text makes the primary text become
bold, unless you have provided explicit markup.
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.
<informalexample><programlisting>
gchar *msg;
msg = g_markup_printf_escaped (message_format, ...);
gtk_message_dialog_format_secondary_markup (message_dialog, "%s", msg);
g_free (msg);
</programlisting></informalexample>
printf()-style markup string (see
Sets the secondary text of the message dialog to be @message_format
(with printf()-style).
Note that setting a secondary text makes the primary text become
bold, unless you have provided explicit markup.
printf()-style format string, or %NULL
Gets the dialog's image.
the dialog's image
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,
on the right side of the dialog's image (or on the left for right-to-left
languages). See gtk_dialog_get_content_area() for the corresponding
function in the parent #GtkDialog.
"message area" in the @message_dialog.
A #GtkVBox corresponding to the
Sets the dialog's image to @image.
the image
Sets the text of the message dialog to be @str, which is marked
up with the <link linkend="PangoMarkupFormat">Pango text markup
language</link>.
markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
The image for this dialog.
The #GtkVBox 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 type is used to determine
the image that is shown in the dialog, unless the image is
explicitly set by the ::image property.
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.
Gets the X and Y alignment of the widget within its allocation.
See gtk_misc_set_alignment().
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().
location to store padding in the X direction, or %NULL
location to store padding in the Y direction, or %NULL
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
Gets the screen on which windows of the #GtkMountOperation
will be shown.
the screen on which windows of @op are shown
Returns whether the #GtkMountOperation is currently displaying
a window.
%TRUE if @op is currently displaying a window
Sets the transient parent for windows shown by the
#GtkMountOperation.
transient parent of the window, or %NULL
Sets the screen to show windows of the #GtkMountOperation on.
a #GdkScreen
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())
<refsect2 id="GtkNotebook-BUILDER-UI">
<title>GtkNotebook as GtkBuildable</title>
<para>
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.
</para>
<example>
<title>A UI definition fragment with GtkNotebook</title>
<programlisting><![CDATA[
<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>
]]></programlisting>
</example>
</refsect2>
Creates a new #GtkNotebook widget with no pages.
the newly created #GtkNotebook
Appends a page to @notebook.
page in the notebook, or -1 if function fails
the index (starting from 0) of the appended
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.
page in the notebook, or -1 if function fails
the index (starting from 0) of the appended
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.
Gets one of the action widgets. See gtk_notebook_set_action_widget().
or %NULL when this action widget has not been set
The action widget with the given @pack_type
pack type of the action widget to receive
Returns the page number of the current page.
page in the notebook. If the notebook has no pages,
then -1 will be returned.
the index (starting from 0) of the current
Gets the current group name for @notebook.
or %NULL if none is set.
the group name,
Retrieves the menu label widget of the page containing @child.
notebook page does not have a menu label other than the
default (the tab label).
the menu label, or %NULL if the
a widget contained in a page of @notebook
Retrieves the text of the menu label for the page containing
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.
the text of the tab label, or %NULL if the
the child widget of a page of the notebook.
Gets the number of pages in a notebook.
the number of pages in the notebook
Returns the child widget contained in page number @page_num.
if @page_num is out of bounds
the child widget, or %NULL
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
Returns whether a bevel will be drawn around the notebook pages.
See gtk_notebook_set_show_border().
%TRUE if the bevel is drawn
Returns whether the tabs of the notebook are shown.
See gtk_notebook_set_show_tabs().
%TRUE if the tabs are shown
Returns whether the tab contents can be detached from @notebook.
%TRUE if the tab is detachable.
a child #GtkWidget
Returns the horizontal width of a tab border.
horizontal width of a tab border
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
the page
Retrieves the text of the tab label for the page containing
tab label widget is not a #GtkLabel. The string is owned
by the widget and must not be freed.
the text of the tab label, or %NULL if the
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
Gets whether the tab can be reordered via drag and drop or not.
%TRUE if the tab is reorderable.
a child #GtkWidget
Returns the vertical width of a tab border.
vertical width of a tab border
Insert a page into @notebook at the given position.
page in the notebook, or -1 if function fails
the index (starting from 0) of the inserted
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.
page in the notebook
the index (starting from 0) of the inserted
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.
Finds the index of the page which contains the given child
widget.
-1 if @child is not in the notebook
the index of the page containing @child, or
a #GtkWidget
Disables the popup menu.
mouse button on the tab labels, a menu with all the pages
will be popped up.
Prepends a page to @notebook.
page in the notebook, or -1 if function fails
the index (starting from 0) of the prepended
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.
page in the notebook, or -1 if function fails
the index (starting from 0) of the prepended
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.
Removes a page from the notebook given its index
in the notebook.
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
children in the list or negative, @child will be moved to the end
of the list.
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 #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.
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.
the name of the notebook group, or %NULL to unset it
Changes the menu label for the page containing @child.
the child widget
the menu label, or %NULL for default
Creates a new label and sets it as the menu label of @child.
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.
%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().
%TRUE if a bevel should be drawn around the notebook
Sets whether to show the tabs for the notebook or not.
%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.
|[
static void
on_drop_zone_drag_data_received (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
GtkSelectionData *selection_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 (selection_data);
process_widget (*child);
gtk_container_remove (GTK_CONTAINER (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 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'.
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.
the page
the label text
Sets the edge at which the tabs for switching pages in the
notebook are drawn.
the edge to draw the tabs at
Sets whether the notebook tab can be reordered
via drag and drop or not.
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 ).
added to, or %NULL.
a #GtkNotebook that @page should be
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
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().
<example>
<title>Typical numerable icons</title>
<inlinegraphic fileref="numerableicon.png" format="PNG"/>
<inlinegraphic fileref="numerableicon2.png" format="PNG"/>
</example>
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
Returns the icon name used as the base background image,
or %NULL if there's none.
an icon name, or %NULL
Returns the value currently displayed by @self.
the currently displayed value
Returns the currently displayed label of the icon, or %NULL.
the currently displayed label
Returns the #GtkStyleContext used by the icon for theming,
or %NULL if there's none.
This object is internal to GTK+ and should not be unreffed.
Use g_object_ref() if you want to keep it around
a #GtkStyleContext, or %NULL.
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 #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.
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 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 short label, or %NULL
Updates the icon to fetch theme information from the
given #GtkStyleContext.
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.
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.
surface, or %NULL.
A #cairo_surface_t pointer to the offscreen
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.
Sets the orientation of the @orientable.
the orientable's new orientation.
The orientation of the orientable.
Represents the orientation of widgets which can be switched between horizontal
and vertical orientation on the fly, like #GtkToolbar.
Determines how widgets should be packed insided menubars
and menuitems contained in menubars.
#GtkHBox, and #GtkButtonBox).
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.
<para id="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 <emphasis>minimal</emphasis> size for the layout
margins.
</para>
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.
<example>
<title>A page setup dialog</title>
<programlisting>
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;
}
</programlisting>
</example>
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
Reads the page setup from the group @group_name in the key file
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
Gets the bottom margin in units of @unit.
the bottom margin
the unit for the return value
Gets the left margin in units of @unit.
the left margin
the unit for the return value
Gets the page orientation of the #GtkPageSetup.
the page orientation
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.
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.
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.
the unit for the return value
Gets the paper size of the #GtkPageSetup.
the paper size
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.
the unit for the return value
Gets the right margin in units of @unit.
the right margin
the unit for the return value
Gets the top margin in units of @unit.
the top margin
the unit for the return value
Reads the page setup from the file @file_name.
See gtk_page_setup_to_file().
%TRUE on success
the filename to read the page setup from
Reads the page setup from the group @group_name in the key file
%TRUE on success
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.
the new bottom margin in units of @unit
the units for @margin
Sets the left margin of the #GtkPageSetup.
the new left margin in units of @unit
the units for @margin
Sets the page orientation of the #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 #GtkPaperSize
Sets the paper size of the #GtkPageSetup and modifies
the margins according to the new paper size.
a #GtkPaperSize
Sets the right margin of the #GtkPageSetup.
the new right margin in units of @unit
the units for @margin
Sets the top margin of the #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
the file to save to
This function adds the page setup from @setup to @key_file.
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()
#GtkPaned is the base class for widgets with two panes, arranged either
horizontally (#GtkHPaned) or vertically (#GtkVPaned). 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
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
The application can set the position of the slider as if it were set
by the user, by calling gtk_paned_set_position().
<example>
<title>Creating a paned widget with minimum sizes.</title>
<programlisting>
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);
</programlisting>
</example>
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
<literal>gtk_paned_pack1 (paned, child, FALSE, TRUE)</literal>.
the child to add
Adds a child to the bottom or right pane with default parameters. This
is equivalent to
<literal>gtk_paned_pack2 (paned, child, TRUE, TRUE)</literal>.
the child to add
Obtains the first child of the paned widget.
first child, or %NULL if it is not set.
Obtains the second child of the paned widget.
second child, or %NULL if it is not set.
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.
Obtains the position of the divider between the two panes.
position of the divider
Adds a child to the top or left pane.
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.
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.
pixel position of divider, a negative value means that the position is unset.
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.
The ::accept-position signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<ulink url="http://www.pwg.org/standards.html">"PWG 5101.1-2002 PWG: Standard for Media Standardized Names"</ulink>
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 <link linkend="print-margins">print margins</link>.
Printing support has been added in GTK+ 2.10.
Creates a new #GtkPaperSize object by parsing a
<ulink url="ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf">PWG 5101.1-2002</ulink>
paper name.
If @name is %NULL, the default paper size is returned,
see gtk_paper_size_get_default().
to free it
a new #GtkPaperSize, use gtk_paper_size_free()
a paper size name, or %NULL
Creates a new #GtkPaperSize object with the
given parameters.
to free it
a new #GtkPaperSize object, use gtk_paper_size_free()
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
Reads a paper size from the group @group_name in the key file
paper size, or %NULL if an error occurred
a new #GtkPaperSize object with the restored
the #GKeyFile to retrieve the papersize from
the name ofthe 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,
construct a custom #GtkPaperSize object.
to free it
a new #GtkPaperSize, use gtk_paper_size_free()
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
Free the given #GtkPaperSize object.
Gets the default bottom margin for the #GtkPaperSize.
the default bottom margin
the unit for the return value
Gets the default left margin for the #GtkPaperSize.
the default left margin
the unit for the return value
Gets the default right margin for the #GtkPaperSize.
the default right margin
the unit for the return value
Gets the default top margin for the #GtkPaperSize.
the default top margin
the unit for the return value
Gets the human-readable name of the #GtkPaperSize.
the human-readable name of @size
Gets the paper height of the #GtkPaperSize, in
units of @unit.
the paper height
the unit for the return value
Gets the name of the #GtkPaperSize.
the name of @size
Gets the PPD name of the #GtkPaperSize, which
may be %NULL.
the PPD name of @size
Gets the paper width of the #GtkPaperSize, in
units of @unit.
the paper width
the unit for the return value
Returns %TRUE if @size is not a standard paper size.
whether @size is a custom paper size.
Compares two #GtkPaperSize objects.
represent the same paper size
%TRUE, if @size1 and @size2
another #GtkPaperSize object
Changes the dimensions of a @size to @width x @height.
the new width in units of @unit
the new height in units of @unit
the unit for @width and @height
This function adds the paper size from @size to @key_file.
the #GKeyFile to save the paper size to
the group to add the settings to in @key_file
Determines when a scroll bar will be visible.
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.
Creates a new #PangoContext that can be used with the
#GtkPrintContext.
a new Pango context for @context
Creates a new #PangoLayout that is suitable for use
with the #GtkPrintContext.
a new Pango layout for @context
Obtains the cairo context that is associated with the
#GtkPrintContext.
the cairo context of @context
Obtains the horizontal resolution of the #GtkPrintContext,
in dots per inch.
the horizontal resolution of @context
Obtains the vertical resolution of the #GtkPrintContext,
in dots per inch.
the vertical resolution of @context
Obtains the hardware printer margins of the #GtkPrintContext, in units.
%TRUE if the hard margins were retrieved
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
Obtains the #GtkPageSetup that determines the page
dimensions of the #GtkPrintContext.
the page setup of @context
Returns a #PangoFontMap that is suitable for use
with the #GtkPrintContext.
the font map of @context
Obtains the width of the #GtkPrintContext, in pixels.
the width of @context
Sets a new cairo context on a print context.
This function is intended to be used when implementing
an internal print preview, it is not needed for printing,
since GTK+ itself creates a suitable cairo context in that
case.
the cairo context
the horizontal resolution to use with @cr
the vertical resolution to use with @cr
Error codes that identify various errors that can occur while
using the GTK+ printing support.
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.
<example>
<title>The high-level printing API</title>
<programlisting>
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);
}
</programlisting>
</example>
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_print_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.
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.
Returns the default page setup, see
gtk_print_operation_set_default_page_setup().
the default page setup
Gets the value of #GtkPrintOperation::embed-page-setup property.
whether page setup selection combos are embedded
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.
Gets the value of #GtkPrintOperation::has-selection property.
whether there is a selection
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
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.
Returns the status of the print operation.
Also see gtk_print_operation_get_status_string().
the status of the print operation
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.
of the print operation
a string representation of the status
Gets the value of #GtkPrintOperation::support-selection property.
whether the application supports print of selection
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).
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.
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).
|[
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.
%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.
the result of the print operation. A return value of
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.
%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.
the current page, 0-based
Sets the label for the tab holding custom widgets.
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 #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.
Embed page size combo box and orientation combo box into page setup page.
Selected page setup is stored as default page setup in #GtkPrintOperation.
%TRUE to embed page setup selection in the #GtkPrintDialog
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.
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.
%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 string that identifies the print job
Sets the number of pages in the document.
This <emphasis>must</emphasis> 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
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().
#GtkPrintSettings
If @show_progress is %TRUE, the print operation will show a
progress dialog during the print operation.
%TRUE to show a progress dialog
Sets whether selection is supported by #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.
%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.
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).
%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 <emphasis>must</emphasis> 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.
the print dialog, or %NULL
A custom widget that gets embedded in
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.
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().
|[
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 #GtkPrintPreviewOperation 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.
Ends a preview.
This function must be called to finish a custom print preview.
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 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.
the page to render
Ends a preview.
This function must be called to finish a custom print preview.
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 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.
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
the page to render
%TRUE if the page has been selected for printing
a page number
A value of this type is returned by gtk_print_operation_run().
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
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
Calls @func for each key-value pair of @settings.
the function to call
user data for @func
Looks up the string value associated with @key.
the string value for @key
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 key
Gets the value of %GTK_PRINT_SETTINGS_COLLATE.
whether to collate the printed pages
Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE.
the default source
Gets the value of %GTK_PRINT_SETTINGS_DITHER.
the dithering that is used
Returns the double value associated with @key, or 0.
the double value of @key
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 key
the default value
Gets the value of %GTK_PRINT_SETTINGS_DUPLEX.
whether to print the output in duplex.
Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS.
the finishings
Returns the integer value of @key, or 0.
the integer value of @key
a key
Returns the value of @key, interpreted as
an integer, or the default value.
the integer value of @key
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 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.
<!-- FIXME link here -->
the media type
Gets the value of %GTK_PRINT_SETTINGS_N_COPIES.
the number of copies to print
Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP.
the number of pages per sheet
Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT.
layout of page in number-up mode
Get the value of %GTK_PRINT_SETTINGS_ORIENTATION,
converted to a #GtkPageOrientation.
the orientation
Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN.
the output bin
Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
of #GtkPageRange<!-- -->s. Use g_free() to free the array when
it is no longer needed.
an array
return location for the length of the returned array
Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET.
the set of pages to print
Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT,
converted to @unit.
the paper height, in units of @unit
the unit for the return value
Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT,
converted to a #GtkPaperSize.
the paper size
Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH,
converted to @unit.
the paper width, in units of @unit
the unit for the return value
Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES.
which pages to print
Convenience function to obtain the value of
%GTK_PRINT_SETTINGS_PRINTER.
the printer name
Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI.
the resolution in lpi (lines per inch)
Gets the value of %GTK_PRINT_SETTINGS_QUALITY.
the print quality
Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION.
the resolution in dpi
Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X.
the horizontal resolution in dpi
Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y.
the vertical resolution in dpi
Gets the value of %GTK_PRINT_SETTINGS_REVERSE.
whether to reverse the order of the printed pages
Gets the value of %GTK_PRINT_SETTINGS_SCALE.
the scale in percent
Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR.
whether to use color
Returns %TRUE, if a value is associated with @key.
%TRUE, if @key has a value
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
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
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 key
a string value, or %NULL
Sets @key to a boolean value.
a key
a boolean
Sets the value of %GTK_PRINT_SETTINGS_COLLATE.
whether to collate the output
Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE.
the default source
Sets the value of %GTK_PRINT_SETTINGS_DITHER.
the dithering that is used
Sets @key to a double value.
a key
a double value
Sets the value of %GTK_PRINT_SETTINGS_DUPLEX.
a #GtkPrintDuplex value
Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS.
the finishings
Sets @key to an integer value.
a key
an integer
Associates a length in units of @unit with @key.
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.
<!-- FIXME link here -->
the media type
Sets the value of %GTK_PRINT_SETTINGS_N_COPIES.
the number of copies
Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP.
the number of pages per sheet
Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT.
a #GtkNumberUpLayout value
Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION.
a page orientation
Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN.
the output bin
Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
an array of #GtkPageRange<!-- -->s
the length of @page_ranges
Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET.
a #GtkPageSet value
Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT.
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 paper size
Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH.
the paper width
the units of @width
Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES.
a #GtkPrintPages value
Convenience function to set %GTK_PRINT_SETTINGS_PRINTER
to @printer.
the printer name
Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI.
the resolution in lpi (lines per inch)
Sets the value of %GTK_PRINT_SETTINGS_QUALITY.
a #GtkPrintQuality value
Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION,
%GTK_PRINT_SETTINGS_RESOLUTION_X and
%GTK_PRINT_SETTINGS_RESOLUTION_Y.
the resolution in dpi
Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION,
%GTK_PRINT_SETTINGS_RESOLUTION_X and
%GTK_PRINT_SETTINGS_RESOLUTION_Y.
the horizontal resolution in dpi
the vertical resolution in dpi
Sets the value of %GTK_PRINT_SETTINGS_REVERSE.
whether to reverse the output
Sets the value of %GTK_PRINT_SETTINGS_SCALE.
the scale in percent
Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR.
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
the file to save to
This function adds the print settings from @settings to @key_file.
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 key
The status gives a rough indication of the completion of a running
print operation.
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
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.
Creates a new #GtkProgressBar.
a #GtkProgressBar.
Returns the ellipsizing position of the progressbar.
See gtk_progress_bar_set_ellipsize().
#PangoEllipsizeMode
Returns the current fraction of the task that's been completed.
a fraction from 0.0 to 1.0
Gets the value set by gtk_progress_bar_set_inverted()
%TRUE if the progress bar is inverted
Retrieves the pulse step set with gtk_progress_bar_set_pulse_step()
a fraction from 0.0 to 1.0
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
Retrieves the text displayed superimposed on 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.
and should not be modified or freed.
text, or %NULL; this string is owned by the widget
Indicates that some progress is 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()).
if there is not enough space to render the entire string.
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.
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.
%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().
fraction between 0.0 and 1.0
Sets whether the progressbar will show text superimposed
over 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.
whether to show superimposed text
Causes the given @text to appear superimposed on the progress bar.
a UTF-8 string, or %NULL
The preferred place to ellipsize the string, if the progressbar does
not have enough room to display the entire string, specified as a
#PangoEllisizeMode.
Note that setting this property to a value other than
%PANGO_ELLIPSIZE_NONE has the side-effect that the progressbar requests
only enough space to display the ellipsis "...". Another means to set a
progressbar's width is gtk_widget_set_size_request().
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
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:
|[
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
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:
|[
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;
}
]|
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.
the new value
Sets the radio group for the radio action object.
a list representing a radio group
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.
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.
<example>
<title>How to create a group of two radio buttons.</title>
<programlisting>
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, TRUE, 2);
/* 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, TRUE, TRUE, 2);
gtk_box_pack_start (GTK_BOX (box), radio2, TRUE, TRUE, 2);
gtk_container_add (GTK_CONTAINER (window), box);
gtk_widget_show_all (window);
return;
}
</programlisting>
</example>
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 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
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.
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 linked list
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:
|[
GtkRadioButton *radio_button;
GtkRadioButton *last_button;
while (/* more buttons to add */)
{
radio_button = gtk_radio_button_new (...);
gtk_radio_button_join_group (radio_button, last_button);
last_button = radio_button;
}
]|
a radio button object whos group we are joining, or %NULL to remove the radio button from its group
Creates a new #GtkRadioButton, adding it to the same group as
should be packed into the radio button.
a new radio button.
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.
an existing radio button group, such as one returned from gtk_radio_button_get_group().
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.
Creates a new #GtkRadioMenuItem whose child is a simple #GtkLabel.
A new #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
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.
of @radio_menu_item
the group
Creates a new #GtkRadioMenuItem adding it to the same group as @group.
The new #GtkRadioMenuItem
Creates a new GtkRadioMenuItem whose child is a simple GtkLabel.
The new #GtkRadioMenuItem is added to the same group as @group.
The new #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.
The new #GtkRadioMenuItem is added to the same group as @group.
The new #GtkRadioMenuItem
the text of the button, with an underscore in front of the mnemonic character
The radio menu item whose group this widget belongs to.
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.
The new #GtkRadioToolItem
an existing radio button group, or %NULL if you are creating a new group
the name of a stock item
Returns the radio button group @button belongs to.
The group @button belongs to.
Creates a new #GtkRadioToolButton adding it to the same group as @gruup
The new #GtkRadioToolButton
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.
A new #GtkRadioToolButton
the name of a stock item
Adds @button to @group, removing it from the group it belonged to before.
an existing radio button group
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
Returns the range's event window if it is realized, %NULL otherwise.
This function should be rarely needed.
@range's event window.
Gets the current position of the fill level indicator.
The current fill level
Gets the value set by gtk_range_set_flippable().
%TRUE if the range is flippable
Gets the value set by gtk_range_set_inverted().
%TRUE if the range is inverted
Gets the sensitivity policy for the stepper that points to the
'lower' end of the GtkRange's adjustment.
The lower stepper's sensitivity policy.
This function is useful mainly for #GtkRange subclasses.
See gtk_range_set_min_slider_size().
The minimum size of the range's slider.
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.
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.
Gets the number of digits to round the value to when
it changes. See #GtkRange::change-value.
the number of digits to round to
Gets whether the range displays the fill level graphically.
%TRUE if @range shows the fill level.
This function returns sliders range along the long dimension,
in widget->window coordinates.
This function is useful mainly for #GtkRange subclasses.
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.
Gets the sensitivity policy for the stepper that points to the
'upper' end of the GtkRange's adjustment.
The upper stepper's sensitivity policy.
Gets the current value of the range.
current value of the range.
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 #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.
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().
%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.
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.
%TRUE to invert the range
Sets the sensitivity policy for the stepper that points to the
'lower' end of the GtkRange's adjustment.
the lower stepper's sensitivity policy.
Sets the minimum size of the range's slider.
This function is useful mainly for #GtkRange subclasses.
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.)
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.
Whether the fill level restricts slider movement.
Sets the number of digits to round the value to when
it changes. See #GtkRange::change-value.
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.
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.
%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.
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.
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.
It is not possible to use delayed update policies in an overridden
#GtkRange::change-value handler.
%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.
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.
the resulting #GtkRcStyle
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.
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.
%TRUE if the shown items should be numbered
#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 #GtkRecentFilter
Gets the URI currently selected by @chooser.
a newly allocated string holding a URI.
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.
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 newly allocated
Gets the #GtkRecentFilter objects held by @chooser.
of #GtkRecentFilter objects. You
should just free the returned list using g_slist_free().
A singly linked list
Removes @filter from the list of #GtkRecentFilter objects held by @chooser.
a #GtkRecentFilter
Selects all the items inside @chooser, if the @chooser supports
multiple selection.
Selects @uri inside @chooser.
%TRUE if @uri was found.
a URI
Sets @uri as the current URI for @chooser.
%TRUE if the URI was found.
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
item comes before the second, zero if the two items are equal and
a negative integer if the first item comes after the second.
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.
Unselects @uri inside @chooser.
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 #GtkRecentFilter
Gets the #GtkRecentInfo currently selected by @chooser.
when you have finished using it.
a #GtkRecentInfo. Use gtk_recent_info_unref() when
Gets the URI currently selected by @chooser.
a newly allocated string holding a URI.
Gets the #GtkRecentFilter object currently used by @chooser to affect
the display of the recently used resources.
a #GtkRecentFilter object.
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.
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 newly allocated
Gets the number of items returned by gtk_recent_chooser_get_items()
and gtk_recent_chooser_get_uris().
returned.
A positive integer, or -1 meaning that all items are
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.
Gets whether @chooser can select multiple items.
%TRUE if @chooser can select more than one item.
Retrieves whether @chooser should show an icon near the resource.
%TRUE if the icons should be displayed, %FALSE otherwise.
Retrieves whether @chooser should show the recently used resources that
were not found.
%FALSE otheriwse.
%TRUE if the resources not found should be displayed, and
Returns whether @chooser should display recently used resources
registered as private.
%FALSE otherwise.
%TRUE if the recent chooser should show private items,
Gets whether @chooser should display tooltips containing the full path
of a recently user resource.
%FALSE otherwise.
%TRUE if the recent chooser should show tooltips,
Gets the value set by gtk_recent_chooser_set_sort_type().
the sorting order of the @chooser.
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.
return location for a the length of the URI list, or %NULL
Gets the #GtkRecentFilter objects held by @chooser.
of #GtkRecentFilter objects. You
should just free the returned list using g_slist_free().
A singly linked list
Removes @filter from the list of #GtkRecentFilter objects held by @chooser.
a #GtkRecentFilter
Selects all the items inside @chooser, if the @chooser supports
multiple selection.
Selects @uri inside @chooser.
%TRUE if @uri was found.
a URI
Sets @uri as the current URI for @chooser.
%TRUE if the URI was found.
a URI
Sets @filter as the current #GtkRecentFilter object used by @chooser
to affect the displayed recently used resources.
a #GtkRecentFilter
Sets the number of items that should be returned by
gtk_recent_chooser_get_items() and gtk_recent_chooser_get_uris().
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
to be accessible through the operating system native file system.
%TRUE if only local files can be shown
Sets whether @chooser can select multiple items.
%TRUE if @chooser can select more than one item
Sets whether @chooser should show an icon near the resource when
displaying it.
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.
whether to show the local items we didn't find
Whether to show recently used resources marked registered as private.
%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.
%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
item comes before the second, zero if the two items are equal and
a negative integer if the first item comes after the second.
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
sort order that the chooser should use
Unselects all the items inside @chooser.
Unselects @uri inside @chooser.
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. By default, the
override that limit on a particular instance of #GtkRecentChooser
by setting this property.
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
<keycap>Enter</keycap>.
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
explicitely 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.
<example id="gtkrecentchooser-typical-usage">
<title>Typical usage</title>
In the simplest of cases, you can use the following code to use
a #GtkRecentChooserDialog to select a recently used file:
<programlisting>
GtkWidget *dialog;
dialog = gtk_recent_chooser_dialog_new ("Recent Documents",
parent_window,
GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
NULL);
if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
{
GtkRecentInfo *info;
info = gtk_recent_chooser_get_current_item (GTK_RECENT_CHOOSER (dialog));
open_file (gtk_recent_info_get_uri (info));
gtk_recent_info_unref (info);
}
gtk_widget_destroy (dialog);
</programlisting>
</example>
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
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
These identify the various errors that can occur while calling
#GtkRecentChooser functions.
%TRUE if the URI was found.
a URI
a newly allocated string holding a URI.
%TRUE if @uri was found.
a URI
a URI
A newly allocated
a #GtkRecentFilter
a #GtkRecentFilter
A singly linked list
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.
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.
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 #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.
<refsect2 id="GtkRecentFilter-BUILDER-UI">
<title>GtkRecentFilter as GtkBuildable</title>
<para>
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> is the same
as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern()
or gtk_recent_filter_add_application().
<example>
<title>A UI definition fragment specifying GtkRecentFilter rules</title>
<programlisting><![CDATA[
<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>
]]></programlisting>
</example>
</para>
</refsect2>
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:
|[
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.
number of days
Adds a rule that allows resources based on the name of the application
that has registered them.
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.
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 group name
Adds a rule that allows resources based on their registered MIME type.
a MIME type
Adds a rule that allows resources based on a pattern matching their
display name.
a file pattern
Adds a rule allowing image files in the formats supported
by GdkPixbuf.
Tests whether a file should be displayed according to @filter.
The #GtkRecentFilterInfo structure @filter_info should include
the fields returned from gtk_recent_filter_get_needed().
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 #GtkRecentFilterInfo structure containing information about a recently used resource
Gets the human-readable name for the filter.
See gtk_recent_filter_set_name().
is owned by the filter object and should not be freed.
the name of the filter, or %NULL. The returned string
Gets the fields that need to be filled in for the structure
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.
calling gtk_recent_filter_filter()
bitfield of flags indicating needed fields when
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.
then human readable name of @filter
These flags indicate what parts of a #GtkRecentFilterInfo struct
are filled or need to be filled.
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().
#GtkRecentInfo is an opaque data structure
whose members can only 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
In case of error, @error will be set either with a
%GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR
the newly created #GAppInfo, or %NULL.
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
Gets the timestamp (seconds from system's Epoch) when the resource
was added to the recently used resources list.
the resource was added to the list, or -1 on failure.
the number of seconds elapsed from system's Epoch when
Gets the number of days elapsed since the last update of the resource
pointed by @info.
since the time this resource was last modified.
a positive integer containing the number of days elapsed
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.
resource inside the recently used list, or %FALSE otherwise. The
modified or freed
%TRUE if an application with @app_name has registered this
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.
return location for the length of the returned list
Gets the (short) description of the resource.
is owned by the recent manager, and should not be freed.
the description of the resource. The returned string
Gets the name of the resource. If none has been defined, the basename
of the resource is obtained.
is owned by the recent manager, and should not be freed.
the display name of the resource. The returned string
Retrieves the icon associated to the resource MIME type.
g_object_unref() when finished using the icon
a #GIcon containing the icon, or %NULL. Use
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.
return location for the number of groups returned
Retrieves the icon of size @size associated to the resource MIME type.
or %NULL. Use g_object_unref() when finished using the icon.
a #GdkPixbuf containing the icon,
the size of the icon in pixels
Gets the MIME type of the resource.
is owned by the recent manager, and should not be freed.
the MIME type of the resource. The returned string
Gets the timestamp (seconds from system's Epoch) when the resource
was last modified.
the resource was last modified, or -1 on failure.
the number of seconds elapsed from system's Epoch when
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.
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".
g_free().
A newly-allocated string in UTF-8 encoding; free it with
Gets the URI of the resource.
owned by the recent manager, and should not be freed.
the URI of the resource. The returned string is
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().
resource's URI or %NULL. Use g_free() when done using it.
a newly allocated UTF-8 string containing the
Gets the timestamp (seconds from system's Epoch) when the resource
was last visited.
the resource was last visited, or -1 on failure.
the number of seconds elapsed from system's Epoch when
Checks whether an application registered this resource using @app_name.
%FALSE otherwise.
%TRUE if an application with name @app_name was found,
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.
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.
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.
Checks whether two #GtkRecentInfo structures point to the same
resource.
resource, %FALSE otherwise.
%TRUE if both #GtkRecentInfo structures point to se same
a #GtkRecentInfo
Increases the reference count of @recent_info by one.
by one.
the recent info object with its reference count increased
Decreases the reference count of @info by one. If the reference
count reaches zero, @info is deallocated, and the memory freed.
#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.
<note><para>The recently used files list is per user.</para></note>
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:
|[
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():
|[
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_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
structures.
A #GtkRecentManager is the model used to populate the contents of
one, or more #GtkRecentChooser implementations.
<note><para>The maximum age of the recently used files list is
controllable through the #GtkSettings:gtk-recent-files-max-age
property.</para></note>
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
structure 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 structure, 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 structure 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.
recently used resources list, %FALSE otherwise.
%TRUE if the new item was successfully added to the
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.
to the recently used resources list
%TRUE if the new item was successfully added
a valid URI
Gets the list of recently used resources.
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 list of
Checks whether there is a recently used resource registered
with @uri inside the recent manager.
%TRUE if the resource was found, %FALSE otherwise.
a URI
Searches for a URI inside the recently used resources list, and
returns a structure containing informations about the resource
like its MIME type, or its display name.
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 #GtkRecentInfo structure containing information
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.
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.
recently used resources list.
the number of items that have been removed from the
Removes a resource pointed by @uri from the recently used resources
list handled by a recent manager.
removed by the recently used resources list, and %FALSE otherwise.
%TRUE if the item pointed by @uri has been successfully
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
Used to specify the sorting method to be applyed to the recently
used resource list.
Describes a region within a widget.
Indicated the relief to be drawn around a #GtkButton.
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 <structname>GtkRequisition</structname> represents the desired size of a widget. See
<xref linkend="geometry-management"/> for more information.
Allocates a new #GtkRequisition structure and initializes its elements to zero.
be freed with gtk_requisition_free().
a new empty #GtkRequisition. The newly allocated #GtkRequisition should
Copies a #GtkRequisition.
a copy of @requisition
Frees a #GtkRequisition.
Predefined values for use as response ids in gtk_dialog_add_button().
All predefined values are negative, GTK+ leaves positive values for
application-defined response ids.
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).
<refsect2 id="GtkScale-BUILDER-UI"><title>GtkScale as GtkBuildable</title>
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.
</refsect2>
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.
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().
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 <link linkend="PangoMarkupFormat">Pango markup</link>, or %NULL
Removes any marks that have been added with gtk_scale_add_mark().
Gets the number of decimal places that are displayed in the value.
the number of decimal places that are displayed
Returns whether the current value is displayed as a string
next to the slider.
whether the current value is displayed as a string
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.
or %NULL if the #GtkScale:draw-value property is %FALSE.
the #PangoLayout for this scale,
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.
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
Sets the number of decimal places that are displayed in the value.
Also causes the value of the adjustment to be rounded off to this
number of digits, so the retrieved value matches the value the user saw.
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.
%TRUE to draw the value
Sets the position in which the current value is displayed.
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
Here's an example signal handler which displays a value 1.0 as
with "-->1.0<--".
|[
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.
Creates a #GtkScaleButton, with a range between @min and @max, with
a stepping of @step.
a new #GtkScaleButton
a stock icon size
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
Retrieves the minus button of the #GtkScaleButton.
the minus button of the #GtkScaleButton
Retrieves the plus button of the #GtkScaleButton.
the plus button of the #GtkScaleButton
Retrieves the popup of the #GtkScaleButton.
the popup of the #GtkScaleButton
Gets the current value of the scale button.
current value of the scale button
Sets the #GtkAdjustment to be used as a model
for the #GtkScaleButton's scale.
See gtk_range_set_adjustment() for details.
a #GtkAdjustment
Sets the icons to be used by the scale button.
For details, see the #GtkScaleButton:icons property.
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.
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
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted to popdown the scale widget.
The default binding for this signal is Escape.
The ::popup signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
location to store X offset of layout, or %NULL
location to store Y offset of layout, or %NULL
#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.
<refsect2>
<title>Creating a scrollable widget</title>
<para>
All scrollable widgets should do the following.
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
When the parent allocates space to the scrollable child widget, the widget should update
the adjustments' properties with new values.
</para>
</listitem>
<listitem>
<para>
When any of the adjustments emits the #GtkAdjustment::value-changed signal,
the scrollable widget should scroll its contents.
</para>
</listitem>
</orderedlist>
</para>
</refsect2>
Retrieves the #GtkAdjustment used for horizontal scrolling.
horizontal #GtkAdjustment.
Gets the horizontal #GtkScrollablePolicy.
The horizontal #GtkScrollablePolicy.
Retrieves the #GtkAdjustment used for vertical scrolling.
vertical #GtkAdjustment.
Gets the vertical #GtkScrollablePolicy.
The vertical #GtkScrollablePolicy.
Sets the horizontal adjustment of the #GtkScrollable.
a #GtkAdjustment
Sets the #GtkScrollablePolicy to determine whether
horizontal scrolling should start below the minimum width or
below the natural width.
the horizontal #GtkScrollablePolicy
Sets the vertical adjustment of the #GtkScrollable.
a #GtkAdjustment
Sets the #GtkScrollablePolicy to determine whether
vertical scrolling should start below the minimum height or
below the natural height.
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.
Defines the policy to be used in a scrollable widget when updating
the scrolled window adjustments in a given orientation.
The #GtkScrollbar widget is the base class for #GtkHScrollbar and
#GtkVScrollbar. It can be used in the same way as these, by setting
the "orientation" property appropriately.
The position of the thumb in a scrollbar is controlled by the scroll
adjustments. See #GtkAdjustment for the fields in an adjustment - for
#GtkScrollbar, the #GtkAdjustment.value field represents the position
of the scrollbar, which must be between the #GtkAdjustment.lower field
and #GtkAdjustment.upper - #GtkAdjustment.page_size. The
#GtkAdjustment.page_size field represents the size of the visible
scrollable area. The #GtkAdjustment.step_increment and
#GtkAdjustment.page_increment fields are used when the user asks to
step down (using the small stepper arrows) or page down (using for
example the <keycap>PageDown</keycap> key).
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 #GtkBin subclass: it's a container
the accepts a single child widget. #GtkScrolledWindow adds scrollbars
to the child widget and optionally draws a beveled frame around the
child widget.
The scrolled window can work in two ways. Some widgets have native
scrolling support; these widgets implement the #GtkScrollable interface.
Widgets with native scroll support include #GtkTreeView, #GtkTextView,
and #GtkLayout.
For widgets that lack native scrolling support, 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 #GtkTable, #GtkBox, and so on.
If a widget has native scrolling abilities, it can be added to the
#GtkScrolledWindow with gtk_container_add(). If a widget does not, you
must first add the widget to a #GtkViewport, then add the #GtkViewport
to the scrolled window. The convenience function
gtk_scrolled_window_add_with_viewport() does exactly this, so you can
ignore the presence of the viewport.
The position of the scrollbars is controlled by the scroll
adjustments. See #GtkAdjustment for the fields in an adjustment - for
#GtkScrollbar, used by #GtkScrolledWindow, the "value" field
represents the position of the scrollbar, which must be between the
"lower" field and "upper - page_size." The "page_size" field
represents the size of the visible scrollable area. The
"step_increment" and "page_increment" fields are used when the user
asks to step down (using the small stepper arrows) or page down (using
for example the PageDown key).
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 #GtkTable.
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.
the widget you want to scroll
Returns the horizontal scrollbar's adjustment, used to connect the
horizontal scrollbar to the child widget's horizontal scroll
functionality.
the horizontal #GtkAdjustment
Returns the horizontal scrollbar of @scrolled_window.
or %NULL if it does not have one.
the horizontal scrollbar of the scrolled window,
Gets the minimal content height of @scrolled_window, or -1 if not set.
the minimal content height
Gets the minimum content width of @scrolled_window, or -1 if not set.
the minimum content width
Gets the placement of the contents with respect to the scrollbars
for the scrolled window. See gtk_scrolled_window_set_placement().
See also gtk_scrolled_window_set_placement() and
gtk_scrolled_window_unset_placement().
the current placement value.
Retrieves the current policy values for the horizontal and vertical
scrollbars. See gtk_scrolled_window_set_policy().
location to store the policy for the horizontal scrollbar, or %NULL.
location to store the policy for the vertical scrollbar, or %NULL.
Gets the shadow type of the scrolled window. See
gtk_scrolled_window_set_shadow_type().
the current shadow type
Returns the vertical scrollbar's adjustment, used to connect the
vertical scrollbar to the child widget's vertical scroll functionality.
the vertical #GtkAdjustment
Returns the vertical scrollbar of @scrolled_window.
or %NULL if it does not have one.
the vertical scrollbar of the scrolled window,
Sets the #GtkAdjustment for the horizontal scrollbar.
horizontal scroll adjustment
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.
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.
the minimal content width
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().
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).
policy for horizontal bar
policy for vertical bar
Changes the type of shadow drawn around the contents of
kind of shadow to draw around scrolled window contents
Sets the #GtkAdjustment for the vertical scrollbar.
vertical scroll adjustment
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 obeys the "gtk-scrolled-window-placement" XSETTING.
See also gtk_scrolled_window_set_placement() and
gtk_scrolled_window_get_placement().
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 "window-placement" should be used to determine the location
of the contents with respect to the scrollbars. Otherwise, the
"gtk-scrolled-window-placement" setting is used.
The ::move-focus-out signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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 windows toplevel parent in the container hierarchy.
The default bindings for this signal are
<keycombo><keycap>Tab</keycap><keycap>Ctrl</keycap></keycombo>
and
<keycombo><keycap>Tab</keycap><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>.
either %GTK_DIR_TAB_FORWARD or %GTK_DIR_TAB_BACKWARD
The ::scroll-child signal is a
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted when a keybinding that scrolls is pressed.
The horizontal or vertical adjustment is updated which triggers a
signal that the scrolled windows child may listen to and scroll itself.
a #GtkScrollType describing how much to scroll
whether the keybinding scrolls the child horizontally or not
Makes a copy of a #GtkSelectionData structure and its data.
a pointer to a copy of @data.
Frees a #GtkSelectionData structure returned from
gtk_selection_data_copy().
Retrieves the raw data of the selection.
the raw data of the selection.
Retrieves the data type of the selection.
the data type of the selection.
Retrieves the raw data of the selection along with its length.
the raw data of the selection
return location for length of the data segment
Retrieves the display of the selection.
the display of the selection.
Retrieves the format of the selection.
the format of the selection.
Retrieves the length of the raw data of the selection.
the length of the data of the selection.
Gets the contents of the selection data as a #GdkPixbuf.
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().
if the selection data contained a recognized
Retrieves the selection #GdkAtom of the selection data.
the selection #GdkAtom of the selection data.
Retrieves the target of the selection.
the target of the selection.
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.
array of targets, otherwise %FALSE.
%TRUE if @selection_data contains a valid
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.
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().
if the selection data contained a
Gets the contents of the selection data as array of URIs.
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().
if
Stores new data into a #GtkSelectionData object. Should
<emphasis>only</emphasis> be called from a selection handler callback.
Zero-terminates the stored data.
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
otherwise %FALSE.
%TRUE if the selection was successfully set,
a #GdkPixbuf
Sets the contents of the selection from a UTF-8 encoded string.
The string is converted to the form determined by
otherwise %FALSE.
%TRUE if the selection was successfully set,
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
otherwise %FALSE.
%TRUE if the selection was successfully set,
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.
and a suitable target for images is included, otherwise %FALSE.
%TRUE if @selection_data holds a list of targets,
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.
and a suitable target for rich text is included,
otherwise %FALSE.
%TRUE if @selection_data holds a list of targets,
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.
and a suitable target for text is included, otherwise %FALSE.
%TRUE if @selection_data holds a list of targets,
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.
and a suitable target for URI lists is included, otherwise %FALSE.
%TRUE if @selection_data holds a list of targets,
Used to control what selections users are allowed to make.
Determines how GTK+ handles the sensitivity of stepper arrows
at the end of range widgets.
The GtkSeparator widget is the base class for #GtkHSeparator and
#GtkVSeparator. It can be used in the same way as these, by setting
the "orientation" property suitably.
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.
Creates a new #GtkSeparatorMenuItem.
a new #GtkSeparatorMenuItem.
A #GtkSeparatorItem 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.
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.
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.
whether @item is drawn as a vertical line
GtkSettings provide a mechanism to share global settings between
applications.
On the X window system, this sharing is realized by an
<ulink url="http://www.freedesktop.org/wiki/Specifications/xsettings-spec">XSettings</ulink>
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
<filename>settings.ini</filename> files in
<filename>/etc/gtk-3.0</filename> and <filename>$XDG_CONFIG_HOME/gtk-3.0</filename>. 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 <filename>settings.ini</filename> file
next to their <filename>gtk.css</filename> file.
Applications can override system-wide settings with
gtk_settings_set_string_property(), gtk_settings_set_long_property(),
etc. 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:
<informalexample><programlisting>
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-menu-images", FALSE, NULL);
</programlisting></informalexample>
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().
screen, then returns %NULL.
a #GtkSettings object. If there is no default
Gets the #GtkSettings object for @screen, creating it if necessary.
a #GtkSettings object.
a #GdkScreen.
Holds a hash table representation of the #GtkSettings:gtk-color-scheme
setting, mapping color names to #GdkColor<!-- -->s.
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.
A palette of named colors for use in themes. The format of the string is
<programlisting>
...
</programlisting>
Color names must be acceptable as identifiers in the
<link linkend="gtk-Resource-Files">gtkrc</link> 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:
<programlisting>
</programlisting>
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.
Whether menu items should have visible accelerators which can be
activated.
Whether to play any event sounds at all.
See the <ulink url="http://www.freedesktop.org/wiki/Specifications/sound-theme-spec">Sound Theme spec</ulink>
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 <ulink url="http://www.freedesktop.org/wiki/Specifications/sound-theme-spec">Sound Theme spec</ulink>
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.
Whether tooltips should be shown on widgets.
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.
A list of icon sizes. The list is separated by colons, and
item has the form:
<replaceable>size-name</replaceable> = <replaceable>width</replaceable> , <replaceable>height</replaceable>
E.g. "gtk-menu=16,16:gtk-button=20,20:gtk-dialog=48,48".
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().
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.
See #GtkIMContext and see the #GtkSettings:gtk-show-input-method-menu property.
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.
When %TRUE, some widgets will wrap around when doing keyboard
navigation, such as menus, menubars and notebooks.
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.
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.
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.
The XDG sound theme to use for event sounds.
See the <ulink url="http://www.freedesktop.org/wiki/Specifications/sound-theme-spec">Sound Theme spec</ulink>
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.
The size of icons in default toolbars.
The size of icons in default toolbars.
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.
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.
Time, in milliseconds, after which a tooltip could appear if the
cursor is hovering on top of a widget.
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.
Used to change the appearance of an outline typically provided by a #GtkFrame.
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.
the #GtkWidget to add
Returns if invisible widgets are ignored when calculating the size.
%TRUE if invisible widgets are ignored.
Gets the current mode of the size group. See gtk_size_group_set_mode().
the current mode of the size group.
Returns the list of widgets associated with @size_group.
widgets. The list is owned by GTK+ and should not be modified.
a #GSList of
Removes a widget from a #GtkSizeGroup.
the #GtkWidget to remove
Sets whether unmapped widgets should be ignored when
calculating the size.
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).
the mode to set for the size group.
If %TRUE, unmapped widgets are ignored when determining
the size of the group.
The mode of the size group determines the directions in which the size
group affects the requested sizes of its component widgets.
Specifies a preference for height-for-width or
width-for-height geometry management.
Determines the direction of a sort.
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.
<example>
<title>Using a GtkSpinButton to get an integer</title>
<programlisting>
/* 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);
}
</programlisting>
</example>
<example>
<title>Using a GtkSpinButton to get a floating point value</title>
<programlisting>
/* 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);
}
</programlisting>
</example>
Creates a new #GtkSpinButton.
The new spin button as a #GtkWidget
the #GtkAdjustment object that this spin button should use, or %NULL
specifies how much the spin button changes when an arrow is clicked on
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 all changed accordingly,
after this function call.
a #GtkAdjustment
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
Fetches the precision of @spin_button. See gtk_spin_button_set_digits().
the current precision
Gets the current step and page the increments used by @spin_button. See
gtk_spin_button_set_increments().
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
Gets the range allowed for @spin_button.
See gtk_spin_button_set_range().
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
Gets the update behavior of a spin button.
See gtk_spin_button_set_update_policy().
the current update policy
Get the value in the @spin_button.
the value of @spin_button
Get the value @spin_button represented as an integer.
the value of @spin_button
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
Replaces the #GtkAdjustment associated with @spin_button.
a #GtkAdjustment to replace the existing adjustment
Set the precision to be displayed by @spin_button. Up to 20 digit precision
is allowed.
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.
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.
flag indicating if only numeric entry is allowed
Sets the minimum and maximum allowable values for @spin_button.
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 flag indicating if invalid values should be corrected
Sets the update behavior of a spin button.
This determines wether the spin button is always updated
or only when a valid value is set.
a #GtkSpinButtonUpdatePolicy value
Sets the value of @spin_button.
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 flag indicating if wrapping behavior is performed
Increment or decrement a spin button's value in a specified
direction by a specified amount.
a #GtkSpinType indicating the direction to spin
step increment to apply in the specified direction
Manually force an update of the spin button.
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().
was not handled, and %GTK_INPUT_ERROR if the conversion failed.
%TRUE for a successful conversion, %FALSE if the input
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.
|[
/* 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 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().
The values of the GtkSpinType enumeration are used to specify the
change to make in gtk_spin_button_spin().
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().
Returns a new spinner widget. Not yet started.
a new #GtkSpinner
Starts the animation of the spinner.
Stops the animation of the spinner.
Describes a widget state.
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.
Creates an empty status icon object.
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.
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.
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.
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.
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().
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.
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().
been filled in
%TRUE if the location information has
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;
the displayed icon, or %NULL if the image is empty
Returns the current value of the has-tooltip property.
See #GtkStatusIcon:has-tooltip for more information.
current value of has-tooltip on @status_icon.
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.
name of the displayed icon, or %NULL if the image is empty.
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.
or %NULL if the image is empty.
the displayed pixbuf,
Returns the #GdkScreen associated with @status_icon.
a #GdkScreen.
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()).
the size that is available for the image
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.
or %NULL if the image is empty.
stock id of the displayed stock icon,
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.
the image representation being used
Gets the title of this tray icon. See gtk_status_icon_set_title().
the title of the status icon
Gets the contents of the tooltip for @status_icon.
returned string with g_free() when done.
the tooltip text, or %NULL. You should free the
Gets the contents of the tooltip for @status_icon.
returned string with g_free() when done.
the tooltip text, or %NULL. You should free the
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().
%TRUE if the status icon is visible
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().
underlying X11 Window
An 32 bit unsigned integer identifier for the
Returns whether the status icon is embedded in a notification
area.
a notification area.
%TRUE if the status icon is embedded in
Makes @status_icon display the file @filename.
See gtk_status_icon_new_from_file() for details.
a filename
Makes @status_icon display the #GIcon.
See gtk_status_icon_new_from_gicon() for details.
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.
an icon name
Makes @status_icon display @pixbuf.
See gtk_status_icon_new_from_pixbuf() for details.
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.
a stock icon id
Sets the has-tooltip property on @status_icon to @has_tooltip.
See #GtkStatusIcon:has-tooltip for more information.
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.
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.
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.
the title
Sets @markup as the contents of the tooltip, which is marked up with
the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
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().
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().
the contents of the tooltip for @status_icon
Shows or hides a status icon.
%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
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.
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 <link linkend="PangoMarkupFormat">Pango text markup
language</link>. 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.
for the event. %FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked
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.
for the event. %FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked
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 #GtkSettings:gtk-tooltip-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
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventScroll which triggered this signal
Gets emitted when the size available for the image
changes, e.g. because the notification area got resized.
size. Otherwise, GTK+ will scale the icon as necessary.
%TRUE if the icon was updated for the new
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
<emphasis>context id</emphasis> 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().
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
<emphasis>not</emphasis> shown in the UI.
an integer id
textual description of what context the new message is being used in
Retrieves the box containing the label widget.
a #GtkBox
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 context identifier
Pushes a new message onto a statusbar's stack.
gtk_statusbar_remove().
a message id that can be used with
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 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 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
Copies a stock item, mostly useful for language bindings and not in applications.
a new #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 #GtkStyle object encapsulates the information that provides the look and
feel for a widget.
<warning>
In GTK+ 3.0, GtkStyle has been deprecated and replaced by #GtkStyleContext.
</warning>
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.
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.
containing the rendered icon
a newly-created #GdkPixbuf
the #GtkIconSource specifying the icon to render
a text direction
a state
the size to render the icon at. 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.
a #GdkWindow
a state
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:
<literal>style = gtk_style_attach (style, window)</literal>
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.
Either @style, or a newly-created #GtkStyle.
a #GdkWindow.
Creates a copy of the passed in #GtkStyle object.
a copy of @style
Detaches a style from a window. If the style is not attached
to any windows anymore, it is unrealized. See gtk_style_attach().
Gets the values of a multiple style properties for @widget_type
from @style.
the #GType of a descendant of #GtkWidget
the name of the first style property to get
Queries the value of a style property corresponding to a
widget class is in the given style.
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.
the #GType of a descendant of #GtkWidget
the name of the first style property to get
a <type>va_list</type> 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
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.
%TRUE if the mapping was found.
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.
icon set of @stock_id
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.
containing the rendered icon
a newly-created #GdkPixbuf
the #GtkIconSource specifying the icon to render
a text direction
a state
the size to render the icon at. 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.
a #GdkWindow
a state
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.
a #GdkWindow
a state
a newly-created #GdkPixbuf
the #GtkIconSource specifying the icon to render
a text direction
a state
the size to render the icon at. 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 be also
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 gtk_style_context_set_screen(), as well
as updating the context yourself using gtk_style_context_invalidate()
whenever any of the conditions change, such as a change in the
#GtkSettings:gtk-theme-name setting or a hierarchy change in the rendered
widget.
<refsect2 id="gtkstylecontext-animations">
<title>Transition animations</title>
<para>
#GtkStyleContext has built-in support for state change transitions.
Note that these animations respect the #GtkSettings:gtk-enable-animations
setting.
</para>
<para>
For simple widgets where state changes affect the whole widget area,
calling gtk_style_context_notify_state_change() with a %NULL region
is sufficient to trigger the transition animation. And GTK+ already
does that when gtk_widget_set_state() or gtk_widget_set_state_flags()
are called.
</para>
<para>
If a widget needs to declare several animatable regions (i.e. not
affecting the whole widget area), its #GtkWidget::draw signal handler
needs to wrap the render operations for the different regions with
calls to gtk_style_context_push_animatable_region() and
gtk_style_context_pop_animatable_region(). These functions take an
identifier for the region which must be unique within the style context.
For simple widgets with a fixed set of animatable regions, using an
enumeration works well:
</para>
<example>
<title>Using an enumeration to identify animatable regions</title>
<programlisting>
enum {
REGION_ENTRY,
REGION_BUTTON_UP,
REGION_BUTTON_DOWN
};
...
gboolean
spin_button_draw (GtkWidget *widget,
cairo_t *cr)
{
GtkStyleContext *context;
context = gtk_widget_get_style_context (widget);
gtk_style_context_push_animatable_region (context,
GUINT_TO_POINTER (REGION_ENTRY));
gtk_render_background (cr, 0, 0, 100, 30);
gtk_render_frame (cr, 0, 0, 100, 30);
gtk_style_context_pop_animatable_region (context);
...
}
</programlisting>
</example>
<para>
For complex widgets with an arbitrary number of animatable regions, it
is up to the implementation to come up with a way to uniquely identify
each animatable region. Using pointers to internal structs is one way
to achieve this:
</para>
<example>
<title>Using struct pointers to identify animatable regions</title>
<programlisting>
void
notebook_draw_tab (GtkWidget *widget,
NotebookPage *page,
cairo_t *cr)
{
gtk_style_context_push_animatable_region (context, page);
gtk_render_extension (cr, page->x, page->y, page->width, page->height);
gtk_style_context_pop_animatable_region (context);
}
</programlisting>
</example>
<para>
The widget also needs to notify the style context about a state change
for a given animatable region so the animation is triggered.
</para>
<example>
<title>Triggering a state change animation on a region</title>
<programlisting>
gboolean
notebook_motion_notify (GtkWidget *widget,
GdkEventMotion *event)
{
GtkStyleContext *context;
NotebookPage *page;
context = gtk_widget_get_style_context (widget);
page = find_page_under_pointer (widget, event);
gtk_style_context_notify_state_change (context,
gtk_widget_get_window (widget),
page,
GTK_STATE_PRELIGHT,
TRUE);
...
}
</programlisting>
</example>
<para>
gtk_style_context_notify_state_change() accepts %NULL region IDs as a
special value, in this case, the whole widget area will be updated
by the animation.
</para>
</refsect2>
<refsect2 id="gtkstylecontext-classes">
<title>Style classes and regions</title>
<para>
Widgets can add style classes to their context, which can be used
to associate different styles by class (see <xref linkend="gtkcssprovider-selectors"/>). Theme engines can also use style classes to vary their
rendering. GTK+ has a number of predefined style classes:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Style class</entry>
<entry>Macro</entry>
<entry>Used by</entry>
</row>
</thead>
<tbody>
<row>
<entry>button</entry>
<entry>GTK_STYLE_CLASS_BUTTON</entry>
<entry>#GtkButton, #GtkToggleButton, #GtkRadioButton, #GtkCheckButton</entry>
</row>
<row>
<entry>default</entry>
<entry>GTK_STYLE_CLASS_DEFAULT</entry>
<entry>#GtkButton</entry>
</row>
<row>
<entry>check</entry>
<entry>GTK_STYLE_CLASS_CHECK</entry>
<entry>#GtkCheckButton, #GtkCheckMenuItem, #GtkCellRendererToggle</entry>
</row>
<row>
<entry>radio</entry>
<entry>GTK_STYLE_CLASS_RADIO</entry>
<entry>#GtkRadioButton, #GtkRadioMenuItem, #GtkCellRendererToggle</entry>
</row>
<row>
<entry>arrow</entry>
<entry>GTK_STYLE_CLASS_ARROW</entry>
<entry>#GtkArrow</entry>
</row>
<row>
<entry>calendar</entry>
<entry>GTK_STYLE_CLASS_CALENDAR</entry>
<entry>#GtkCalendar</entry>
</row>
<row>
<entry>entry</entry>
<entry>GTK_STYLE_CLASS_ENTRY</entry>
<entry>#GtkEntry</entry>
</row>
<row>
<entry>cell</entry>
<entry>GTK_STYLE_CLASS_CELL</entry>
<entry>#GtkCellRendererToggle</entry>
</row>
<row>
<entry>menu</entry>
<entry>GTK_STYLE_CLASS_MENU</entry>
<entry>#GtkMenu, #GtkMenuItem, #GtkCheckMenuItem, #GtkRadioMenuItem</entry>
</row>
<row>
<entry>expander</entry>
<entry>GTK_STYLE_CLASS_EXPANDER</entry>
<entry>#GtkExpander</entry>
</row>
<row>
<entry>tooltip</entry>
<entry>GTK_STYLE_CLASS_TOOLTIP</entry>
<entry>#GtkTooltip</entry>
</row>
<row>
<entry>frame</entry>
<entry>GTK_STYLE_CLASS_FRAME</entry>
<entry>#GtkFrame</entry>
</row>
<row>
<entry>scrolled-window</entry>
<entry></entry>
<entry>#GtkScrolledWindow</entry>
</row>
<row>
<entry>viewport</entry>
<entry></entry>
<entry>#GtkViewport</entry>
</row>
<row>
<entry>trough</entry>
<entry>GTK_STYLE_CLASS_TROUGH</entry>
<entry>#GtkScrollbar, #GtkProgressBar, #GtkScale</entry>
</row>
<row>
<entry>progressbar</entry>
<entry>GTK_STYLE_CLASS_PROGRESSBAR</entry>
<entry>#GtkProgressBar, #GtkCellRendererProgress</entry>
</row>
<row>
<entry>slider</entry>
<entry>GTK_STYLE_CLASS_SLIDER</entry>
<entry>#GtkScrollbar, #GtkScale</entry>
</row>
<row>
<entry>menuitem</entry>
<entry>GTK_STYLE_CLASS_MENUITEM</entry>
<entry>#GtkMenuItem</entry>
</row>
<row>
<entry>popup</entry>
<entry></entry>
<entry>#GtkMenu</entry>
</row>
<row>
<entry>accelerator</entry>
<entry>GTK_STYLE_CLASS_ACCELERATOR</entry>
<entry>#GtkAccelLabel</entry>
</row>
<row>
<entry>menubar</entry>
<entry>GTK_STYLE_CLASS_MENUBAR</entry>
<entry>#GtkMenuBar</entry>
</row>
<row>
<entry>toolbar</entry>
<entry>GTK_STYLE_CLASS_TOOLBAR</entry>
<entry>#GtkToolbar</entry>
</row>
<row>
<entry>dock</entry>
<entry>GTK_STYLE_CLASS_DOCK</entry>
<entry>#GtkHandleBox</entry>
</row>
<row>
<entry>notebook</entry>
<entry></entry>
<entry>#GtkNotebook</entry>
</row>
<row>
<entry>background</entry>
<entry>GTK_STYLE_CLASS_BACKGROUND</entry>
<entry>#GtkWindow</entry>
</row>
<row>
<entry>rubberband</entry>
<entry>GTK_STYLE_CLASS_RUBBERBAND</entry>
<entry></entry>
</row>
<row>
<entry>header</entry>
<entry>GTK_STYLE_CLASS_HEADER</entry>
<entry></entry>
</row>
<row>
<entry>grip</entry>
<entry>GTK_STYLE_CLASS_GRIP</entry>
<entry>#GtkWindow</entry>
</row>
<row>
<entry>spinner</entry>
<entry>GTK_STYLE_CLASS_SPINNER</entry>
<entry>#GtkSpinner</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
Widgets can also add regions with flags to their context.
The regions used by GTK+ widgets are:
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Region</entry>
<entry>Flags</entry>
<entry>Macro</entry>
<entry>Used by</entry>
</row>
</thead>
<tbody>
<row>
<entry>row</entry>
<entry>even, odd</entry>
<entry>GTK_STYLE_REGION_ROW</entry>
<entry>#GtkTreeView</entry>
</row>
<row>
<entry>column</entry>
<entry>first, last, sorted</entry>
<entry>GTK_STYLE_REGION_COLUMN</entry>
<entry>#GtkTreeView</entry>
</row>
<row>
<entry>column-header</entry>
<entry></entry>
<entry>GTK_STYLE_REGION_COLUMN_HEADER</entry>
<entry></entry>
</row>
<row>
<entry>tab</entry>
<entry>even, odd, first, last</entry>
<entry>GTK_STYLE_REGION_TAB</entry>
<entry>#GtkNotebook</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect2>
<refsect2 id="gtkstylecontext-custom-styling">
<title>Custom styling in UI libraries and applications</title>
<para>
If you are developing a library with custom #GtkWidget<!-- -->s 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 theming engines may still attempt
to style your UI elements in a different way if needed so.
</para>
<para>
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
<filename><replaceable>XDG_CONFIG_HOME</replaceable>/gtk-3.0/gtk.css</filename> will
still take precedence over your changes, as it uses the
%GTK_STYLE_PROVIDER_PRIORITY_USER priority.
</para>
<para>
If a custom theming engine is needed, you probably want to implement a
#GtkStyleProvider yourself so it points to your #GtkThemingEngine
implementation, as #GtkCssProvider uses gtk_theming_engine_load()
which loads the theming engine module from the standard paths.
</para>
</refsect2>
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.
<note>
This function is only useful when using the theming layer
separated from GTK+, if you are using #GtkStyleContext to
theme #GtkWidget<!-- -->s, use gtk_widget_get_style_context()
in order to get a style context ready to theme the widget.
</note>
A newly created #GtkStyleContext.
Adds a global style provider to @screen, which will be used
in style construction for all #GtkStyleContext<!-- -->s under
GTK+ uses this to make styling information from #GtkSettings
available.
<note><para>If both priorities are the same, A #GtkStyleProvider
added through gtk_style_context_add_provider() takes precedence
over another added through this function.</para></note>
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 an "entry"
class, would be matched by:
<programlisting>
GtkEntry.entry { ... }
</programlisting>
While any widget defining an "entry" class would be
matched by:
<programlisting>
.entry { ... }
</programlisting>
class name to use in styling
Adds a style provider to @context, to be used in style construction.
<note><para>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().</para></note>
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:
<programlisting>
GtkTreeView row { ... }
</programlisting>
Pseudo-classes are used for matching @flags, so the two
following rules:
<programlisting>
GtkTreeView row:nth-child (even) { ... }
GtkTreeView row:nth-child (odd) { ... }
</programlisting>
would apply to even and odd rows, respectively.
<note><para>Region names must only contain lowercase letters
and '-', starting always with a lowercase letter.</para></note>
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.
animatable region to stop, or %NULL. See gtk_style_context_push_animatable_region()
Retrieves several style property values from @context for a
given state.
state to retrieve the property values for
Gets the background color for a given state.
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_PROPERTY_BORDER_WIDTH.
state to retrieve the border for
return value for the border settings
Gets the border color for a given state.
state to retrieve the color for
return value for the border color
Gets the foreground color for a given state.
state to retrieve the color for
return value for the foreground color
Returns the widget direction used for rendering.
the widget direction
Returns the font description for a given state. The returned
object is const and will remain valid until the
#GtkStyleContext::changed signal happens.
state. This object is owned by GTK+ and should not be
freed.
the #PangoFontDescription for the given
state to retrieve the font for
Returns the sides where rendered elements connect visually with others.
the junction sides
Gets the margin for a given state as a #GtkBorder.
See %GTK_STYLE_PROPERTY_MARGIN.
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_PROPERTY_PADDING.
state to retrieve the padding for
return value for the padding settings
Returns the widget path used for style matching.
A #GtkWidgetPath
Gets a style property from @context for the given state.
When @value is no longer needed, g_value_unset() must be called
to free any allocated memory.
style property name
state to retrieve the property value for
return location for the style property value
Returns the #GdkScreen to which @context is attached.
a #GdkScreen.
Returns the state used when rendering.
the state flags
Retrieves several widget style properties from @context according to the
current style.
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.
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.
va_list of property name/return location pairs, followed by %NULL
Retrieves several style property values from @context for a given state.
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 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 region name
return location for region flags
Invalidates @context style information, so it will be reconstructed
again.
If you're using a #GtkStyleContext returned from
gtk_widget_get_style_context(), you do not need to
call this yourself.
Returns the list of classes currently defined in @context.
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 #GList of
Returns the list of regions currently defined in @context.
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 #GList of
Looks up and resolves a color name in the @context color map.
%TRUE if @color_name was found and resolved, %FALSE otherwise
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.
The looked up %GtkIconSet, or %NULL
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
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:
<programlisting>
gtk_style_context_notify_state_change (context,
gtk_widget_get_window (widget),
NULL,
GTK_STATE_PRELIGHT,
button->in_button);
</programlisting>
Can be handled in the CSS file like this:
<programlisting>
GtkButton {
}
GtkButton:hover {
}
</programlisting>
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.
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().
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 theming engine
can uniquely identify rendered elements subject to a state transition.
unique identifier for the animatable region
Removes @class_name from @context.
class name to remove
Removes @provider from the style providers list in @context.
a #GtkStyleProvider
Removes a region from @context.
region name to unset
Restores @context state to a previous stage.
See gtk_style_context_save().
Saves the @context state, so all modifications done through
gtk_style_context_add_class(), gtk_style_context_remove_class(),
gtk_style_context_add_region(), gtk_style_context_remove_region()
or gtk_style_context_set_junction_sides() can be reverted in one
go through gtk_style_context_restore().
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.
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.
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.
the new direction.
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 theming engines.
Container widgets are expected to set junction hints as appropriate
for their children, so it should not normally be necessary to call
this function manually.
sides where rendered elements are visually connected to other elements
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 #GtkWidgetPath
Attaches @context to the given screen.
The screen is used to add style information from 'global' style
providers, such as the screens #GtkSettings instance.
If you are using a #GtkStyleContext returned from
gtk_widget_get_style_context(), you do not need to
call this yourself.
a #GdkScreen
Sets the state to be used when rendering with any
of the gtk_render_*() functions.
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.
%TRUE if there is a running transition animation for @state.
a widget state
return location for the transition progress
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.
Returns a newly created #GtkStyleProperties
a new #GtkStyleProperties
Returns %TRUE if a property has been registered, if @pspec or
will be respectively returned.
%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.
parsing function to use, or %NULL
the #GParamSpec for the new property
Clears all style information from @props.
Retrieves several style property values from @props for a
given state.
state to retrieve the property values for
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.
%TRUE if the property exists in @props, %FALSE otherwise
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.
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.
The mapped color
color name to lookup
Maps @color so it can be referenced by @name. See
gtk_style_properties_lookup_color()
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.
a second #GtkStyleProperties
whether to replace values or not
Sets several style properties on @props.
state to set the values for
Sets a styling property in @props.
styling property to set
state to set the value for
new value for the property
Sets several style properties on @props.
state to set the values for
va_list of property name/value pairs, followed by %NULL
Unsets a style property in @props.
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.
The icon factory to use for @path, or %NULL
#GtkWidgetPath to query
Returns the style settings affecting a widget defined by @path, or %NULL if
style settings affecting @path
a #GtkStyleProperties containing the
#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
#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.
The icon factory to use for @path, or %NULL
#GtkWidgetPath to query
Returns the style settings affecting a widget defined by @path, or %NULL if
style settings affecting @path
a #GtkStyleProperties containing the
#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
#GtkWidgetPath to query
state to query the style property for
The #GParamSpec to query
return location for the property value
a #GtkStyleProperties containing the
#GtkWidgetPath to query
%TRUE if the property was found and has a value, %FALSE otherwise
#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
#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.
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
Changes the state of @sw to the desired one.
%TRUE if @sw should be active, and %FALSE otherwise
Whether the #GtkSwitch widget is in its on or off state.
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 <structname>GtkSwitchClass</structname> structure contains only
private data.
GtkSymbolicColor is a boxed type that represents a symbolic color.
It is the result of parsing a
<link linkend="gtkcssprovider-symbolic-colors">color expression</link>.
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.
Creates a symbolic color pointing to a literal color.
a newly created #GtkSymbolicColor
a #GdkRGBA
Creates a symbolic color pointing to an unresolved named
color. See gtk_style_context_lookup_color() and
gtk_style_properties_lookup_color().
a newly created #GtkSymbolicColor
color name
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.
A newly created #GtkSymbolicColor
factor to apply to @color alpha
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.
A newly created #GtkSymbolicColor
another color to mix
mix factor
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.
A newly created #GtkSymbolicColor
shading factor to apply to @color
Increases the reference count of @color
the same @color
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.
gtk_symbolic_color_named_new(), but can be omitted in other cases.
%TRUE if the color has been resolved
#GtkStyleProperties to use when resolving named colors, or %NULL
return location for the resolved color
Decreases the reference count of @color, freeing its memory if the
reference count reaches 0.
Gets the amount of space between column @col, and
column @col + 1. See gtk_table_set_col_spacing().
the column spacing
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())
the default column spacing
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())
the default row spacing
Returns whether the table cells are all constrained to the same
width and height. (See gtk_table_set_homogenous ())
%TRUE if the cells are all constrained to the same size
Gets the amount of space between row @row, and
row @row + 1. See gtk_table_set_row_spacing().
the row spacing
a row in the table, 0 indicates the first row
Gets the number of rows and columns in the table.
return location for the number of rows, or %NULL
return location for the number of columns, or %NULL
A #GtkTargetEntry structure 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.
Makes a new #GtkTargetEntry structure.
Free with gtk_target_entry_free()
a pointer to a new GtkTargetEntry structure.
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 structure and its data.
Free with gtk_target_entry_free()
a pointer to a copy of @data.
Frees a #GtkTargetEntry structure returned from
gtk_target_entry_new() or gtk_target_entry_copy().
A #GtkTargetList structure is a reference counted list
of #GtkTargetPair. It is used to represent the same
information as a table of #GtkTargetEntry, but in
an efficient form. This structure 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.
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 #GtkSelection to
the target list. All targets are added with the same @info.
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.
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.
the table of #GtkTargetEntry
number of targets in the table
Appends the text targets supported by #GtkSelection to
the target list. All targets are added with the same @info.
an ID that will be passed back to the application
Appends the URI targets supported by #GtkSelection to
the target list. All targets are added with the same @info.
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
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.
Removes a target from a target list.
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.
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.
Creates a #GtkTextAttributes, which describes
a set of properties on some text.
a new #GtkTextAttributes
Copies @src and returns a new #GtkTextAttributes.
a copy of @src
Copies the values from @src to @dest so that @dest has the same values
as @src. Frees existing values in @dest.
another #GtkTextAttributes
Increments the reference count on @values.
the #GtkTextAttributes that were passed in
Decrements the reference count on @values, freeing the structure
if the reference count reaches 0.
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.
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.
Should be paired with a call to gtk_text_buffer_begin_user_action().
See that function for a full explanation.
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.
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().
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
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 "mark-set" signal as notification of the mark's initial
placement.
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 #GtkClipboard
Emits the "apply-tag" signal on @buffer. The default
handler for the signal applies @tag to the given range.
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().
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 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.
Copies the currently-selected text to a clipboard.
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
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 <emphasis>not</emphasis> 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 "mark-set" signal as notification of the mark's initial
placement.
the new #GtkTextMark object
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
name of the new tag, or %NULL
name of first property to set, or %NULL
Copies the currently-selected text to a clipboard, then deletes
said text if it's editable.
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 position in @buffer
another position in @buffer
Deletes all <emphasis>editable</emphasis> 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
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 "mark-deleted" signal will be emitted as notification after
the mark is deleted.
a #GtkTextMark in @buffer
Deletes the mark named @name; the mark must exist. See
gtk_text_buffer_delete_mark() for details.
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
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.
gtk_text_buffer_register_deserialize_format() or
gtk_text_buffer_register_deserialize_tagset() beforehand.
%TRUE on success, %FALSE otherwise.
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 #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 #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.
Retrieves the first and last iterators in the buffer, i.e. the
entire buffer lies within the range [@start,@end).
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
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
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()
#GdkAtom<!-- -->s representing the registered formats.
an array of
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.
iterator to initialize
Indicates whether the buffer has some text currently selected.
%TRUE if the there is text selected
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
Obtains the location of @anchor within @buffer.
an iterator to be initialized
a child anchor that appears in @buffer
Initializes @iter to the start of the given line.
iterator to initialize
line number counting from 0
Obtains an iterator pointing to @byte_index within the given line.
beyond the end of the line. Note <emphasis>bytes</emphasis>, not
characters; UTF-8 may encode one character as multiple bytes.
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. The @char_offset must exist, offsets off the end of the line
are not allowed. Note <emphasis>characters</emphasis>, not bytes;
UTF-8 may encode one character as multiple bytes.
iterator to initialize
line number counting from 0
char offset from start of line
Initializes @iter with the current position of @mark.
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.
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
Returns the mark named @name in buffer @buffer, or %NULL if no such
mark exists in the buffer.
a #GtkTextMark, or %NULL
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
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
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
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).
NULL, then they are not filled in, but the return value still indicates
whether text is selected.
whether the selection has nonzero length
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()
#GdkAtom<!-- -->s representing the registered formats.
an array of
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
0xFFFC character whenever the buffer contains
embedded images, so byte and character indexes into
the returned string <emphasis>do</emphasis> 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
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.
iterator to initialize
Get the #GtkTextTagTable associated with this buffer.
the buffer's tag table
Returns the text in the range [@start,@end). Excludes undisplayed
text (text marked with tags that set the invisibility attribute) if
representing embedded images, so byte and character indexes into
the returned string do <emphasis>not</emphasis> correspond to byte
and character indexes into the buffer. Contrast with
gtk_text_buffer_get_slice().
an allocated UTF-8 string
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,
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 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.
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.
location to insert the anchor
a #GtkTextChildAnchor
Like gtk_text_buffer_insert(), but the insertion will not occur if
want to prevent insertions at ineditable locations if the insertion
results from a user action (is interactive).
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 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.
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
text in UTF-8 format
length of text in bytes, or -1
default editability of buffer
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().
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
Implemented via emissions of the insert_text and apply_tag signals,
so expect those.
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 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.
an iterator in @buffer
UTF-8 text
length of @text, or -1
first tag to apply to @text
Same as gtk_text_buffer_insert_with_tags(), but allows you
to pass in tag names instead of tag objects.
position in @buffer
UTF-8 text
length of @text, or -1
name of a tag to apply to @text
Moves @mark to the new location @where. Emits the "mark-set" signal
as notification of the move.
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.
name of a mark
new location for mark
Pastes the contents of a clipboard at the insertion point, or
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.)
the #GtkClipboard to paste from
location to insert pasted text, or %NULL for at the cursor
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.
where to put the cursor
This function registers a rich text deserialization @function along with
its @mime_type with the passed @buffer.
newly registered format's mime-type.
the #GdkAtom that corresponds to the
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.
newly registered format's mime-type.
the #GdkAtom that corresponds to the
an optional tagset name, on %NULL
This function registers a rich text serialization @function along with
its @mime_type with the passed @buffer.
newly registered format's mime-type.
the #GdkAtom that corresponds to the
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
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.
newly registered format's mime-type.
the #GdkAtom that corresponds to the
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.
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 #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
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().
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.
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.
gtk_text_buffer_register_serialize_format() or
gtk_text_buffer_register_serialize_tagset() beforehand.
data, encoded as @format
the serialized
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 a "modified-changed" signal.
modification flag setting
Deletes current contents of @buffer, and inserts @text instead. If
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 #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 #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).
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.
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 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.
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.
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.
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.
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.
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.
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 ::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).
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
location to insert the pixbuf
a #GdkPixbuf
location to insert the anchor
a #GtkTextChildAnchor
a #GtkTextTag
one bound of range to be tagged
other bound of range to be tagged
a #GtkTextTag
one bound of range to be untagged
other bound of range to be untagged
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
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
You may wish to begin by reading the <link linkend="TextWidget">text widget
conceptual overview</link> which gives an overview of all the objects and data
types related to the text widget and how they work together.
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
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
number of characters to move
Like gtk_text_iter_forward_cursor_position(), but moves backward.
%TRUE if we moved
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
number of positions to move
Same as gtk_text_iter_forward_find_char(), but goes backward from @iter.
whether a match was found
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
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
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
number of lines to move backward
Same as gtk_text_iter_forward_search(), but moves backward.
whether a match was found
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
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
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
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 #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
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
number of positions to move
Moves @iter to the start of the previous visible line. Returns %TRUE if
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
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
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
Calls gtk_text_iter_backward_visible_word_start() up to @count times.
%TRUE if @iter moved and is not the end iterator
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
Calls gtk_text_iter_backward_word_start() up to @count times.
%TRUE if @iter moved and is not the end iterator
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 the gtk_text_iter_begins_tag () returns %TRUE if @iter is the
<emphasis>start</emphasis> of the tagged range;
gtk_text_iter_has_tag () tells you whether an iterator is
<emphasis>within</emphasis> a tagged range.
whether @iter is the start of a range tagged with @tag
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
%TRUE if text is editable by default
A qsort()-style function that returns negative if @lhs is less than
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
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 (<literal>GtkTextIter i = j;</literal>). The
function is used by language bindings.
a copy of the @iter, free with gtk_text_iter_free ()
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
%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
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.
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 the gtk_text_iter_ends_tag () returns %TRUE if @iter is the
<emphasis>end</emphasis> of the tagged range;
gtk_text_iter_has_tag () tells you whether an iterator is
<emphasis>within</emphasis> a tagged range.
whether @iter is the end of a range tagged with @tag
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
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
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
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
(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
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 structure and
pango_break() function.
%TRUE if we moved and the new position is dereferenceable
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
number of positions to move
Advances @iter, calling @pred on each character. If
If @pred never returns %TRUE, @iter is set to @limit if
whether a match was found
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
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
number of lines to move forward
Searches forward for @str. Any match is returned by setting
first character after the match. The search will not continue past
may wish to use @limit to avoid locking up your UI on large
buffers.
If the #GTK_TEXT_SEARCH_VISIBLE_ONLY flag is present, the match may
have invisible text interspersed in @str. i.e. @str will be a
possibly-noncontiguous subsequence of the matched range. similarly,
if you specify #GTK_TEXT_SEARCH_TEXT_ONLY, the match may have
pixbufs or child widgets mixed inside the matched range. If these
flags are not given, the match must be exact; the special 0xFFFC
character in @str will match embedded pixbufs or child widgets.
If you specify the #GTK_TEXT_SEARCH_CASE_INSENSITIVE flag, the text will
be matched regardless of what case it is in.
whether a match was found
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
bound for the search, 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
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
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.
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
Moves forward to the next toggle (on or off) of the
#GtkTextTag @tag, or to the next toggle of any tag if
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 #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
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
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
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
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
Calls gtk_text_iter_forward_visible_word_end() up to @count times.
%TRUE if @iter moved and is not the end iterator
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
Calls gtk_text_iter_forward_word_end() up to @count times.
%TRUE if @iter moved and is not the end iterator
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.
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
a #GtkTextAttributes to be filled in
Returns the #GtkTextBuffer this iterator is associated with.
the buffer
Returns the number of bytes in the line containing @iter,
including the paragraph delimiters.
number of bytes in the line
Returns the Unicode character at this iterator. (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
Returns the number of characters in the line containing @iter,
including the paragraph delimiters.
number of characters in the line
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
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
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
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
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
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
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
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
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 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
Returns <emphasis>text</emphasis> 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 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 <emphasis>not</emphasis> have the tag applied to it.
tags toggled at this point
%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
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
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 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 end of range
Returns %TRUE if @iter is within a range tagged with @tag.
whether @iter is tagged with @tag
a #GtkTextTag
Checks whether @iter falls in the range [@start, @end).
%TRUE if @iter is in the range
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.
Determines whether @iter is inside 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).
%TRUE if @iter is inside a word
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
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
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
Swaps the value of @first and @second if @second comes before
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.
another #GtkTextIter
Moves iterator @iter to the start of the line @line_number. If
buffer, moves @iter to the start of the last line in the buffer.
line number (counted from 0)
Same as gtk_text_iter_set_line_offset(), but works with a
<emphasis>byte</emphasis> 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 byte index relative to the start of @iter's current line
Moves @iter within a line, to a new <emphasis>character</emphasis>
(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 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 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 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 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
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.
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
This is equivalent to (gtk_text_iter_begins_tag () ||
gtk_text_iter_ends_tag ()), i.e. it tells you whether a range with
whether @tag is toggled on or off at @iter
a #GtkTextTag, or %NULL
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
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
Determines whether the mark has left gravity.
%TRUE if the mark has left gravity, %FALSE otherwise
Returns the mark name; returns NULL for anonymous marks.
mark name
Returns %TRUE if the mark is visible (i.e. a cursor is displayed
for it).
%TRUE if visible
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.
visibility of mark
You may wish to begin by reading the <link linkend="TextWidget">text widget
conceptual overview</link> 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 <application>gtk3-demo</application> for numerous examples.
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)
object that received the event, such as a widget
the event
location where the event was received
Emits the "event" signal on the #GtkTextTag.
result of signal emission (whether the event was handled)
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.
Sets the priority of a #GtkTextTag. Valid priorities are
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.
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).
Font description as string, e.g. \"Sans Italic 12\".
Note that the initial value of this property depends on
the internals of #PangoFontDescription.
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().
The paragraph background color as a string.
The paragraph background color as a as a (possibly unallocated)
#GdkColor.
The ::event signal is emitted when an event occurs on a region of the
buffer marked with this tag.
event. %FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the
the object the event was fired from (typically a #GtkTextView)
the event which triggered the signal
a #GtkTextIter pointing at the location the event occured
result of signal emission (whether the event was handled)
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 <link linkend="TextWidget">text widget
conceptual overview</link> which gives an overview of all the objects and
data types related to the text widget and how they work together.
<refsect2 id="GtkTextTagTable-BUILDER-UI">
<title>GtkTextTagTables as GtkBuildable</title>
<para>
The GtkTextTagTable implementation of the GtkBuildable interface
supports adding tags by specifying "tag" as the "type"
attribute of a <child> element.
<example>
<title>A UI definition fragment specifying tags</title>
<programlisting><![CDATA[
<object class="GtkTextTagTable">
<child type="tag">
<object class="GtkTextTag"/>
</child>
</object>
]]></programlisting>
</example>
</para>
</refsect2>
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.
the same name as an already-added tag.
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 function to call on each tag
user data
Returns the size of the table (number of tags)
number of tags in @table
Look up a named tag.
The tag, or %NULL if none by that name is in the table.
name of a tag
Remove a tag from the table. This will remove the table's
reference to the tag, so be careful - the tag will end
up destroyed if you don't have a reference to it.
a #GtkTextTag
the added tag.
the changed tag.
whether the size has been changed.
the removed tag.
You may wish to begin by reading the <link linkend="TextWidget">text widget
conceptual overview</link> which gives an overview of all the objects and data
types related to the text widget and how they work together.
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
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 #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 the #GdkWindow in question, and
that these coordinates have no sane relationship 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), you'll need to compute the child's correct position
in buffer coordinates any time scrolling occurs or buffer changes
occur, and then call gtk_text_view_move_child() to update the
child's position.
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 #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 #GtkTextIter
Converts coordinate (@buffer_x, @buffer_y) to coordinates for the window
Note that you can't convert coordinates for a nonexisting window (see
gtk_text_view_set_border_window_size()).
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 #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 #GtkTextIter
Returns whether pressing the Tab key inserts a tab characters.
gtk_text_view_set_accepts_tab().
%FALSE if pressing the Tab key moves the keyboard focus.
%TRUE if pressing the Tab key inserts a tab character,
Gets the width of the specified border window. See
gtk_text_view_set_border_window_size().
width of window
window to return size from
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
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 #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 is being displayed.
whether the insertion mark is visible
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.
a new #GtkTextAttributes
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
Gets the horizontal-scrolling #GtkAdjustment.
pointer to the horizontal #GtkAdjustment
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
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().
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 <emphasis>between</emphasis>
characters.
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 #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
Gets the default left margin size of paragraphs in the @text_view.
Tags in the buffer may override the default.
left margin in pixels
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 #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 #GtkTextIter
return location for a y coordinate
return location for a height
Returns whether the #GtkTextView is in overwrite mode or not.
whether @text_view is in overwrite mode or not.
Gets the default number of pixels to put above paragraphs.
default number of pixels above paragraphs
Gets the value set by gtk_text_view_set_pixels_below_lines().
default number of blank pixels below paragraphs
Gets the value set by gtk_text_view_set_pixels_inside_wrap().
default number of pixels of blank space between wrapped lines
Gets the default right margin for text in @text_view. Tags
in the buffer may override the default.
right margin in pixels
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().
tabs are used; must be freed with pango_tab_array_free().
copy of default tab array, or %NULL if "standard"
Gets the vertical-scrolling #GtkAdjustment.
pointer to the vertical #GtkAdjustment
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().
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
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 <literal>event->window</literal> to
see which window it was.
the window type.
a window type
Gets the line wrapping for the view.
the line wrap setting
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.
|[
static gboolean
gtk_foo_bar_key_press_event (GtkWidget *widget,
GdkEventKey *event)
{
if ((key->keyval == GDK_KEY_Return || key->keyval == GDK_KEY_KP_Enter))
{
if (gtk_text_view_im_context_filter_keypress (GTK_TEXT_VIEW (view), 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.
the key event
Updates the position of a child, as for gtk_text_view_add_child_in_window().
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 #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 #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.
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.
Scrolls @text_view the minimum distance such that @mark is contained
within the visible area of the widget.
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
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 #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
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.
%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," it doesn't work
with #GTK_TEXT_WINDOW_WIDGET, #GTK_TEXT_WINDOW_TEXT, or
#GTK_TEXT_WINDOW_PRIVATE.
window to affect
width or height of the window
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 #GtkTextBuffer
Toggles whether the insertion point is displayed. A buffer with no editable
text probably shouldn't have a visible cursor, so you may want to turn
the cursor off.
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.
whether it's editable
Sets the default indentation for paragraphs in @text_view.
Tags in the buffer may override the default.
indentation in pixels
Sets the default justification of text in @text_view.
Tags in the view's buffer may override the default.
justification
Sets the default left margin for text in @text_view.
Tags in the buffer may override the default.
left margin in pixels
Changes the #GtkTextView overwrite mode.
%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.
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.
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.
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.
right margin in pixels
Sets the default tab stops for paragraphs in @text_view.
Tags in the buffer may override the default.
tabs as a #PangoTabArray
Sets the line wrapping for the view.
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 #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 #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
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.
The ::backspace signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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 ::insert-at-cursor signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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 ::move-cursor signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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.
<itemizedlist>
<listitem>Arrow keys move by individual characters/lines</listitem>
<listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
<listitem>Home/End keys move to the ends of the buffer</listitem>
<listitem>PageUp/PageDown keys move vertically by pages</listitem>
<listitem>Ctrl-PageUp/PageDown keys move horizontally by pages</listitem>
</itemizedlist>
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
<link linkend="keybinding-signals">keybinding signal</link>
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 move, as a #GtkMovementStep
the number of @step units to move
The ::paste-clipboard signal is a
<link linkend="keybinding-signals">keybinding signal</link>
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 menuitems to the @menu.
the menu 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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
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
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted to toggle the visibility of the cursor.
The default binding for this signal is F7.
The ::toggle-overwrite signal is a
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted to toggle the overwrite mode of the text view.
The default bindings for this signal is Insert.
#GtkThemingEngine is the object used for rendering themed content
in GTK+ widgets. Even though GTK+ has a default implementation,
it can be overridden in CSS files by enforcing a #GtkThemingEngine
object to be loaded as a module.
In order to implement a theming engine, a #GtkThemingEngine subclass
must be created, alongside the CSS file that will reference it, the
theming engine would be created as an .so library, and installed in
$(gtk-modules-dir)/theming-engines/.
#GtkThemingEngine<!-- -->s have limited access to the object they are
rendering, the #GtkThemingEngine API has read-only accessors to the
style information contained in the rendered object's #GtkStyleContext.
Loads and initializes a theming engine module from the
standard directories.
the engine @name doesn't exist.
A theming engine, or %NULL if
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.
<note>
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 #GtkThemeEngine<!-- -->s yourself.
</note>
<note>
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.
<programlisting>
* {
-SomeEngine-custom-property: 2;
}
</programlisting>
</note>
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.
state to retrieve values for
Gets the background color for a given state.
state to retrieve the color for
return value for the background color
Gets the border for a given state as a #GtkBorder.
state to retrieve the border for
return value for the border settings
Gets the border color for a given state.
state to retrieve the color for
return value for the border color
Gets the foreground color for a given state.
state to retrieve the color for
return value for the foreground color
Returns the widget direction used for rendering.
the widget direction
Returns the font description for a given state.
state. This object is owned by GTK+ and should not be
freed.
the #PangoFontDescription for the given
state to retrieve the font for
Returns the widget direction used for rendering.
the widget direction
Gets the margin for a given state as a #GtkBorder.
state to retrieve the border for
return value for the margin settings
Gets the padding for a given state as a #GtkBorder.
state to retrieve the padding for
return value for the padding settings
Returns the widget path used for style matching.
A #GtkWidgetPath
Gets a property value as retrieved from the style settings that apply
to the currently rendered element.
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.
returns the state used when rendering.
the state flags
Retrieves several widget style properties from @engine according
to the currently rendered content's style.
Gets the value for a widget style property.
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.
va_list of property name/return location pairs, followed by %NULL
Retrieves several style property values that apply to the currently
rendered element.
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
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 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
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.
%TRUE if there is a running transition animation for @state.
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
<programlisting>
-Clearlooks-glossy: true;
</programlisting>
Base class for theming engines.
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.
Returns the checked state of the toggle action.
the checked state of the toggle action
Returns whether the action should have proxies like a radio action.
whether the action should have proxies like a radio action.
Sets the checked state on the toggle action.
whether the action should be checked or not
Sets whether the action should have proxies like a radio action.
whether the action should have proxies like a radio action
Emits the "toggled" signal on the toggle action.
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.
#GtkToggleActionEntry structs are used with
gtk_action_group_add_toggle_actions() to construct toggle actions.
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
Gets the value set by gtk_toggle_button_set_inconsistent().
%TRUE if the button is displayed as inconsistent, %FALSE otherwise
Retrieves whether the button is displayed as a separate indicator
and label. See gtk_toggle_button_set_mode().
and label.
%TRUE if the togglebutton is drawn as a separate indicator
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.
%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
This function only affects instances of classes like #GtkCheckButton
and #GtkRadioButton that derive from #GtkToggleButton,
not instances of #GtkToggleButton itself.
if %TRUE, draw the button as a separate indicator and label; if %FALSE, draw the button like a normal button
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.
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
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.
whether @button should be active
If the toggle tool button should be pressed in.
Emitted whenever the toggle tool button changes state.
Creates a new %GtkToolButton using @icon_widget as icon and @label as
label.
A new #GtkToolButton
a #GtkMisc widget that will be used as icon widget, 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.
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().
no themed icon
the icon name or %NULL if the tool button has
Return the widget used as icon widget on @button.
See gtk_tool_button_set_icon_widget().
on @button, or %NULL.
The widget used as icon
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
Returns the widget used as label on @button.
See gtk_tool_button_set_label_widget().
on @button, or %NULL.
The widget used as label
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.
the name of the stock item for @button.
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().
mnemonics on menu items on the overflow menu.
%TRUE if underscores in the label property are used as
Sets the icon for the tool button from a named themed icon.
See the docs for #GtkIconTheme for more details.
The "icon_name" property only has an effect if not
overridden by non-%NULL "label", "icon_widget" and "stock_id"
properties.
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 "stock_id" property. If the
"stock_id" property is also %NULL, @button will not have an icon.
the widget used as icon, or %NULL
Sets @label as the label used for the tool button. The "label" property
only has an effect if not overridden by a non-%NULL "label_widget" property.
If both the "label_widget" and "label" properties are %NULL, the label
is determined by the "stock_id" property. If the "stock_id" property is also
%NULL, @button will not have a label.
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 "label" property is used
as label. If "label" is also %NULL, the label in the stock item
determined by the "stock_id" property is used as label. If
"stock_id" is also %NULL, @button does not have a label.
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 "label" and "icon_widget" properties.
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.
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 "label",
"icon_widget" or "stock_id" properties.
This signal is emitted when the tool button is clicked with the mouse
or activated with the keyboard.
#GtkToolItem<!-- -->s 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.
Returns the ellipsize mode used for @tool_item. Custom subclasses of
#GtkToolItem should call this function to find out how text should
be ellipsized.
should be ellipsized.
a #PangoEllipsizeMode indicating how text in @tool_item
Returns whether @tool_item is allocated extra space.
See gtk_tool_item_set_expand().
%TRUE if @tool_item is allocated extra space.
Returns whether @tool_item is the same size as other homogeneous
items. See gtk_tool_item_set_homogeneous().
items.
%TRUE if the item is the same size as other homogeneous
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.
used for @tool_item
a #GtkIconSize indicating the icon size
Returns whether @tool_item is considered important. See
gtk_tool_item_set_is_important()
%TRUE if @tool_item is considered important.
Returns the orientation used for @tool_item. Custom subclasses of
#GtkToolItem should call this function to find out what size icons
they should use.
used for @tool_item
a #GtkOrientation indicating the orientation
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
will not inadvertently change a menu item that they did not create.
gtk_tool_item_set_proxy_menu_item(), if the @menu_item_id<!-- -->s
match.
The #GtkMenuItem passed to
a string used to identify the menu item
Returns the relief style of @tool_item. See gtk_button_set_relief_style().
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.
for @tool_item.
a #GtkReliefStyle indicating the relief style used
Returns the text alignment used for @tool_item. Custom subclasses of
#GtkToolItem should call this function to find out how text should
be aligned.
used for @tool_item
a #gfloat indicating the horizontal text alignment
Returns the text orientation used for @tool_item. Custom subclasses of
#GtkToolItem should call this function to find out how text should
be orientated.
used for @tool_item
a #GtkOrientation indicating the text orientation
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
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:
<itemizedlist>
<listitem> GTK_TOOLBAR_BOTH, meaning the tool item should show
both an icon and a label, stacked vertically </listitem>
<listitem> GTK_TOOLBAR_ICONS, meaning the toolbar shows
only icons </listitem>
<listitem> GTK_TOOLBAR_TEXT, meaning the tool item should only
show text</listitem>
<listitem> GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
both an icon and a label, arranged horizontally (however, note the
#GtkToolButton::has_text_horizontally that makes tool buttons not
show labels when the toolbar style is GTK_TOOLBAR_BOTH_HORIZ.
</listitem>
</itemizedlist>
for @tool_item.
A #GtkToolbarStyle indicating the toolbar style used
Returns whether @tool_item has a drag window. See
gtk_tool_item_set_use_drag_window().
%TRUE if @tool_item uses a drag window.
Returns whether the @tool_item is visible on toolbars that are
docked horizontally.
docked horizontally.
%TRUE if @tool_item is visible on toolbars that are
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
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.
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.
overflow menu for @tool_item.
The #GtkMenuItem that is going to appear in the
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.
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.
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"
whether the tool item should be considered important
Sets the #GtkMenuItem used in the toolbar overflow menu. The
should also be used with gtk_tool_item_get_proxy_menu_item().
a string used to identify @menu_item
a #GtkMenuItem to be used in the overflow menu
Sets the markup text to be displayed as tooltip on the item.
See gtk_widget_set_tooltip_markup().
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().
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.
Whether @tool_item has a drag window.
Sets whether @tool_item is visible when the toolbar is docked horizontally.
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
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.
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
<itemizedlist>
<listitem>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
</listitem>
<listitem> call gtk_tool_item_set_proxy_menu_item() with a new menu
item and return %TRUE, or
</listitem>
<listitem> 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.
</listitem>
</itemizedlist>
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
<itemizedlist>
<listitem>gtk_tool_shell_get_orientation()</listitem>
<listitem>gtk_tool_shell_get_style()</listitem>
<listitem>gtk_tool_shell_get_icon_size()</listitem>
<listitem>gtk_tool_shell_get_relief_style()</listitem>
</itemizedlist>
to find out what the toolbar should look like and change
themselves accordingly.
A #GtkToolItemGroup is used together with #GtkToolPalette to add
#GtkToolItem<!-- -->s to a palette like container with different
categories and drag and drop support.
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
Gets the tool item at position (x, y).
the #GtkToolItem at position (x, y)
the x position
the y position
Gets the ellipsization mode of @group.
the #PangoEllipsizeMode of @group
Gets the relief mode of the header button of @group.
the #GtkReliefStyle
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 #GtkToolItem
Gets the label 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()
the label of @group. The label is an internal string of @group
Gets the label widget of @group.
See gtk_tool_item_group_set_label_widget().
the label widget of @group
Gets the number of tool items in @group.
the number of tool items in @group
Gets the tool item at @index in group.
the #GtkToolItem at index
the index
Inserts @item at @position in the list of children of @group.
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.
whether the @group should be collapsed or expanded
Sets the ellipsization mode which should be used by labels in @group.
the #PangoEllipsizeMode labels in @group should use
Set the button relief of the group header.
See gtk_button_set_relief() for details.
the #GtkReliefStyle
Sets the position of @item in the list of children of @group.
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.
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.
the widget to be displayed in place of the usual label
A #GtkToolPalette allows you to add #GtkToolItem<!-- -->s 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().
#GtkToolItem<!-- -->s 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().
|[
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_from_stock (GTK_STOCK_OK);
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.
|[
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);
]|
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 #GtkWidget which should be a drag destination for @palette
the flags that specify what actions GTK+ should take for drops on that widget
the #GtkToolPaletteDragTarget<!-- -->s which the widget should support
the #GdkDragAction<!-- -->s 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 #GtkSelectionData
Gets the group at position (x, y).
if there is no such group
the #GtkToolItemGroup at position or %NULL
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
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 #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 #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 #GtkToolItemGroup
Gets the horizontal adjustment of the tool palette.
the horizontal adjustment of @palette
Gets the size of icons in the tool palette.
See gtk_tool_palette_set_icon_size().
the #GtkIconSize of icons in the tool palette
Gets the style (icons, text or both) of items in the tool palette.
the #GtkToolbarStyle of items in the tool palette.
Gets the vertical adjustment of the tool palette.
the vertical adjustment of @palette
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().
the #GtkToolPaletteDragTarget<!-- -->s 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 #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 #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 #GtkToolItemGroup which is a child of palette
a new index for group
Sets the size of icons in the tool palette.
the #GtkIconSize that icons in the tool palette shall have
Sets the style (text, icons or both) of items in the tool palette.
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.
Unsets a toolbar style set with gtk_tool_palette_set_style(),
so that user preferences will be used to determine the toolbar style.
The size of the icons in a tool palette is normally determined by
the #GtkSettings:toolbar-icon-size setting. When this property is set,
it overrides the 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.
Flags used to specify the supported drag targets.
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
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
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.
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
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
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
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
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.
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
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 for icons of @shell
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
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.
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
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
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
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
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.
Virtual function table for the #GtkToolShell interface.
the current orientation of @shell
the current style of @shell
The relief style of buttons on @shell.
the current text orientation of @shell
the current text alignment of @shell
the current ellipsize mode of @shell
the current text size group of @shell
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.
Creating a context menu for the toolbar can be done by connecting to
the #GtkToolbar::popup-context-menu signal.
Creates a new toolbar.
the newly-created toolbar.
Returns the position corresponding to the indicated point on
this function returns the position a new item should be
inserted.
The position corresponding to the point (@x, @y) on the toolbar.
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 toolbar.
the current icon size for the icons on
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 #GtkToolItem that is a child of @toolbar
Returns the number of items on the toolbar.
the number of items on the toolbar
Returns the @n<!-- -->'th item on @toolbar, or %NULL if the
toolbar does not contain an @n<!-- -->'th item.
or %NULL if there isn't an @n<!-- -->'th item.
The @n<!-- -->'th #GtkToolItem on @toolbar,
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.
Returns whether the toolbar has an overflow menu.
See gtk_toolbar_set_show_arrow().
%TRUE if the toolbar has an overflow menu.
Retrieves whether the toolbar has text, icons, or both . See
gtk_toolbar_set_style().
the current style of @toolbar
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 #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 #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.
The #GtkIconSize that stock icons in the toolbar shall have.
Sets whether to show an overflow menu when
items that there are not room are available through an
overflow menu.
Whether to show an overflow menu
Alters the view of @toolbar to display either icons only, text only, or both.
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.
Unsets a toolbar style set with gtk_toolbar_set_style(), so that
user preferences will be used to determine the toolbar style.
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
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.
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:
<itemizedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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 stock icon, or even putting in
a custom widget.
</para>
</listitem>
<listitem>
<para>
Return %TRUE from your query-tooltip handler. This causes the tooltip to be
show. If you return %FALSE, it will not be shown.
</para>
</listitem>
</itemizedlist>
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:
<itemizedlist>
<listitem>
<para>
Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as
before.
</para>
</listitem>
<listitem>
<para>
Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as
tooltip window.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</itemizedlist>
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
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 #GtkWidget, or %NULL to unset the old custom widget.
Sets the icon of the tooltip (which is in front of the text) to be
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 #GIcon representing the icon, or %NULL
a stock icon size
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.
an icon name, or %NULL
a stock icon size
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.
a stock id, or %NULL
a stock icon size
Sets the text of the tooltip to be @markup, which is marked up
with the <link
linkend="PangoMarkupFormat">Pango text markup language</link>.
If @markup is %NULL, the label will be hidden.
a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) 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 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
gtk_tree_view_set_tooltip_cell().
a #GdkRectangle
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 equivilent. This is set by
calling gtk_tree_view_column_set_cell_data_func()
A #GtkTreeColumn
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
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
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
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
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
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
destination row
the data being dragged
whether a new row was created before position @dest
row to drop in front of
data to drop
%TRUE if a drop is possible before @dest_path
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
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
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
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
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
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
row on which user is initiating a drag
%TRUE if the row can be dragged
row on which user is initiating a drag
%TRUE if data of the required type was provided
row that was dragged
a #GtkSelectionData to fill with data from the dragged row
%TRUE if the row was successfully deleted
row that was being dragged
The <structname>GtkTreeIter</structname> is the primary structure
for accessing a #GtkTreeModel. Models are expected to put a unique
integer in the <structfield>stamp</structfield> member, and put
model-specific data in the three <structfield>user_data</structfield>
members.
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
(<literal>GtkTreeIter new_iter = iter;</literal>).
You must free this iter with gtk_tree_iter_free().
a newly-allocated copy of @iter
Frees an iterator that has been allocated by gtk_tree_iter_copy().
This function is mainly used for language bindings.
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
<literal>price_of(@a) - price_of(@b)</literal>.
a negative integer, zero or a positive integer depending on whether
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 and the
#GtkTreeIter<footnote><para>Here, <abbrev>iter</abbrev> is short
for <quote>iterator</quote></para></footnote>. Most of the interface
consists of operations on a #GtkTreeIter.
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 <quote>0</quote> refers to the root
node and the path <quote>2:4</quote> refers to the fifth child of
the third node.
By contrast, a #GtkTreeIter 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 <quote>3:2:5</quote>. While the first method shown is
easier, the second is much more common, as you often get paths from
callbacks.
<example>
<title>Acquiring a <structname>GtkTreeIter</structname></title>
<programlisting>
/* 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);
</programlisting>
</example>
This second example shows a quick way of iterating through a list
and getting a string and an integer from each row. The
<function>populate_model</function> 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.
<example>
<title>Reading data from a <structname>GtkTreeModel</structname></title>
<programlisting>
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 */
valid = gtk_tree_model_get_iter_first (list_store, &iter);
while (valid)
{
/* Walk through the list, reading each row */
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_free (str_data);
row_count++;
valid = gtk_tree_model_iter_next (list_store, &iter);
}
</programlisting>
</example>
Returns the type of the column.
the type of the column
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
Sets @iter to a valid iterator pointing to @path.
%TRUE, if @iter was set
the uninitialized #GtkTreeIter
the #GtkTreePath
Returns the number of columns supported by @tree_model.
the number of columns
Returns a newly-created #GtkTreePath referenced by @iter.
This path should be freed with gtk_tree_path_free().
a newly-created #GtkTreePath
the #GtkTreeIter
Initializes and sets @value to that at @column.
When done with @value, g_value_unset() needs to be called
to free any allocated memory.
the #GtkTreeIter
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
<literal>gtk_tree_model_get_iter_first (tree_model, iter);</literal>
%TRUE, if @child has been set to the first child
the new #GtkTreeIter to be set to the child
the #GtkTreeIter, or %NULL
Returns %TRUE if @iter has children, %FALSE otherwise.
%TRUE if @iter has children
the #GtkTreeIter 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
the #GtkTreeIter, 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
the #GtkTreeIter
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,
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
the #GtkTreeIter to set to the nth child
the #GtkTreeIter 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
called.
%TRUE, if @iter is set to the parent of @child
the new #GtkTreeIter to set to the parent
the #GtkTreeIter
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
the #GtkTreeIter
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). 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.
the #GtkTreeIter
Emits the #GtkTreeModel::row-changed signal on @tree_model.
a #GtkTreePath pointing to the changed row
a valid #GtkTreeIter 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.
a #GtkTreePath pointing to the previous location of the deleted row
Emits the #GtkTreeModel::row-has-child-toggled signal on
state of a node changes.
a #GtkTreePath pointing to the changed row
a valid #GtkTreeIter pointing to the changed row
Emits the #GtkTreeModel::row-inserted signal on @tree_model.
a #GtkTreePath pointing to the inserted row
a valid #GtkTreeIter 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 #GtkTreePath pointing to the tree node whose children have been reordered
a valid #GtkTreeIter 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<literal>[newpos] = oldpos</literal>
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.
the #GtkTreeIter
Creates a new #GtkTreeModel, with @child_model as the child_model
and @root as the virtual root.
A new #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 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
where <literal>place_string_here</literal> is a <type>gchar*</type>
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 row in @tree_model
Returns the type of the column.
the type of the column
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
Sets @iter to a valid iterator pointing to @path.
%TRUE, if @iter was set
the uninitialized #GtkTreeIter
the #GtkTreePath
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
the uninitialized #GtkTreeIter
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
an uninitialized #GtkTreeIter
a string representation of a #GtkTreePath
Returns the number of columns supported by @tree_model.
the number of columns
Returns a newly-created #GtkTreePath referenced by @iter.
This path should be freed with gtk_tree_path_free().
a newly-created #GtkTreePath
the #GtkTreeIter
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.
Must be freed with g_free().
a newly-allocated string.
a #GtkTreeIter
See gtk_tree_model_get(), this version takes a <type>va_list</type>
for language bindings to use.
a row in @tree_model
<type>va_list</type> 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.
the #GtkTreeIter
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
<literal>gtk_tree_model_get_iter_first (tree_model, iter);</literal>
%TRUE, if @child has been set to the first child
the new #GtkTreeIter to be set to the child
the #GtkTreeIter, or %NULL
Returns %TRUE if @iter has children, %FALSE otherwise.
%TRUE if @iter has children
the #GtkTreeIter 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
the #GtkTreeIter, 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
the #GtkTreeIter
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,
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
the #GtkTreeIter to set to the nth child
the #GtkTreeIter 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
called.
%TRUE, if @iter is set to the parent of @child
the new #GtkTreeIter to set to the parent
the #GtkTreeIter
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
the #GtkTreeIter
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). 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.
the #GtkTreeIter
Emits the #GtkTreeModel::row-changed signal on @tree_model.
a #GtkTreePath pointing to the changed row
a valid #GtkTreeIter 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.
a #GtkTreePath pointing to the previous location of the deleted row
Emits the #GtkTreeModel::row-has-child-toggled signal on
state of a node changes.
a #GtkTreePath pointing to the changed row
a valid #GtkTreeIter pointing to the changed row
Emits the #GtkTreeModel::row-inserted signal on @tree_model.
a #GtkTreePath pointing to the inserted row
a valid #GtkTreeIter 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 #GtkTreePath pointing to the tree node whose children have been reordered
a valid #GtkTreeIter 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<literal>[newpos] = oldpos</literal>
Creates a new #GtkTreeModel, with @child_model as the child model.
A new #GtkTreeModel.
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.
the #GtkTreeIter
This signal is emitted when a row in the model has changed.
a #GtkTreePath identifying the changed row
a valid #GtkTreeIter 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 identifying the row
This signal is emitted when a row has gotten the first child
row or lost its last child row.
a #GtkTreePath identifying the row
a valid #GtkTreeIter 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 identifying the new row
a valid #GtkTreeIter 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 <emphasis>not</emphasis> emitted
when rows are reordered by DND, since this is implemented
by removing and then reinserting the row.
a #GtkTreePath identifying the tree node whose children have been reordered
a valid #GtkTreeIter pointing to the node whose
an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order<literal>[newpos] = oldpos</literal>
A #GtkTreeModelFilter is a tree model which wraps another tree model,
and can do the following things:
<itemizedlist>
<listitem><para>
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.
</para></listitem>
<listitem><para>
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.
</para></listitem>
<listitem><para>
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.
</para></listitem>
</itemizedlist>
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.
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.
valid iterator pointing to a visible row in child model.
%TRUE, if @filter_iter was set, i.e. if @child_iter is a
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 #GtkTreePath to convert.
Sets @child_iter to point to the row pointed to by @filter_iter.
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,
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 #GtkTreePath to convert.
Returns a pointer to the child model of @filter.
A pointer to a #GtkTreeModel.
Emits ::row_changed for each row in the child model, which causes
the filter to re-evaluate whether a row is visible or not.
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 <emphasis>each</emphasis>
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.
The number of columns in the filter model.
The #GType<!-- -->s 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.
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 uptodate.
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.
<informalexample><programlisting>
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;
}
</programlisting></informalexample>
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.
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 #GtkTreePath pointing to the changed row
a valid #GtkTreeIter pointing to the changed row
a #GtkTreePath pointing to the inserted row
a valid #GtkTreeIter pointing to the inserted row
a #GtkTreePath pointing to the changed row
a valid #GtkTreeIter pointing to the changed row
a #GtkTreePath pointing to the previous location of the deleted row
a #GtkTreePath pointing to the tree node whose children have been reordered
a valid #GtkTreeIter 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<literal>[newpos] = oldpos</literal>
the flags supported by this interface
the number of columns
the type of the column
the column index
%TRUE, if @iter was set
the uninitialized #GtkTreeIter
the #GtkTreePath
a newly-created #GtkTreePath
the #GtkTreeIter
the #GtkTreeIter
the column to lookup the value at
an empty #GValue to set
%TRUE if @iter has been changed to the next node
the #GtkTreeIter
%TRUE if @iter has been changed to the previous node
the #GtkTreeIter
%TRUE, if @child has been set to the first child
the new #GtkTreeIter to be set to the child
the #GtkTreeIter, or %NULL
%TRUE if @iter has children
the #GtkTreeIter to test for children
the number of children of @iter
the #GtkTreeIter, or %NULL
%TRUE, if @parent has an @n<!-- -->th child
the #GtkTreeIter to set to the nth child
the #GtkTreeIter to get the child from, or %NULL.
the index of the desired child
%TRUE, if @iter is set to the parent of @child
the new #GtkTreeIter to set to the parent
the #GtkTreeIter
the #GtkTreeIter
the #GtkTreeIter
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.
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
valid iterator pointer to a visible row in the child model.
%TRUE, if @sort_iter was set, i.e. if @sort_iter is a
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,
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 #GtkTreePath to convert
Sets @child_iter to point to the row pointed to by @sorted_iter.
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 #GtkTreePath to convert
Returns the model the #GtkTreeModelSort is sorting.
the "child model" being sorted
<warning><para>
This function is slow. Only use it for debugging and/or testing purposes.
</para></warning>
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 #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.
Creates a new #GtkTreePath.
This structure refers to a row.
A newly created #GtkTreePath.
Creates a new #GtkTreePath.
The string representation of this path is "0".
A new #GtkTreePath
Creates a new path with @first_index and @varargs as indices.
A newly created #GtkTreePath
first integer
Creates a new #GtkTreePath initialized to @path.
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, 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.
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 to compare with
Creates a new #GtkTreePath as a copy of @path.
a new #GtkTreePath
Moves @path to point to the first child of the current path.
Frees @path.
Returns the current depth of @path.
The depth of @path
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 current indices, or %NULL
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.
indices, or %NULL
The current
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
another #GtkTreePath
Returns %TRUE if @path is a descendant of @ancestor.
%TRUE if @ancestor contains @path somewhere below it
another #GtkTreePath
Moves the @path to point to the next node at the current depth.
Prepends a new index to a path.
As a result, the depth of the path is increased.
the index
Moves the @path to point to the previous node at the
current depth, if it exists.
the move was made
%TRUE if @path has a previous node, and
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.
Must be freed with g_free().
A newly-allocated string.
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
Creates a row reference based on @path.
This reference will keep pointing to the node pointed to
by @path, so long as it exists. It listens to all signals
emitted by @model, and updates its path appropriately. If
a newly allocated #GtkTreeRowReference, or %NULL
a #GtkTreeModel
a valid #GtkTreePath 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 to monitor
Copies a #GtkTreeRowReference.
a copy of @reference
Free's @reference. @reference may be %NULL
Returns the model that the row reference is monitoring.
the model
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
Returns %TRUE if the @reference is non-%NULL and refers to
a current valid path.
%TRUE if @reference points to a valid path
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 independentally 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.
Gets the selection mode for @selection. See
gtk_tree_selection_set_mode().
the current selection mode
Returns the current selection function.
The function.
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 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 #GtkTreeRowReference<!-- -->s.
To do this, you can use gtk_tree_row_reference_new().
To free the return value, use:
|[
g_list_foreach (list, (GFunc) gtk_tree_path_free, NULL);
g_list_free (list);
]|
A #GList containing a #GtkTreePath for each selected row.
A pointer to set to the #GtkTreeModel, or %NULL.
Returns the tree view associated with @selection.
A #GtkTreeView
Returns the user data for the selection function.
The user data.
Returns %TRUE if the row at @iter is currently selected.
%TRUE, if @iter is selected
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 #GtkTreePath to check selection on.
Selects all the nodes. @selection must be set to #GTK_SELECTION_MULTIPLE
mode.
Selects the specified iterator.
The #GtkTreeIter to be selected.
Select the row at @path.
The #GtkTreePath to be selected.
Selects a range of nodes, determined by @start_path and @end_path inclusive.
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.
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.
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.
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.
Unselects the specified iterator.
The #GtkTreeIter to be unselected.
Unselects the row at @path.
The #GtkTreePath to be unselected.
Unselects a range of nodes, determined by @start_path and @end_path
inclusive.
The initial node of the range.
The initial node of the range.
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.
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.
column ids.
%TRUE if the sort column is not one of the special sort
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
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.
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:
<variablelist>
<varlistentry>
<term>%GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</term>
<listitem>the default sort function will be used, if it is set</listitem>
</varlistentry>
<varlistentry>
<term>%GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</term>
<listitem>no sorting will occur</listitem>
</varlistentry>
</variablelist>
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.
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.
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.
column ids.
%TRUE if the sort column is not one of the special sort
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
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.
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:
<variablelist>
<varlistentry>
<term>%GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</term>
<listitem>the default sort function will be used, if it is set</listitem>
</varlistentry>
<varlistentry>
<term>%GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</term>
<listitem>no sorting will occur</listitem>
</varlistentry>
</variablelist>
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.
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.
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.
%TRUE if the sort column is not one of the special sort
The sort column id to be filled in
The #GtkSortType to be filled in
the sort column id to set
The sort order of the column
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
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
The #GtkTreeStore 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 <link linkend="gtktreednd">drag and
drop</link> interfaces.
<refsect2 id="GtkTreeStore-BUILDER-UI">
<title>GtkTreeStore as GtkBuildable</title>
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.
<example>
<title>A UI Definition fragment for a tree store</title>
<programlisting><![CDATA[
<object class="GtkTreeStore">
<columns>
<column type="gchararray"/>
<column type="gchararray"/>
<column type="gint"/>
</columns>
</object>
]]></programlisting>
</example>
</refsect2>
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, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
GDK_TYPE_PIXBUF);</literal> will create a new #GtkTreeStore with three columns, of type
<type>int</type>, <type>string</type> and #GdkPixbuf respectively.
a new #GtkTreeStore
number of columns in the tree store
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().
An unset #GtkTreeIter to set to the appended row
A valid #GtkTreeIter, or %NULL
Removes all rows from @tree_store
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 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().
An unset #GtkTreeIter to set to the new row
A valid #GtkTreeIter, or %NULL
position to insert the new row
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,
this function is called. To fill in values, you need to call
gtk_tree_store_set() or gtk_tree_store_set_value().
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,
this function is called. To fill in values, you need to call
gtk_tree_store_set() or gtk_tree_store_set_value().
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 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
<literal>gtk_tree_store_insert_with_values (tree_store, iter, position, ...)</literal>
has the same effect as calling
|[
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.
An unset #GtkTreeIter to set the new row, or %NULL.
A valid #GtkTreeIter, or %NULL
position to insert the new row
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.
An unset #GtkTreeIter to set the new row, or %NULL.
A valid #GtkTreeIter, or %NULL
position to insert the new row
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 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 valid #GtkTreeIter
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 #GtkTreeIter.
Moves @iter in @tree_store to the position after @position. @iter and
works with unsorted stores. If @position is %NULL, @iter will be moved
to the start of the level.
A #GtkTreeIter.
A #GtkTreeIter.
Moves @iter in @tree_store to the position before @position. @iter and
works with unsorted stores. If @position is %NULL, @iter will be
moved to the end of the level.
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().
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 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 #GtkTreeIter.
an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. @new_order<literal>[newpos] = oldpos</literal>.
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
<literal>gtk_tree_store_set (store, iter, 0, "Foo", -1)</literal>.
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 valid #GtkTreeIter for the row being modified
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.
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 <type>va_list</type> for
use by language bindings.
A valid #GtkTreeIter for the row being modified
<type>va_list</type> 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 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 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 #GtkTreeIter.
Another #GtkTreeIter.
Widget that displays any object that implements the #GtkTreeModel interface.
Please refer to the <link linkend="TreeWidget">tree widget conceptual
overview</link> 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:
<inlinegraphic fileref="tree-view-coordinates.png" format="PNG"></inlinegraphic>
<variablelist><title>Coordinate systems in GtkTreeView API</title>
<varlistentry><term>Widget coordinates</term>
<listitem>
<para>
Coordinates relative to the widget (usually <literal>widget->window</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry><term>Bin window coordinates</term>
<listitem>
<para>
Coordinates relative to the window that GtkTreeView renders to.
</para>
</listitem>
</varlistentry>
<varlistentry><term>Tree coordinates</term>
<listitem>
<para>
Coordinates relative to the entire scrollable area of GtkTreeView. These
coordinates start at (0, 0) for row 0 of the tree.
</para>
</listitem>
</varlistentry>
</variablelist>
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).
<refsect2 id="GtkTreeView-BUILDER-UI">
<title>GtkTreeView as GtkBuildable</title>
The GtkTreeView implementation of the GtkBuildable interface accepts
#GtkTreeViewColumn objects as <child> elements and exposes the
internal #GtkTreeSelection in UI definitions.
<example>
<title>A UI definition fragment with GtkTreeView</title>
<programlisting><![CDATA[
<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>
]]></programlisting>
</example>
</refsect2>
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.
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.
The #GtkTreeViewColumn to add.
Recursively collapses all visible, expanded nodes in @tree_view.
Collapses a row (hides its child rows, if they exist).
%TRUE if the row was collapsed.
path to a row in the @tree_view
Resizes all columns to their optimal width. Only works after the
treeview has been realized.
Converts bin_window coordinates to coordinates for the
tree (the full scrollable area of the tree).
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.
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.
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.
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()).
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).
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 #GtkTreePath in @tree_view
Turns @tree_view into a drop destination for automatic DND. Calling
this method sets #GtkTreeView:reorderable to %FALSE.
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.
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.
Opens the row so its children are visible.
%TRUE if the row existed and had children
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 to a row.
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
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 #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 <literal>event->window</literal>
to confirm that the event on @tree_view is on the right window.
hasn't been realized yet
A #GdkWindow, or %NULL when @tree_view
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 #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.
position is outside the range of columns.
The #GtkTreeViewColumn, or %NULL if the
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
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 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
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.
is indeed the case.
whether there is a row at the given position, %TRUE if this
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.
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
Returns whether or not tree lines are drawn in @tree_view.
otherwise.
%TRUE if tree lines are drawn in @tree_view, %FALSE
Returns the column that is the current expander column.
This column has the expander arrow drawn next to it.
The expander column.
Returns whether fixed height mode is turned on for @tree_view.
%TRUE if @tree_view is in fixed height mode
Returns which grid lines are enabled in @tree_view.
are enabled.
a #GtkTreeViewGridLines value indicating which grid lines
Gets the #GtkAdjustment currently being used for the horizontal aspect.
if none is currently being used.
A #GtkAdjustment object, or %NULL
Returns whether all header columns are clickable.
%TRUE if all header columns are clickable, otherwise %FALSE
Returns %TRUE if the headers on the @tree_view are visible.
Whether the headers are visible or not.
Returns whether hover expansion mode is turned on for @tree_view.
%TRUE if @tree_view is in hover expansion mode
Returns whether hover selection mode is turned on for @tree_view.
%TRUE if @tree_view is in hover selection mode
Returns the amount, in pixels, of extra indentation for child levels
in @tree_view.
the amount of extra indentation for child levels in
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.
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 <literal>event->window ==
gtk_tree_view_get_bin_window (<!-- -->)</literal>. 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
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.
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.
Returns the current row separator function.
the current row separator function.
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.
Gets the setting set by gtk_tree_view_set_rules_hint().
%TRUE if rules are useful for the user of this tree
Gets the column searched on by the interactive search code.
the column the interactive search code searches in.
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.
Returns the compare function currently in use.
the currently used compare function for the search code.
Returns the positioning function currently in use.
the currently used function for positioning the search dialog.
Gets the #GtkTreeSelection associated with @tree_view.
A #GtkTreeSelection object.
Returns whether or not expanders are drawn in @tree_view.
otherwise.
%TRUE if expanders are drawn in @tree_view, %FALSE
Returns the column of @tree_view's model which is being used for
displaying tooltips on @tree_view's rows.
used, or -1 if this is disabled.
the index of the tooltip column that is currently being
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
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.
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.
if none is currently being used.
A #GtkAdjustment object, 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.
The paths should be freed with gtk_tree_path_free() after use.
%TRUE, if valid paths were placed in @start_path and @end_path.
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.
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.
The #GtkTreeViewColumn to be inserted.
The position to insert @column in.
Creates a new #GtkTreeViewColumn and inserts it into the @tree_view 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.
The position to insert the new column in.
The title to set the header to.
The #GtkCellRenderer.
Convenience function that inserts a new column into the #GtkTreeView
with the given cell renderer and a #GtkCellDataFunc 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
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 <literal>event->window == gtk_tree_view_get_bin_window (<!-- -->)</literal>.
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.
%FALSE otherwise.
%TRUE if the area at the given coordinates is blank,
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.
done in @tree_view.
%TRUE if a rubber banding operation is currently being
Calls @func on all expanded rows.
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
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.
The #GtkTreeViewColumn to remove.
Activates the cell determined by @path and @column.
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 #GtkTreePath to test expansion state.
Moves the alignments of @tree_view to the position specified by @column and
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.
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.
X coordinate of new top-left pixel of visible area, or -1
Y coordinate of new top-left pixel of visible area, or -1
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
dragged, the two #GtkTreeViewColumn s determining the drop spot, and
are %NULL, then they indicate an edge. If @func is set to be %NULL, then
dropped everywhere.
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
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 #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
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
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 #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.
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.
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.
%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.
%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.
%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.
%TRUE to enable fixed height mode
Sets which grid lines to draw in @tree_view.
a #GtkTreeViewGridLines value indicating which grid lines to enable.
Sets the #GtkAdjustment for the current horizontal aspect.
The #GtkAdjustment to set, or %NULL
Allow the column title buttons to be clicked.
%TRUE if the columns are clickable.
Sets the visibility state of the headers.
%TRUE if the headers are visible
Enables of disables the hover expansion mode of @tree_view.
Hover expansion makes rows expand or collapse if the pointer
moves over them.
%TRUE to enable hover selection mode
Enables of 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.
%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.
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.
The model.
This function is a convenience function to allow you to reorder
models that support the #GtkDragSourceIface and the
#GtkDragDestIface. 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 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.
%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 #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.
%TRUE to enable rubber banding
This function tells GTK+ that the user interface for your
application requires users to read across tree rows and associate
cells with one another. By default, GTK+ will then render the tree
with alternating row colors. Do <emphasis>not</emphasis> 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 <emphasis>semantic</emphasis>
hint to the theme engine that your tree makes alternating colors
useful from a functional standpoint (since it has lots of columns,
generally).
%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.
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
in our interface at all time at a fixed position. Passing %NULL for
entry again.
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.
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.
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
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.
%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 #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
Note that the signal handler sets the text with gtk_tooltip_set_markup(),
so &, <, etc have to be escaped in the text.
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 #GtkTooltip
a #GtkTreePath
Sets the #GtkAdjustment for the current vertical aspect.
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.
Undoes the effect of
gtk_tree_view_enable_model_drag_source(). Calling this method sets
#GtkTreeView:reorderable to %FALSE.
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.
%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 "row-activated" signal is emitted when the method
gtk_tree_view_row_activated() is called or the user double clicks
a treeview row. It is also emitted when a non-editable row is
Enter is pressed.
For selection handling refer to the <link linkend="TreeWidget">tree
widget conceptual overview</link> 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
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 <link linkend="TreeWidget">tree widget conceptual overview</link>
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:
|[
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.
Emits the "clicked" signal on the column. This function will only work if
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.
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 #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.
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
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.
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.
Clears all existing attributes previously set with
gtk_tree_view_column_set_attributes().
a #GtkCellRenderer to clear the attribute mapping on.
Emits the "clicked" signal on the column. This function will only work if
Sets the current keyboard focus to be at @cell, if the column contains
2 or more editable and activatable cells.
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.
Returns the button used in the treeview column header
The button for the column header.
Returns %TRUE if the user can click on the header for the column.
%TRUE if user can click the column header.
Return %TRUE if the column expands to take any available space.
%TRUE, if the column expands
Gets the fixed width of the column. This value is only meaning may not be
the actual width of the column on the screen, just what is requested.
the fixed width of the column
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.
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.
Returns %TRUE if the @tree_column can be reordered by the user.
%TRUE if the @tree_column can be reordered by the user.
Returns %TRUE if the @tree_column can be resized by the end user.
%TRUE, if the @tree_column can be resized.
Returns the current type of @tree_column.
The type of @tree_column.
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().
this column can't be used for sorting.
the current @sort_column_id for this column, or -1 if
Gets the value set by gtk_tree_view_column_set_sort_indicator().
whether the sort indicator arrow is displayed
Gets the value set by gtk_tree_view_column_set_sort_order().
the sort order the sort indicator is indicating
Returns the spacing of @tree_column.
the spacing of @tree_column.
Returns the title of the widget.
modified or freed.
the title of the column. This string should not be
Returns the #GtkTreeView wherein @tree_column has been inserted.
If @column is currently not inserted in any tree view, %NULL is
returned.
been inserted if any, %NULL otherwise.
The tree view wherein @column has
Returns %TRUE if @tree_column is visible.
the tree will show the column.
whether the column is visible or not. If it is visible, then
Returns the #GtkWidget in the button on the column header.
If a custom widget has not been set then %NULL is returned.
header, or %NULL
The #GtkWidget in the column
Returns the current size of @tree_column in pixels.
The current width of @tree_column.
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.
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.
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.
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.
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.
the #GtkCellRenderer we're setting the attributes of
Sets the #GtkTreeViewColumnFunc 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 #GtkCellRenderer
The #GtkTreeViewColumnFunc to use.
The user data for @func.
The destroy notification for @func_data
Sets the header to be active if @active is %TRUE. When the header is active,
then it can take keyboard focus, and can be clicked.
%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.
%TRUE if the column should take available extra space, %FALSE if not
Sets the size of the column in pixels. This is meaningful only if the sizing
type is #GTK_TREE_VIEW_COLUMN_FIXED. The size of the column is clamped to
the min/max width for the column. Please note that the min/max width of the
column doesn't actually affect the "fixed_width" property of the widget, just
the actual size when displayed.
The size to set @tree_column to. Must be greater than 0.
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.
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.
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.
%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.
%TRUE, if the column can be resized
Sets the growth behavior of @tree_column to @type.
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.
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.
%TRUE to display an indicator that the column is sorted
Changes the appearance of the sort indicator.
This <emphasis>does not</emphasis> 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() 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().
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.
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.
The title of the @tree_column.
Sets the visibility of @tree_column.
%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 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.
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.
An enum for determining where a dropped row goes.
Used to indicate which grid lines to draw in a tree view.
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()
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.
or %NULL if no widget was found.
the action whose proxy widget is found by following the path,
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 itmanager.
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.
was found.
the widget found by following the path, or %NULL if no widget
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
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.
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 <link linkend="XML-UI">UI definition</link> and
merges it with the current contents of @manager.
to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred,
the return value is 0.
The merge id for the merged UI. The merge id can be used
the name of the file to parse
Parses a string containing a <link linkend="XML-UI">UI definition</link> and
merges it with the current contents of @manager. An enclosing <ui>
element is added if it is missing.
to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred,
the return value is 0.
The merge id for the merged UI. The merge id can be used
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:
|[
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);
]|
Returns the #GtkAccelGroup associated with @manager.
the #GtkAccelGroup.
Looks up an action by following a path. See gtk_ui_manager_get_widget()
for more information about paths.
or %NULL if no widget was found.
the action whose proxy widget is found by following the path,
a path
Returns the list of action groups associated with @manager.
action groups. The list is owned by GTK+
and should not be modified.
a #GList of
Returns whether menus generated by this #GtkUIManager
will have tearoff menu items.
whether tearoff menu items are added
Obtains a list of all toplevel widgets of the requested types.
all toplevel widgets of the requested types. Free the returned list with g_slist_free().
a newly-allocated #GSList of
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 <link linkend="XML-UI">UI definition</link> of the merged UI.
the merged UI.
A newly allocated string containing an XML representation of
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 itmanager.
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.
was found.
the widget found by following the path, or %NULL if no widget
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.
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.
Removes an action group from the list of action groups associated
with @manager.
the action group to be removed
Unmerges the part of @manager<!-- -->s content identified by @merge_id.
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.
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.
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
a path
the action whose proxy widget is found by following the path,
a path
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.
Creates a new #GtkVBox.
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.
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.
Create a new #GtkVPaned
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.
Creates a new #GtkVScale.
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.
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.
Creates a new vertical scrollbar.
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.
Creates a new #GtkVSeparator.
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
#GtkTable, #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.
The convenience function gtk_scrolled_window_add_with_viewport() does
exactly this, 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.
Creates a new #GtkViewport with the given adjustments.
a new #GtkViewport.
horizontal adjustment.
vertical adjustment.
Gets the bin window of the #GtkViewport.
a #GdkWindow
Returns the horizontal adjustment of the viewport.
the horizontal adjustment of @viewport.
Gets the shadow type of the #GtkViewport. See
gtk_viewport_set_shadow_type().
the shadow type
Returns the vertical adjustment of the viewport.
the vertical adjustment of @viewport.
Gets the view window of the #GtkViewport.
a #GdkWindow
Sets the horizontal adjustment of the viewport.
a #GtkAdjustment.
Sets the shadow type of the viewport.
the new shadow type.
Sets the vertical adjustment of the viewport.
a #GtkAdjustment.
#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.
<refsect2 id="geometry-management">
<title>Height-for-width Geometry Management</title>
<para>
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:
<itemizedlist>
<listitem>#GtkWidgetClass.get_request_mode()</listitem>
<listitem>#GtkWidgetClass.get_preferred_width()</listitem>
<listitem>#GtkWidgetClass.get_preferred_height()</listitem>
<listitem>#GtkWidgetClass.get_preferred_height_for_width()</listitem>
<listitem>#GtkWidgetClass.get_preferred_width_for_height()</listitem>
</itemizedlist>
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 <link linkend="container-geometry-management">GtkContainer's
geometry management section</link>
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:
<programlisting><![CDATA[
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;
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
{
... 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.
}
}
]]></programlisting>
And in #GtkWidgetClass.get_preferred_width_for_height() it will simply return
the minimum and natural width:
<programlisting><![CDATA[
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.
}
}
]]></programlisting>
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:
<example>
<title>Widget calling its own size request method.</title>
<programlisting>
GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget),
&min, &natural);
</programlisting>
</example>
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
<emphasis>another</emphasis> widget, such as a child of a
container, you <emphasis>must</emphasis> use the wrapper APIs.
Otherwise, you would not properly consider widget margins,
#GtkSizeGroup, and so forth.
</para>
</refsect2>
<refsect2 id="style-properties">
<title>Style Properties</title>
<para>
<structname>GtkWidget</structname> introduces <firstterm>style
properties</firstterm> - 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 <link linkend="gtk-Resource-Files">resource files</link>.
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.
</para>
<para>
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.
</para>
</refsect2>
<refsect2 id="GtkWidget-BUILDER-UI">
<title>GtkWidget as GtkBuildable</title>
<para>
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.
</para>
<example>
<title>A UI definition fragment specifying an accelerator</title>
<programlisting><![CDATA[
<object class="GtkButton">
<accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/>
</object>
]]></programlisting>
</example>
<para>
In addition to accelerators, <structname>GtkWidget</structname> 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 <structname>GtkWidget</structname>.
</para>
<example>
<title>A UI definition fragment specifying an accessible</title>
<programlisting><![CDATA[
<object class="GtkButton" 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="AtkObject::name">Clickable Button</property>
</object>
</child>
</object>
]]></programlisting>
</example>
<para>
Finally, GtkWidget allows style information such as style classes to
be associated with widgets, using the custom <style> element:
<example>
<title>A UI definition fragment specifying an style class</title>
<programlisting><![CDATA[
<object class="GtkButton" id="button1">
<style>
<class name="my-special-button-class"/>
<class name="dark-button"/>
</style>
</object>
]]></programlisting>
</example>
</para>
</refsect2>
This is a convenience function for creating a widget and setting
its properties in one go. For example you might write:
<literal>gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign",
0.0, NULL)</literal> 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
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.
object is owned by GTK+ and should not be modified or freed.
gtk_css_provider_get_default() to obtain a #GtkStyleProvider
with the default widget style information.
the default style. This #GtkStyle
Cancels the effect of a previous call to gtk_widget_push_composite_child().
Makes all newly-created widgets as composite children until
the corresponding gtk_widget_pop_composite_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.
Here is a simple example:
|[
gtk_widget_push_composite_child ();
scrolled_window->hscrollbar = gtk_scrollbar_new (GTK_ORIENTATION_HORIZONTAL, hadjustment);
gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
gtk_widget_pop_composite_child ();
gtk_widget_set_parent (scrolled_window->hscrollbar,
GTK_WIDGET (scrolled_window));
g_object_ref (scrolled_window->hscrollbar);
]|
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.
the ID of a signal installed on @widget
Emits a #GtkWidget::child-notify signal for the
<link linkend="child-properties">child property</link> @child_property
on @widget.
This is the analogue of g_object_notify() for child properties.
Destroys a widget.
When a widget is
destroyed, it will break any references it holds to other objects.
If the widget is inside a container, the widget will be removed
from the container. If the widget is a toplevel (derived from
#GtkWindow), it will be removed from the list of toplevels, and the
reference GTK+ holds to it will be removed. Removing a
widget from its container or the list of toplevels results in the
widget being finalized, unless you've added additional references
to the widget with g_object_ref().
In most cases, only toplevel widgets (windows) require explicit
destruction, because when you destroy a toplevel its children will
be destroyed as well.
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.
the event was handled)
return from the event signal emission (%TRUE if
a #GdkEvent
Returns the accessible object that describes the widget to an
assistive technology.
If no accessibility library is loaded (i.e. no ATK implementation library is
loaded via <envar>GTK_MODULES</envar> or via another application library,
such as libgnome), then 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
<ulink url="http://library.gnome.org/devel/atk/stable/">ATK</ulink>
library contains more information about accessible objects and their uses.
the #AtkObject associated with @widget
Retrieves a widget's initial minimum and natural height.
<note><para>This call is specific to width-for-height requests.</para></note>
The returned request will be modified by the
GtkWidgetClass::adjust_size_request virtual method and by any
#GtkSizeGroup<!-- -->s 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.
location to store the minimum height, or %NULL
location to store 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
#GtkSizeGroup<!-- -->s 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.
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.
<note><para>This call is specific to height-for-width
requests.</para></note>
The returned request will be modified by the
GtkWidgetClass::adjust_size_request virtual method and by any
#GtkSizeGroup<!-- -->s 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.
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
#GtkSizeGroup<!-- -->s 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.
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.
<note><para>#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.</para></note>
The #GtkSizeRequestMode preferred by @widget.
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.
Reverses the effects of gtk_widget_show(), causing the widget to be
hidden (invisible to the user).
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 %TRUE for
%GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other
values of #GtkDirectionType, it looks at the
#GtkSettings:gtk-keynav-cursor-only setting and returns %FALSE
if the setting is %TRUE. This way the entire user interface
becomes cursor-navigatable on input devices such as mobile phones
which only have cursor keys but no tab key.
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.
if the emitting widget should try to handle the keyboard
navigation attempt in its parent container(s).
%TRUE if stopping keyboard navigation is fine, %FALSE
direction of focus movement
This function is only for use in widget implementations. Causes
a widget to be mapped if it isn't already.
Emits the #GtkWidget::mnemonic-activate signal.
The default handler for this signal activates the @widget if
is %TRUE.
%TRUE if the signal has been handled
%TRUE if there are other widgets with the same mnemonic
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
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.
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.
Recursively shows a widget, and any child widgets (if the widget is
a container).
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.
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.
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).
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
Installs an accelerator for this @widget in @accel_group that causes
The @accel_group needs to be added to the widget's toplevel via
gtk_window_add_accel_group(), and the signal must be of type %G_RUN_ACTION.
Accelerators added through this function are not user changeable during
runtime. If you want to support accelerators that can be changed by the
user, use gtk_accel_map_add_entry() and gtk_widget_set_accel_path() or
gtk_menu_item_set_accel_path() instead.
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
a #GdkDevice
an event mask, see #GdkEventMask
Adds the events in the bitfield @events to the event mask for
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 that acts as a mnemonic label for @widget
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.
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
direction of focus movement
Emits a #GtkWidget::child-notify signal for the
<link linkend="child-properties">child property</link> @child_property
on @widget.
This is the analogue of g_object_notify() for child properties.
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().
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
expand direction
Creates a new #PangoContext with the appropriate font map,
font description, and base direction for drawing text for
this widget. See also gtk_widget_get_pango_context().
the new #PangoContext
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, in order to
notify the layout of changes to the base direction or font of this
widget, you must call pango_layout_context_changed() in response to
the #GtkWidget::style-updated and #GtkWidget::direction-changed signals
for the widget.
the new #PangoLayout
text to set on the layout (can be %NULL)
Destroys a widget.
When a widget is
destroyed, it will break any references it holds to other objects.
If the widget is inside a container, the widget will be removed
from the container. If the widget is a toplevel (derived from
#GtkWindow), it will be removed from the list of toplevels, and the
reference GTK+ holds to it will be removed. Removing a
widget from its container or the list of toplevels results in the
widget being finalized, unless you've added additional references
to the widget with g_object_ref().
In most cases, only toplevel widgets (windows) require explicit
destruction, because when you destroy a toplevel its children will
be destroyed as well.
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.
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().
by another #GtkWidget than @widget.
%TRUE if there is an ongoing grab on @device
a #GdkDevice
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 by GTK+ to get information about the start position of the drag, for
example if the @event is a GDK_MOTION_NOTIFY.
Generally there are three cases when you want to start a drag by hand by
calling this function:
1. During a 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 button-press-event handler.
2. During a 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 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 can really not pass a real event, pass #NULL instead.
the context for this drag.
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.
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.
X coordinate of start of drag
Y coordinate of start of drag
current X coordinate
current Y coordinate
Add the image targets supported by #GtkSelection 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().
Add the text targets supported by #GtkSelection 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().
Add the URI targets supported by #GtkSelection 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().
Looks for a match between the supported targets of @context and the
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.
and the dest can accept, or %GDK_NONE
first target that the source offers
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
Returns whether the widget has been configured to always
emit ::drag-motion signals.
%TRUE if the widget always emits ::drag-motion events
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:
|[
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);
}
]|
which types of default drag behavior to use
a pointer to an array of #GtkTargetEntry<!-- -->s 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.
Set up this widget to proxy drags elsewhere.
window to which forward drag events
Drag protocol which the dest widget accepts
If true, send the same coordinates to the destination, because it is a 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().
list of droppable targets, or %NULL for none
Tells the widget to emit ::drag-motion and ::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.
whether to accept all targets
Unregister this widget as a drag target.
Get the data for a drag or drop
drag context
format to retrieve the data in.
timestamp of triggering event.
Highlight the given widget in the default manner.
Add the writable image targets supported by #GtkSelection 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().
Add the text targets supported by #GtkSelection 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().
Add the URI targets supported by #GtkSelection 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().
Gets the list of targets this widget can provide for
drag-and-drop.
the #GtkTargetList, or %NULL if none
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.
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 a themed icon. See the docs for #GtkIconTheme for more details.
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.
the #GdkPixbuf for the drag icon
Sets the icon that will be used for drags from a particular source
to a stock icon.
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().
list of draggable targets, or %NULL for none
Unregister this widget as a drag source.
Refresh the given widget to remove the highlight.
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><para>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().</para></note>
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.
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.
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.
the event was handled)
return from the event signal emission (%TRUE if
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.
Returns the accessible object that describes the widget to an
assistive technology.
If no accessibility library is loaded (i.e. no ATK implementation library is
loaded via <envar>GTK_MODULES</envar> or via another application library,
such as libgnome), then 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
<ulink url="http://library.gnome.org/devel/atk/stable/">ATK</ulink>
library contains more information about accessible objects and their uses.
the #AtkObject associated with @widget
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
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
Retrieves the widget's allocation.
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 pointer to a #GtkAllocation to copy to
Gets the first ancestor of @widget with type @widget_type. For example,
<literal>gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)</literal> 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
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
Determines whether @widget can be a default widget. See
gtk_widget_set_can_default().
%TRUE if @widget can be a default widget, %FALSE otherwise
Determines whether @widget can own the input focus. See
gtk_widget_set_can_focus().
%TRUE if @widget can own the input focus, %FALSE otherwise
This function is only for use in widget implementations. Obtains
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().
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.
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.
clipboard already exists, a new one will
be created. Once a clipboard object has
been created, it is persistent for all time.
the appropriate clipboard object. If no
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.
a composite child. The string should be freed when it is no
longer needed.
the composite name of @widget, or %NULL if @widget is not
Returns whether @device can interact with @widget and its
children. See gtk_widget_set_device_enabled().
%TRUE is @device is enabled for @widget
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 #GdkDevice
Gets the reading direction for a particular widget. See
gtk_widget_set_direction().
the reading direction for the widget.
Get the #GdkDisplay for the toplevel window associated with
this widget. This function can only be called after the widget
has been added to a widget hierarchy with a #GtkWindow at the top.
In general, you should only create display specific
resources when a widget has been realized, and you should
free those resources when the widget is unrealized.
the #GdkDisplay for the toplevel for this widget.
Determines whether the widget is double buffered.
See gtk_widget_set_double_buffered()
%TRUE if the widget is double buffered
Returns the event mask for the widget (a bitfield containing flags
from the #GdkEventMask enumeration). These are the events that the widget
will receive.
event mask for @widget
Gets the value of the #GtkWidget:halign property.
the horizontal alignment of @widget
Returns the current value of the has-tooltip property. See
#GtkWidget:has-tooltip for more information.
current value of has-tooltip on @widget.
Determines whether @widget has a #GdkWindow of its own. See
gtk_widget_set_has_window().
%TRUE if @widget has a window, %FALSE otherwise
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
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
Whether the widget is mapped.
%TRUE if the widget is mapped, %FALSE otherwise.
Gets the value of the #GtkWidget:margin-bottom property.
The bottom margin of @widget
Gets the value of the #GtkWidget:margin-left property.
The left margin of @widget
Gets the value of the #GtkWidget:margin-right property.
The left margin of @widget
Gets the value of the #GtkWidget:margin-top property.
The top margin of @widget
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.
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.
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().
the modifier style for the widget.
Retrieves the name of a widget. See gtk_widget_set_name() for the
significance of widget names.
should not be modified or freed
name of the widget. This string is owned by GTK+ and
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.
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.
If you create and keep a #PangoLayout using this context, you must
deal with changes to the context by calling pango_layout_context_changed()
on the layout in response to the #GtkWidget::style-updated and
#GtkWidget::direction-changed signals for the widget.
the #PangoContext for the widget.
Returns the parent container of @widget.
the parent container of @widget, or %NULL
Gets @widget's parent window.
the parent window of @widget.
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
Obtains the location of the mouse pointer in widget coordinates.
Widget coordinates are a bit odd; for historical reasons, they are
defined as @widget->window coordinates for widgets that are not
#GTK_NO_WINDOW widgets, and are relative to @widget->allocation.x,
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.
<note><para>This call is specific to width-for-height requests.</para></note>
The returned request will be modified by the
GtkWidgetClass::adjust_size_request virtual method and by any
#GtkSizeGroup<!-- -->s 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.
location to store the minimum height, or %NULL
location to store 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
#GtkSizeGroup<!-- -->s 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.
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.
<note><para>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.</para></note>
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.
<note><para>This call is specific to height-for-width
requests.</para></note>
The returned request will be modified by the
GtkWidgetClass::adjust_size_request virtual method and by any
#GtkSizeGroup<!-- -->s 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.
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
#GtkSizeGroup<!-- -->s 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.
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
Determines whether @widget is alyways treated as default widget
withing its toplevel when it has the focus, even if another widget
is the default.
See gtk_widget_set_receives_default().
%FALSE otherwise
%TRUE if @widget acts as default widget when focussed,
Gets whether the widget prefers a height-for-width layout
or a width-for-height layout.
<note><para>#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.</para></note>
The #GtkSizeRequestMode preferred by @widget.
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.
removed, If you need to cache sizes across requests and allocations,
add an explicit cache to the widget in question instead.
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.
the #GdkWindow root window for the toplevel for this widget.
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.
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
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
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
and the natural requisition of the widget will be used intead. 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.
return location for width, or %NULL
return location for height, or %NULL
Returns the widget's state. See gtk_widget_set_state().
the state of @widget.
Returns the widget state as a flag set. It is worth mentioning
that the effective %GTK_STATE_FLAG_INSENSITIVE state will be
returned, that is, also based on parent insensitivity, even if
The state flags for widget
Simply an accessor function that returns @widget->style.
the widget's #GtkStyle
Returns the style context associated to @widget.
must not be freed.
a #GtkStyleContext. This memory is owned by @widget and
Returns %TRUE if @widget is multiple pointer aware. See
gtk_widget_set_support_multidevice() for more information.
%TRUE if @widget is multidevice aware.
Gets the contents of the tooltip for @widget.
returned string with g_free() when done.
the tooltip text, or %NULL. You should free the
Gets the contents of the tooltip for @widget.
returned string with g_free() when done.
the tooltip text, or %NULL. You should free the
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.
This function returns the topmost widget in the container hierarchy
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();
<literal>gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)</literal>
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 check if the %TOPLEVEL flags
is set on the result.
|[
GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
if (gtk_widget_is_toplevel (toplevel))
{
/* Perform action on toplevel. */
}
]|
if there's no ancestor.
the topmost ancestor of @widget, or @widget itself
Gets the value of the #GtkWidget:valign property.
the vertical alignment of @widget
Gets whether the widget would like any available extra vertical
space.
See gtk_widget_get_hexpand() for more detail.
whether vexpand flag is set
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
Determines whether the widget is visible. Note that this doesn't
take into account whether the widget's parent is also visible
or the widget is obscured in any way.
See gtk_widget_set_visible().
%TRUE if the widget is visible
Gets the visual that will be used to render @widget.
the visual for @widget
Returns the widget's window if it is realized, %NULL otherwise
@widget's window.
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.
Causes @widget to become the default widget. @widget must have the
%GTK_CAN_DEFAULT flag set; typically you have to set this flag
yourself by calling <literal>gtk_widget_set_can_default (@widget,
%TRUE)</literal>. 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.
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.
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.
Determines whether @widget is the current default widget within its
toplevel. See gtk_widget_set_can_default().
its toplevel, %FALSE otherwise
%TRUE if @widget is the current default widget within
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.
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
Determines if the widget style has been looked up through the rc mechanism.
mechanism, %FALSE otherwise.
%TRUE if the widget has been looked up through the rc
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.
with the widget.
%TRUE if there is a #GdkScreen associcated
Reverses the effects of gtk_widget_show(), causing the widget to be
hidden (invisible to the user).
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
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
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.
shape to be added, or %NULL to remove an existing shape
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 rectangle
rectangle to store intersection of @widget and @area
Determines whether @widget is somewhere inside @ancestor, possibly with
intermediate containers.
grandchild, great grandchild, etc.
%TRUE if @ancestor contains @widget as a child,
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()).
channel being drawn correctly.
%TRUE if the widget can rely on its alpha
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
Determines if the widget is the focus widget within its
toplevel. (This does not mean that the %HAS_FOCUS flag is
necessarily set; %HAS_FOCUS will only be set if the
toplevel widget additionally has the global input focus.)
%TRUE if the widget is the focus widget.
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
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
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 %TRUE for
%GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other
values of #GtkDirectionType, it looks at the
#GtkSettings:gtk-keynav-cursor-only setting and returns %FALSE
if the setting is %TRUE. This way the entire user interface
becomes cursor-navigatable on input devices such as mobile phones
which only have cursor keys but no tab key.
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.
if the emitting widget should try to handle the keyboard
navigation attempt in its parent container(s).
%TRUE if stopping keyboard navigation is fine, %FALSE
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
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
<emphasis>must</emphasis> call <literal>g_list_foreach (result,
(GFunc)g_object_ref, NULL)</literal> first, and then unref all the
widgets afterwards.
mnemonic labels; free this list
with g_list_free() when you are done with it.
the list of
This function is only for use in widget implementations. Causes
a widget to be mapped if it isn't already.
Emits the #GtkWidget::mnemonic-activate signal.
The default handler for this signal activates the @widget if
is %TRUE.
%TRUE if the signal has been handled
%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><para>
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.
</para><para>
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.
</para></note>
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><para>
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.
</para><para>
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.
</para></note>
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 #GtkWidget:secondary-cursor-color
style properties.
All other style values are left untouched.
See also gtk_widget_modify_style().
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().
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().
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 explicitely set on the widget using gtk_widget_set_style().
The #GtkRcStyle structure is designed so each field can either be
set or unset, so it is possible, using this function, to modify some
style values and leave the others unchanged.
Note that modifications made with this function are not cumulative
with previous calls to gtk_widget_modify_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.
the #GtkRcStyle 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().
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().
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.
<note><para>
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 and regions in your
widget/container implementation through gtk_style_context_add_class()
and gtk_style_context_add_region().
</para><para>
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.
</para></note>
<note><para>
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.
</para></note>
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
#GtkWidget:cursor-color and #GtkWidget: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.
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().
the font descriptiong 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.
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.
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
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().
Equivalent to calling gtk_widget_queue_draw_area() for the
entire area of a widget.
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 are not
#GTK_NO_WINDOW widgets, and are relative to @widget->allocation.x,
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 rectangular 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.
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><para>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.</para></note>
This function works like gtk_widget_queue_resize(),
except that the widget is not invalidated.
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
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.
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.
A newly allocated region holding the intersection of @widget and @region. The coordinates of the return value are relative to @widget->window for %NO_WINDOW widgets, and relative to the parent window of @widget->window for widgets with their own window.
a #cairo_region_t, in the same coordinate system as for %NO_WINDOW widgets; relative to the parent window of @widget->window for widgets with their own window.
Removes an accelerator from @widget, previously installed with
gtk_widget_add_accelerator().
whether an accelerator was installed and could be removed
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 that was previously set as a mnemnic label for
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().
stock ID wasn't known
a new pixbuf, or %NULL if the
a stock ID
a stock size. A size of (GtkIconSize)-1 means render at the size of the source and don't scale (if there are multiple source sizes, GTK+ picks one of the available sizes).
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().
stock ID wasn't known
a new pixbuf, or %NULL if the
a stock ID
a stock size. A size of (GtkIconSize)-1 means render at the size of the source and don't scale (if there are multiple source sizes, GTK+ picks one of the available sizes).
Moves a widget from one #GtkContainer to another, handling reference
count issues to avoid destroying the widget.
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.
Updates the style context of @widget and all descendents
by updating its widget path. #GtkContainer<!-- -->s 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().
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 child %NO_WINDOW widget, 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().
the event was handled)
return from the event signal emission (%TRUE if
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:
|[
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);
]|
if the event was handled, and %FALSE otherwise
the return value from the event signal emission: %TRUE
a #GdkEvent of type GDK_FOCUS_CHANGE
Given an accelerator group, @accel_group, and an accelerator path,
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().
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 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.
%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".
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.
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.
if %TRUE, @widget should be mapped along with its parent.
Sets a widgets composite name. The widget must be
a composite child of its parent; see gtk_widget_push_composite_child().
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 #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 #GTK_NO_WINDOW widgets;
to get events on those widgets, place them inside a #GtkEventBox
and receive events on the event box.
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 explicitely
visual rather than logical (such as buttons for text justification).
If the direction is set to %GTK_TEXT_DIR_NONE, then the value
set by gtk_widget_set_default_direction() will be used.
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_paint_region() and gdk_window_end_paint() are called
automatically around expose events sent to the
widget. gdk_window_begin_paint() diverts all drawing to a widget's
window to an offscreen buffer, and gdk_window_end_paint() 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.
expose events, since even the clearing to the background color or
pixmap will not happen automatically (as it is done in
gdk_window_begin_paint()).
%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 #GTK_NO_WINDOW widgets;
to get events on those widgets, place them inside a #GtkEventBox
and receive events on the event box.
event mask
Sets the horizontal alignment of @widget.
See the #GtkWidget:halign property.
the horizontal alignment
Sets the has-tooltip property on @widget to @has_tooltip. See
#GtkWidget:has-tooltip for more information.
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.
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.
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.
value for hexpand-set property
Marks the widget as being realized.
This function should only ever be called in a derived widget's
"map" or "unmap" implementation.
%TRUE to mark the widget as mapped
Sets the bottom margin of @widget.
See the #GtkWidget:margin-bottom property.
the bottom margin
Sets the left margin of @widget.
See the #GtkWidget:margin-left property.
the left margin
Sets the right margin of @widget.
See the #GtkWidget:margin-right property.
the right margin
Sets the top margin of @widget.
See the #GtkWidget:margin-top property.
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.
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.
the new value for the "no-show-all" property
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().
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.
<note><para>
For GtkWindow classes, this needs to be called before the
window is realized.
</para></note>
the new parent window.
Marks the widget as being realized.
This function should only ever be called in a derived widget's
"realize" or "unrealize" implementation.
%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".
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 %NO_WINDOW widgets setting this flag to %FALSE turns
its position changes; this is to allow containers that don't draw
anything to avoid excess invalidations. If you set this flag on a
%NO_WINDOW widget that <emphasis>does</emphasis> 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.
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.
%TRUE to make the widget sensitive
Sets the minimum size of a widget; that is, the widget's size
request will be @width by @height. You can use this function to
force a widget to be either larger or smaller than it normally
would be.
In most cases, gtk_window_set_default_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.
Widgets can't actually be allocated a size less than 1 by 1, but
you can pass 0,0 to this function to mean "as small as possible."
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.
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().
new state for @widget
This function is for use in widget implementations. Turns on flag
values in the current widget state (insensitive, prelighted, etc.).
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.
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.
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,
that if custom #GdkWindow<!-- -->s are created in #GtkWidget::realize,
gdk_window_set_support_multidevice() will have to be called manually on them.
%TRUE to support input from multiple devices.
Sets @markup as the contents of the tooltip, which is marked up with
the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
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().
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().
the contents of the tooltip for @widget
Replaces the default, usually yellow, 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.
If the custom window should have the default theming it needs to
have the name "gtk-tooltip", see gtk_widget_set_name().
a #GtkWindow, or %NULL
Sets the vertical alignment of @widget.
See the #GtkWidget:valign property.
the vertical alignment
Sets whether the widget would like any available extra vertical
space.
See gtk_widget_set_hexpand() for more detail.
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.
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.
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 gdk_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.
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><para>This function does not add any reference to @window.</para></note>
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.
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.
Recursively shows a widget, and any child widgets (if the widget is
a container).
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.
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.
position and size to be allocated to @widget
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.
a #GtkRequisition to be filled in
This function attaches the widget's #GtkStyle to the widget's
#GdkWindow. It is a replacement for
<programlisting>
widget->style = gtk_style_attach (widget->style, widget->window);
</programlisting>
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.
Gets the values of a multiple style properties of @widget.
the name of the first property to get
Gets the value of a style property of @widget.
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.
the name of the first property to get
a <type>va_list</type> 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.
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.
was no common ancestor. In this case, nothing is stored in
*@dest_x and *@dest_y. Otherwise %TRUE.
%FALSE if either widget was not realized, or there
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.
This function is only for use in widget implementations. Causes
a widget to be unmapped if it's currently mapped.
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.
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).
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().
State flags to turn off
Whether the widget is double buffered.
Whether to expand in both directions. Setting this sets both #GtkWidget:hexpand and #GtkWidget:vexpand
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 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.
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.
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.
Sets the text of tooltip to be the given string, which is marked up
with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
Also see gtk_tooltip_set_markup().
This is a convenience property which will take care of getting the
will automatically be set to %TRUE and there will be taken care of
#GtkWidget::query-tooltip in the default signal handler.
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
will automatically be set to %TRUE and there will be taken care of
#GtkWidget::query-tooltip in the default signal handler.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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
<link linkend="child-properties">child property</link> 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 @widget<!-- -->s screen changes.
See gdk_screen_is_composited().
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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 gtk_drag_source_set_icon().
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 <emphasis>not</emphasis> 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.
The handler may inspect and modify @drag_context->action before calling
gtk_drag_finish(), e.g. to implement %GDK_ACTION_ASK as shown in the
following example:
|[
void
drag_data_received (GtkWidget *widget,
GdkDragContext *drag_context,
gint x,
gint y,
GtkSelectionData *data,
guint info,
guint time)
{
if ((data->length >= 0) && (data->format == 8))
{
if (drag_context->action == GDK_ACTION_ASK)
{
GtkWidget *dialog;
gint response;
dialog = gtk_message_dialog_new (NULL,
GTK_DIALOG_MODAL |
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_MESSAGE_INFO,
GTK_BUTTONS_YES_NO,
"Move the data ?\n");
response = gtk_dialog_run (GTK_DIALOG (dialog));
gtk_widget_destroy (dialog);
if (response == GTK_RESPONSE_YES)
drag_context->action = GDK_ACTION_MOVE;
else
drag_context->action = GDK_ACTION_COPY;
}
gtk_drag_finish (drag_context, TRUE, FALSE, time);
return;
}
gtk_drag_finish (drag_context, FALSE, FALSE, time);
}
]|
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()
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 cannot not 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().
|[
static void
drag_motion (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
guint time)
{
GdkAtom target;
PrivateData *private_data = GET_PRIVATE_DATA (widget);
if (!private_data->drag_highlight)
{
private_data->drag_highlight = 1;
gtk_drag_highlight (widget);
}
target = gtk_drag_dest_find_target (widget, context, NULL);
if (target == GDK_NONE)
gdk_drag_status (context, 0, time);
else
{
private_data->pending_status = context->suggested_action;
gtk_drag_get_data (widget, context, target, time);
}
return TRUE;
}
static void
drag_data_received (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
GtkSelectionData *selection_data,
guint info,
guint time)
{
PrivateData *private_data = GET_PRIVATE_DATA (widget);
if (private_data->suggested_action)
{
private_data->suggested_action = 0;
/* We are getting this data due to a request in drag_motion,
* rather than due to a request in drag_drop, so we are just
* supposed to call gdk_drag_status (), not actually paste in
* the data.
*/
str = gtk_selection_data_get_text (selection_data);
if (!data_is_acceptable (str))
gdk_drag_status (context, 0, time);
else
gdk_drag_status (context, private_data->suggested_action, time);
}
else
{
/* accept the drop */
}
}
]|
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 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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventCrossing which triggered this signal.
The GTK+ main loop will emit three signals for each GDK event delivered
signal that matches the type of event delivered (e.g.
#GtkWidget::key-press-event) and finally a generic
#GtkWidget::event-after signal.
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.
%TRUE to stop other handlers from being invoked for the event
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.
%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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
the event. %FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for
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 ::hierarchy-changed signal is emitted when the
anchored state of a widget changes. A widget is
<firstterm>anchored</firstterm> 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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventKey which triggered this signal.
Gets emitted if keyboard navigation fails.
See gtk_widget_keynav_failed() for details.
if the emitting widget should try to handle the keyboard
navigation attempt in its parent container(s).
%TRUE if stopping keyboard navigation is fine, %FALSE
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventCrossing which triggered this signal.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventAny which triggered this signal.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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 <xref linkend="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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventProximity which triggered this signal.
Emitted when #GtkWidget:has-tooltip is %TRUE and the #GtkSettings:gtk-tooltip-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
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->window
the y coordinate of the cursor position where the request has been emitted, relative to @widget->window
%TRUE if the tooltip was trigged using the keyboard
a #GtkTooltip
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_BUTTON_PRESS_MASK mask.
This signal will be sent to the grab widget if there is one.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventSelection which triggered this signal.
The ::state-changed signal is emitted when the widget state changes.
See gtk_widget_get_state().
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.
the previous style, or %NULL if the widget just got its initial style
The ::style-updated signal is emitted when the #GtkStyleContext
of a widget is changed. Note that style-modifying functions like
gtk_widget_override_color() also cause this signal to be emitted.
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
the #GdkEventAny which triggered this signal
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.
%FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the event.
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.
event. %FALSE to propagate the event further.
%TRUE to stop other handlers from being invoked for the
the #GdkEventWindowState which triggered this signal.
position and size to be allocated to @widget
The #GtkSizeRequestMode preferred by @widget.
location to store the minimum height, or %NULL
location to store the natural height, or %NULL
the height which is available for allocation
location for storing the minimum width, or %NULL
location for storing the natural width, or %NULL
location to store the minimum width, or %NULL
location to store the natural width, or %NULL
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
%TRUE if there are other widgets with the same mnemonic
%TRUE if stopping keyboard navigation is fine, %FALSE
direction of focus movement
return from the event signal emission (%TRUE if
a #GdkEvent
the #AtkObject associated with @widget
%TRUE if the accelerator can be activated.
the ID of a signal installed on @widget
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.
the name of the style property to find
Installs a style property on a widget class. The parser for the
style property is determined by the value type of @pspec.
the #GParamSpec for the property
Installs a style property on a widget class.
the #GParamSpec for the style property
the parser for the style property
Returns all style properties of a widget class.
an newly allocated array of #GParamSpec*. The array must be freed with g_free().
location to return the number of style properties found
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:
<example>
<title>Defining a button within a window</title>
<programlisting>
{
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);
}
</programlisting>
</example>
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:
<example>
<title>Defining the first tab widget in a notebook</title>
<programlisting>
{
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");
}
</programlisting>
</example>
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 a widget type to the widget hierachy represented by @path.
the position where the element was inserted
widget type to append
Returns a copy of @path
a copy of @path
Frees a #GtkWidgetPath.
Returns the topmost object type, that is, the object type this path
is representing.
The object type
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
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
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().
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().
<note><para>Region names must only contain lowercase letters
and '-', starting always with a lowercase letter.</para></note>
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.
position to modify, -1 for the path head
Removes all regions from the widget at position @pos in the
hierarchy defined in @path.
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
The widget name, or %NULL if none was set.
position to get the widget 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
position to get the object type 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
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
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 GQuark<!-- -->s.
%TRUE if the widget at @pos has the class defined.
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 #GQuark<!-- -->s.
%TRUE if the widget at @pos has this name
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 GQuark<!-- -->s.
%TRUE if the widget at @pos has the region defined.
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.
%TRUE if the class @name is defined for the widget at @pos
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.
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.
The list of
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.
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.
The list of
position to query, -1 for the path head
Removes the class @name from the widget at position @pos in
the hierarchy defined in @path.
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.
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.
position to modify, -1 for the path head
widget name
Sets the object type for a given position in the widget hierarchy
defined by @path.
position to modify, -1 for the path head
object type to set
Returns the number of #GtkWidget #GTypes between the represented
widget and its topmost container.
the number of elements in the path
Prepends a widget type to the widget hierachy represented by @path.
widget type to prepend
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,...).
GTK+ also allows windows to have a resize grip (a small area in the lower
right or left corner) which can be clicked to reszie the window. To
control whether a window has a resize grip, use
gtk_window_set_has_resize_grip().
<refsect2 id="GtkWindow-BUILDER-UI">
<title>GtkWindow as GtkBuildable</title>
<para>
The GtkWindow implementation of the GtkBuildable interface supports a
custom <tag class="starttag">accel-groups</tag> element, which supports
any number of <tag class="starttag">group</tag> elements representing the
#GtkAccelGroup objects you want to add to your window (synonymous with
gtk_window_add_accel_group().
</para>
<example>
<title>A UI definition fragment with accel groups</title>
<programlisting><![CDATA[
<object class="GtkWindow">
<accel-groups>
<group name="accelgroup1"/>
</accel-groups>
</object>
<!-- -->
...
<!-- -->
<object class="GtkAccelGroup" id="accelgroup1"/>
]]></programlisting>
</example>
</refsect2>
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 <link
linkend="gtk-X11-arch">window manager</link>.
If you simply want an undecorated window (no window borders), use
gtk_window_set_decorated(), don't use #GTK_WINDOW_POPUP.
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 <emphasis>must</emphasis> call
<literal>g_list_foreach (result, (GFunc)g_object_ref, NULL)</literal> 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
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.
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.
Activates the current focused widget within the window.
%TRUE if a widget got activated.
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 #GdkEventKey
Associate @accel_group with @window, such that calling
gtk_accel_groups_activate() on @window will activate accelerators
in @accel_group.
a #GtkAccelGroup
Adds a mnemonic to this window.
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 <link
linkend="gtk-X11-arch">window manager</link> or windowing
system. Otherwise, GDK will try to emulate window movement,
potentially not all that well, depending on the windowing system.
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 <link
linkend="gtk-X11-arch">window manager</link> or windowing
system. Otherwise, GDK will try to emulate window resizing,
potentially not all that well, depending on the windowing system.
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
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 <link
linkend="gtk-X11-arch">window manager</link>) 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.
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 <link
linkend="gtk-X11-arch">window manager</link>) 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.
Gets the value set by gtk_window_set_accept_focus().
%TRUE if window should receive the input focus
Gets the #GtkApplication associated with the window (if any).
a #GtkApplication, or %NULL
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
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.
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.
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
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.
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 <literal>gtk_widget_has_focus (widget)</literal> will
not be %TRUE for the widget.
the currently focused widget, or %NULL if there is none.
Gets the value set by gtk_window_set_focus_on_map().
mapped.
%TRUE if window should receive the input focus when
Gets the value set by gtk_window_set_gravity().
window gravity
Returns the group for @window or the default group, if
window group.
the #GtkWindowGroup for a window or the default group
Determines whether the window may have a resize grip.
%TRUE if the window has a resize grip
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
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
Returns the name of the themed icon for the window,
see gtk_window_set_icon_name().
no themed icon
the icon name or %NULL if the window has
Returns the mnemonic modifier for this window. See
gtk_window_set_mnemonic_modifier().
mnemonics on this window.
the modifier mask used to activate
Gets the value of the #GtkWindow:mnemonics-visible property.
in this window.
%TRUE if mnemonics are supposed to be visible
Returns whether the window is modal. See gtk_window_set_modal().
establishes a grab when shown
%TRUE if the window is set to be modal and
Fetches the requested opacity for this window. See
gtk_window_set_opacity().
the requested opacity for this window.
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.
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.
gtk_window_get_position() is not 100% reliable because the X Window System
does not specify a way to obtain the geometry of the
decorations placed on a window by the window manager.
Thus GTK+ is using a "best guess" that works with most
window managers.
Moreover, nearly all window managers are historically broken with
respect to their handling of window gravity. So moving a window to
its current position as returned by gtk_window_get_position() tends
to result in moving the window slightly. Window managers are
slowly getting better over time.
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.
If you are saving and restoring your application's window
positions, you should know that it's impossible for applications to
do this without getting it somewhat wrong because applications do
not have sufficient knowledge of window manager state. The Correct
Mechanism is to support the session management protocol (see the
"GnomeClient" object in the GNOME libraries for example) and allow
the window manager to save your window sizes and positions.
eturn 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
If a window has a resize grip, this will retrieve the grip
position, width and height into the specified #GdkRectangle.
%TRUE if the resize grip's area was retrieved
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.
returned is owned by the widget and must not be modified
or freed.
the role of the window if set, or %NULL. The
Returns the #GdkScreen associated with @window.
a #GdkScreen.
Obtains the current size of @window. If @window is not onscreen,
it returns the size GTK+ will suggest to the <link
linkend="gtk-X11-arch">window manager</link> for the initial window
size (but this is not reliably the same as the size the window
manager will actually select). The size obtained by
gtk_window_get_size() is the last size received in a
#GdkEventConfigure, that is, GTK+ uses its locally-stored size,
rather than querying the X server for the size. As a result, if you
call gtk_window_resize() then immediately call
gtk_window_get_size(), the size won't have taken effect yet. After
the window manager processes the resize request, GTK+ receives
notification that the size has changed via a configure event, and
the size of the window gets updated.
because the size of the window may change between the time that you
get the size and the time that you perform some action assuming
that size is the current size. To avoid race conditions, connect to
"configure-event" on the window and adjust your size-dependent
state to match the size delivered in the #GdkEventConfigure.
size of the window manager decorations (aka the window frame or
border). Those are not drawn by GTK+ and GTK+ has no reliable
method of determining their size.
the window onscreen, there may be a better way. The preferred
way is to 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
things rather than doing it yourself, because all apps will
behave consistently and according to user prefs if the window
manager handles it. Also, the window manager can take the size
of the window decorations/border into account, while your
application cannot.
In any case, if you insist on application-specified window
positioning, there's <emphasis>still</emphasis> a better way than
doing it yourself - gtk_window_set_position() will frequently
handle the details for you.
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
Gets the value set by gtk_window_set_skip_taskbar_hint()
%TRUE if window shouldn't be in taskbar
Retrieves the title of the window. See gtk_window_set_title().
been set explicitely. The returned string is owned by the widget
and must not be modified or freed.
the title of the window, or %NULL if none has
Fetches the transient parent for this window. See
gtk_window_set_transient_for().
if no transient parent has been set.
the transient parent for this window, or %NULL
Gets the type hint for this window. See gtk_window_set_type_hint().
the type hint for @window.
Gets the value set by gtk_window_set_urgency_hint()
%TRUE if window is urgent
Gets the type of the window. See #GtkWindowType.
the type of the window
Returns whether @window has an explicit window group.
Since 2.22
%TRUE if @window has an explicit window group.
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
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 <link
linkend="gtk-X11-arch">window manager</link>) 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.
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.
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 <link
linkend="gtk-X11-arch">window manager</link>) 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.
Activates the targets associated with the mnemonic.
%TRUE if the activation is done.
the mnemonic
the modifiers
Asks the <link linkend="gtk-X11-arch">window manager</link> to move
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.
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:
<literal>gtk_window_move (window, gdk_screen_width () - window_width,
gdk_screen_height () - window_height)</literal> (note that this
example does not take multi-head scenarios into account).
The Extended Window Manager Hints specification at <ulink
url="http://www.freedesktop.org/Standards/wm-spec">
http://www.freedesktop.org/Standards/wm-spec</ulink> has a
nice table of gravities in the "implementation notes" section.
The gtk_window_get_position() documentation may also be relevant.
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.
|[
#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, FALSE, 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),
window,
&size_hints,
GDK_HINT_MIN_SIZE |
GDK_HINT_BASE_SIZE |
GDK_HINT_RESIZE_INC);
if (argc > 1)
{
if (!gtk_window_parse_geometry (GTK_WINDOW (window), argv[1]))
fprintf (stderr, "Failed to parse '%s'\n", argv[1]);
}
gtk_widget_show_all (window);
gtk_main ();
return 0;
}
]|
%TRUE if string was parsed successfully
geometry string
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.
If you are calling this function in response to a user interaction,
it is preferable to use gtk_window_present_with_time().
Presents a window to the user in response to a user interaction.
If you need to present a window without a timestamp, use
gtk_window_present(). See gtk_window_present() for details.
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 #GdkEventKey
Reverses the effects of gtk_window_add_accel_group().
a #GtkAccelGroup
Removes a mnemonic from this window.
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.
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.
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.
%TRUE if a resize grip exists and is visible
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.
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.
%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 the window
is open.
a #GtkApplication, or %NULL
By default, windows are decorated with a title bar, resize
controls, etc. Some <link linkend="gtk-X11-arch">window
managers</link> 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.
%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 about. When setting
(rather than unsetting) the default widget it's generally easier to
call gtk_widget_grab_focus() on the widget. Before making a widget
the default widget, you must set the #GTK_CAN_DEFAULT flag on the
widget you'd like to make the default using GTK_WIDGET_SET_FLAGS().
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.
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.
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
<link linkend="gtk-X11-arch">window managers</link> 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_window_show().
On Windows, this function always works, since there's no window manager
policy involved.
%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.
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.
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.
%TRUE to let this window receive input focus on map
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.
widget the geometry hints will be applied to or %NULL
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."
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.
%TRUE to allow a resize grip
Tells GTK+ whether to drop its extra reference to the window
when gtk_window_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.
the new value
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.
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.
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.
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.
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.
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.
list of #GdkPixbuf
Sets the icon for the window from a named themed icon. See
the docs for #GtkIconTheme for more details.
Note that this has nothing to do with the WM_ICON_NAME
property which is mentioned in the ICCCM.
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 <link
linkend="gtk-X11-arch">window manager</link>) 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 <ulink
url="http://www.freedesktop.org/Standards/wm-spec">Extended Window
Manager Hints</ulink> specification, the above state is mainly meant
for user preferences and should not be used by applications e.g. for
drawing attention to their dialogs.
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 <link
linkend="gtk-X11-arch">window manager</link>) 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 <ulink
url="http://www.freedesktop.org/Standards/wm-spec">Extended Window
Manager Hints</ulink> specification, the above state is mainly meant
for user preferences and should not be used by applications e.g. for
drawing attention to their dialogs.
whether to keep @window below other windows
Sets the mnemonic modifier for this window.
the modifier mask used to activate mnemonics on this window.
Sets the #GtkWindow:mnemonics-visible property.
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 <link linkend="gtk-X11-arch">window managers</link>
will then disallow lowering the dialog below the parent.
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.
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 position constraint.
Sets whether the user can resize a window. Windows are user resizable
by default.
%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
<link linkend="gtk-X11-arch">window manager</link> 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.
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 #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.)
%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.
%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 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 <link linkend="gtk-X11-arch">window
manager</link>, so exactly how the title appears to users may vary
according to a user's exact configuration. The title should help a
user distinguish this window from other windows they may have
open. A good title might include the application name and current
document filename, for example.
title of the window
Dialog windows should be set transient for the main application
window they were spawned from. This allows <link
linkend="gtk-X11-arch">window managers</link> 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 Windows, this function puts the child window on top of the parent,
much as the window manager would have done on X.
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.
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.
%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.
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 <link
linkend="gtk-X11-arch">window manager</link>) 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.
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 <link
linkend="gtk-X11-arch">window manager</link>) 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.
Asks to unmaximize @window. Note that you shouldn't assume the
window is definitely unmaximized afterward, because other entities
(e.g. the user or <link linkend="gtk-X11-arch">window
manager</link>) 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.
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 <link linkend="gtk-X11-arch">window
manager</link>) 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.
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.
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.
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.
The :icon-name property specifies the name of the themed icon to
use as the window icon. See #GtkIconTheme for more details.
The requested opacity of the window. See gtk_window_set_opacity() for
more details about window opacity.
Whether a corner resize grip is currently shown.
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
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted when the user activates the default widget
of @window.
The ::activate-focus signal is a
<link linkend="keybinding-signals">keybinding signal</link>
which gets emitted when the user activates the currently
focused widget of @window.
The ::keys-changed signal gets emitted when the set of accelerators
or mnemonics that are associated with @window changes.
widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window.
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.
the #GtkWindow to add
Returns the current grab widget for @device, or %NULL if none.
The grab widget, or %NULL
a #GdkDevice
Gets the current grab widget of the given group,
see gtk_grab_add().
the current grab widget of the group
Returns a list of the #GtkWindows that belong to @window_group.
newly-allocated list of windows inside the group.
A
Removes a window from 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.
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.
Describes a type of line wrapping.
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 value set by 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 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
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
Sets the modifiers that will be considered significant for keyboard
accelerators. The default mod mask is #GDK_CONTROL_MASK |
#GDK_SHIFT_MASK | #GDK_MOD1_MASK | #GDK_SUPER_MASK |
#GDK_HYPER_MASK | #GDK_META_MASK, that is, 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.
Whether the alternative button order should be used
a #GdkScreen, or %NULL to use the default screen
Override or install a new key binding for @keyval with @modifiers on
emitted on the target widget, with @n_args @Varargs used as
arguments.
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
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:
<informalexample><programlisting>
bind "key" {
"signalname" (param, ...)
...
}
</programlisting></informalexample>
Or they may also unbind a key combination:
<informalexample><programlisting>
unbind "key"
</programlisting></informalexample>
Key combinations must be in a format that can be parsed by
gtk_accelerator_parse().
the expected token otherwise
%G_TOKEN_NONE if the signal was successfully parsed and added,
a #GtkBindingSet
a signal description
Override or install a new key binding for @keyval with @modifiers on
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
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
%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.
This function will return %TRUE if the contents of the given
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
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.
of the running library is newer than the version
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+.
given version, or a string describing the version mismatch.
The returned string is owned by GTK+ and should not be modified
or freed.
%NULL if the GTK+ library is compatible with the
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 #GtkDevice 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 <literal>setlocale (LC_ALL, "")</literal>. 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.
to @sizes.
The remainder of @extra_space after redistributing space
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.
Determines the source widget for a drag.
within a single application, a pointer to the source widget.
Otherwise, %NULL.
if the drag is occurring
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
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
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.
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 a widget to a given widget. GTK+
will not destroy the icon, 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
a toplevel window 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.
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.
<example>
<title>Updating the UI during a long computation</title>
<programlisting>
/* computation going on... */
while (gtk_events_pending ())
gtk_main_iteration ();
/* ...computation continued */
</programlisting>
</example>
%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 <application>libtool</application>
when building the GTK+ library the process is running against.
If <application>libtool</application> 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.
%NULL if there is no current event. The returned event must be
freed with gdk_event_free().
a copy of the current event, or
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.
had a state field
%TRUE if there was a current event and it
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.
or %GDK_CURRENT_TIME.
the timestamp from the current event,
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.
must not be freed
the default language as a #PangoLanguage,
If @event is %NULL or the event was not associated with any widget,
returns %NULL, otherwise returns the widget that received the event
originally.
received @event, or %NULL
the widget that originally
a #GdkEvent
Returns the interface age as passed to <application>libtool</application>
when building the GTK+ library the process is running against.
If <application>libtool</application> means nothing to you, don't
worry about it.
the interface age of the GTK+ library
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.
by GTK+
a #GOptionGroup for the commandline arguments recognized
whether to open the default display when parsing the commandline arguments
Queries the current grab of the default window group.
has the grab or %NULL if no grab is active
The widget which currently
Looks up the icon size associated with @name.
the icon size
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.
the name of the given icon size.
a #GtkIconSize.
Obtains the pixel size of a semantic icon size, possibly
modified by user preferences for the default #GtkSettings.
(See gtk_icon_size_lookup_for_settings().)
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.
%TRUE if @size was a valid size
an icon size
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.
%TRUE if @size was a valid size
a #GtkSettings object, used to determine which set of user preferences to used.
an icon size
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.
integer value representing the size
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.
an alias for @target
an existing icon size
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.
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 <emphasis>don't</emphasis> have to call gtk_init().
<note><para>
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.
</para></note>
<note><para>
Since 2.18, GTK+ calls <literal>signal (SIGPIPE, SIG_IGN)</literal>
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.
</para></note>
Address of the <parameter>argc</parameter> parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled.
Address of the <parameter>argv</parameter> 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
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.
initialized, %FALSE otherwise
%TRUE if the windowing system has been successfully
Address of the <parameter>argc</parameter> parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled.
Address of the <parameter>argv</parameter> 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
<option>--help</option> output. Note that your program will
be terminated after writing out the help output.
initialized, %FALSE otherwise
%TRUE if the windowing system has been successfully
Address of the <parameter>argc</parameter> parameter of your main() function (or 0 if @argv is %NULL). This will be changed if any arguments were handled.
Address of the <parameter>argv</parameter> parameter of main(), or %NULL. Any options understood by GTK+ are stripped before return.
a string which is displayed in the first line of <option>--help</option> output, after <literal><replaceable>programname</replaceable> [OPTION...]</literal>
a %NULL-terminated array of #GOptionEntrys describing the options of your program
a translation domain to use for translating the <option>--help</option> 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.
gtk_key_snooper_remove().
a unique id for this key snooper for use with
a #GtkKeySnoopFunc
data to pass to @snooper
Removes the key snooper function with the given id.
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:
<orderedlist>
<listitem><para>
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.
</para></listitem>
<listitem><para>
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. In that
case it is passed to gtk_selection_incr_event().
</para></listitem>
<listitem><para>
Then the event is pushed onto a stack so you can query the currently
handled event with gtk_get_current_event().
</para></listitem>
<listitem><para>
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:
<itemizedlist>
<listitem><para>
Deletion and destruction events are still sent to the event widget for
obvious reasons.
</para></listitem>
<listitem><para>
Events which directly relate to the visual representation of the event
widget.
</para></listitem>
<listitem><para>
Leave events are delivered to the event widget if there was an enter
event delivered to it before without the paired leave event.
</para></listitem>
<listitem><para>
Drag events are not redirected because it is unclear what the semantics
of that would be.
</para></listitem>
</itemizedlist>
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.
</para></listitem>
<listitem><para>
After finishing the delivery the event is popped from the event stack.
</para></listitem>
</orderedlist>
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.
innermost mainloop
%TRUE if gtk_main_quit() has been called for the
Runs a single iteration of the mainloop.
If no events are available either return or block depending on
the value of @blocking.
innermost mainloop
%TRUE if gtk_main_quit() has been called for the
%TRUE if you want GTK+ to block if no events are pending
Asks for the current nesting level of the main loop.
of the main loop
the nesting level of the current invocation
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
a #GtkStyle
a #cairo_t
a state
the widget (may be %NULL)
a style detail (may be %NULL)
the nth step, a value between 0 and #GtkSpinner:num-steps
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.
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.
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.
is owned by GTK+ and should not be modified.
the name of the default paper size. The string
Creates a list of known paper sizes.
allocated #GtkPaperSize objects
a newly allocated list of newly
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
There is no need to call this function explicitely if you are using
gtk_init(), or gtk_init_check().
%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
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().
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.
freed with g_free()), otherwise %NULL.
The filename, if found (must be
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.
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().
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 <link linkend="im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link>
environment variable for more details.
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 <link linkend="im-module-path"><envar>GTK_PATH</envar></link>
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.
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 <envar>GTK_PATH</envar> in
<xref linkend="gtk-running"/>.
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.)
to the returned style, so if you want to save this style around,
you should add a reference yourself.
the resulting style. No refcount is added
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:
|[
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));
]|
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 style created by matching with the
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
Parses a color in the <link linkend="color=format">format</link> expected
in a RC file.
Note that theme engines should use gtk_rc_parse_color_full() in
order to support symbolic colors.
that was expected but not found
%G_TOKEN_NONE if parsing succeeded, otherwise the token
a #GScanner
a pointer to a #GdkColor structure in which to store the result
Parses a color in the <link linkend="color=format">format</link> expected
in a RC file. If @style is not %NULL, it will be consulted to resolve
references to symbolic colors.
that was expected but not found
%G_TOKEN_NONE if parsing succeeded, otherwise the token
a #GScanner
a #GtkRcStyle, or %NULL
a pointer to a #GdkColor structure in which to store the result
A #GtkRcPropertyParser for use with gtk_settings_install_property_parser()
or gtk_widget_class_install_style_property_parser() which parses
borders in the form
<literal>"{ left, right, top, bottom }"</literal> for integers
%left, %right, %top and %bottom.
has been set to the resulting #GtkBorder.
%TRUE if @gstring could be parsed and @property_value
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
<literal>{ red, green, blue }</literal> where %red, %green and
%blue are integers between 0 and 65535 or floating-point numbers
between 0 and 1.
has been set to the resulting #GdkColor.
%TRUE if @gstring could be parsed and @property_value
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.
has been set to the resulting #GEnumValue.
%TRUE if @gstring could be parsed and @property_value
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
<literal>"( flag1 | flag2 | ... )"</literal>.
has been set to the resulting flags value.
%TRUE if @gstring could be parsed and @property_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
<literal>"{ width, height }"</literal> for integers %width and %height.
has been set to the resulting #GtkRequisition.
%TRUE if @gstring could be parsed and @property_value
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.
%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.
%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 explicitely on them
with gtk_widget_set_style().
a #GtkSettings
Sets the list of files that GTK+ will read at the
end of gtk_init().
A %NULL-terminated list of filenames.
Renders an activity area (Such as in #GtkSpinner or the
fill line in #GtkRange), the state %GTK_STATE_FLAG_ACTIVE
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.
<example>
<title>Typical arrow rendering at 0, 1&solidus;2 π, π and 3&solidus;2 π</title>
<inlinegraphic fileref="arrows.png" format="PNG"/>
</example>
a #GtkStyleContext
a #cairo_t
arrow angle from 0 to 2 * %G_PI, being 0 the arrow pointing to the north
Center X for the render area
Center Y for the render area
square side for render area
Renders the background of an element.
<example>
<title>Typical background rendering, showing the effect of
<parameter>background-image</parameter>,
<parameter>border-width</parameter> and
<parameter>border-radius</parameter></title>
<inlinegraphic fileref="background.png" format="PNG"/>
</example>
a #GtkStyleContext
a #cairo_t
X origin of the rectangle
Y origin of the rectangle
rectangle width
rectangle height
Renders a checkmark (as in a #GtkCheckButton).
The %GTK_STATE_FLAG_ACTIVE state determines whether the check is
on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it
should be marked as undefined.
<example>
<title>Typical checkmark rendering</title>
<inlinegraphic fileref="checks.png" format="PNG"/>
</example>
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_ACTIVE
determines whether the expander is collapsed or expanded.
<example>
<title>Typical expander rendering</title>
<inlinegraphic fileref="expanders.png" format="PNG"/>
</example>
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.
<example>
<title>Typical extension rendering</title>
<inlinegraphic fileref="extensions.png" format="PNG"/>
</example>
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.
<example>
<title>Typical focus rendering</title>
<inlinegraphic fileref="focus.png" format="PNG"/>
</example>
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.
<example>
<title>Examples of frame rendering, showing the effect of
<parameter>border-image</parameter>,
<parameter>border-color</parameter>,
<parameter>border-width</parameter>,
<parameter>border-radius</parameter> and
junctions</title>
<inlinegraphic fileref="frames.png" format="PNG"/>
</example>
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.
<example>
<title>Typical rendering of a frame with a gap</title>
<inlinegraphic fileref="frame-gap.png" format="PNG"/>
</example>
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.
<example>
<title>Handles rendered for the paned and grip classes</title>
<inlinegraphic fileref="handles.png" format="PNG"/>
</example>
a #GtkStyleContext
a #cairo_t
X origin of the rectangle
Y origin of the rectangle
rectangle width
rectangle height
Renders the icon specified by @source at the given @size, returning the result
in a pixbuf.
a newly-created #GdkPixbuf containing the rendered icon
a #GtkStyleContext
the #GtkIconSource specifying the icon to render
the size to render the icon at. A size of (GtkIconSize) -1 means render at the size of the source and don't scale.
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_ACTIVE
state will determine whether the option is on or off, and
%GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined.
<example>
<title>Typical option mark rendering</title>
<inlinegraphic fileref="options.png" format="PNG"/>
</example>
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,
or horizontal.
<example>
<title>Typical slider rendering</title>
<inlinegraphic fileref="sliders.png" format="PNG"/>
</example>
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 #GtkTarget
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.
request. (e.g., there was already a request in process for
this widget).
%TRUE if requested succeeded. %FALSE if we could not process
The widget which acts as requestor
Which selection to get
Form of information desired (e.g., STRING)
Time of request (usually of triggering event)
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 #GdkWidget), 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
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
<simplelist>
<member><filename>file:///home/gnome/pict.jpg</filename></member>
<member><filename>http://www.gnome.org</filename></member>
<member><filename>mailto:me@gnome.org</filename></member>
</simplelist>
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 function can be used as a replacement for gnome_vfs_url_show()
and gnome_url_show().
%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
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
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
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:
|[
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.
otherwise %FALSE.
%TRUE if @targets include a suitable target for images,
an array of #GdkAtom<!-- -->s
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.
otherwise %FALSE.
%TRUE if @targets include a suitable target for rich text,
an array of #GdkAtom<!-- -->s
the length of @targets
a #GtkTextBuffer
Determines if any of the targets in @targets can be used to
provide text.
otherwise %FALSE.
%TRUE if @targets include a suitable target for text,
an array of #GdkAtom<!-- -->s
the length of @targets
Determines if any of the targets in @targets can be used to
provide an uri list.
otherwise %FALSE.
%TRUE if @targets include a suitable target for uri lists,
an array of #GdkAtom<!-- -->s
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.
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.
a newly created widget.
a valid widget type.
Name of first property to set or %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.
a widget pointer to the newly created GtkWindow.
Title of the window to be displayed.
Text inside the window to be displayed.
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
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 <parameter>argc</parameter> parameter of the main() function. Changed if any arguments were handled.
Address of the <parameter>argv</parameter> parameter of main(). Any parameters understood by g_test_init() or gtk_init() are stripped before return.
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().
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
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.
wether 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.
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.
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 %GTK_NO_WINDOW widgets like GtkButton, 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.
wether 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 %GTK_NO_WINDOW widgets like GtkButton, 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.
wether 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.
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().
is otherwise valid
%TRUE if @selection_data had target type %GTK_TREE_MODEL_ROW and
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...
<example>
<title>A persistent window</title>
<programlisting>
#include <gtk/gtk.h><
int
main (int argc, char **argv)
{
GtkWidget *win, *but;
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 ("Close yourself. I mean it!");
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;
}
</programlisting>
</example>
%TRUE