summaryrefslogtreecommitdiff
path: root/gir
diff options
context:
space:
mode:
authorColin Walters <walters@verbum.org>2011-12-15 09:50:04 -0500
committerColin Walters <walters@verbum.org>2011-12-15 09:52:37 -0500
commitdde9894e9297cf4e9fc363d112bf521c940f5bf2 (patch)
tree91fd9ee6a134e5c2befb934d4f15160b492ee588 /gir
parentf35167808a98f9ea9aecb2c04af3b31198ea5f60 (diff)
downloadgobject-introspection-dde9894e9297cf4e9fc363d112bf521c940f5bf2.tar.gz
Update annotations from GLib git
Diffstat (limited to 'gir')
-rw-r--r--gir/gio-2.0.c2138
-rw-r--r--gir/glib-2.0.c586
-rw-r--r--gir/gobject-2.0.c66
3 files changed, 2497 insertions, 293 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 3d64e5ce..17d33fe6 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -62,7 +62,7 @@
* @change_state: the callback to connect to the "change-state" signal of the action
*
* This struct defines a single action. It is for use with
- * g_simple_action_group_add_entries().
+ * g_action_map_add_action_entries().
*
* The order of the items in the structure are intended to reflect
* frequency of use. It is permissible to use an incomplete initialiser
@@ -70,7 +70,7 @@
* after @name are optional. Additional optional fields may be added in
* the future.
*
- * See g_simple_action_group_add_entries() for an example.
+ * See g_action_map_add_action_entries() for an example.
*/
@@ -134,7 +134,9 @@
* @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
* @get_action_state: the virtual function pointer for g_action_group_get_action_state()
* @set_action_state: the virtual function pointer for g_action_group_set_action_state()
+ * @query_action: the virtual function pointer for g_action_group_query_action()
* @activate_action: the virtual function pointer for g_action_group_activate_action()
+ * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* @action_added: the class closure for the #GActionGroup::action-added signal
* @action_removed: the class closure for the #GActionGroup::action-removed signal
* @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
@@ -157,13 +159,25 @@
* @change_state: the virtual function pointer for g_action_change_state()
* @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one.
*
- *
+ * The virtual function table for #GAction.
*
* Since: 2.28
*/
/**
+ * GActionMapInterface:
+ * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
+ * @add_action: the virtual function pointer for g_action_map_add_action()
+ * @remove_action: the virtual function pointer for g_action_map_remove_action()
+ *
+ * The virtual function table for #GActionMap.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* GAppInfo:
*
* Information about an installed application and methods to launch
@@ -224,8 +238,7 @@
/**
* GApplication:
*
- * The <structname>GApplication</structname> structure contains private
- * data and should only be accessed using the provided API
+ *
*
* Since: 2.28
*/
@@ -292,24 +305,14 @@
* @activate: invoked on the primary instance when an activation occurs
* @open: invoked on the primary instance when there are files to open
* @command_line: invoked on the primary instance when a command-line is not handled locally
- * @local_command_line: invoked (locally) when the process has been invoked via commandline execution. The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information.
+ * @local_command_line: invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information.
* @before_emit: invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance
* @after_emit: invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance
* @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions
- * @quit_mainloop: invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested)
- * @run_mainloop: invoked on the primary instance from g_application_run() if the use-count is non-zero
- *
+ * @quit_mainloop: Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32
+ * @run_mainloop: Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore
*
- *
- * Since: 2.28
- */
-
-
-/**
- * GApplicationCommandLine:
- *
- * The <structname>GApplicationCommandLine</structname> structure contains private
- * data and should only be accessed using the provided API
+ * Virtual function table for #GApplication.
*
* Since: 2.28
*/
@@ -318,8 +321,8 @@
/**
* GApplicationCommandLineClass:
*
- * The <structname>GApplicationCommandLineClass</structname> structure contains
- * private data only
+ * The <structname>GApplicationCommandLineClass</structname> structure
+ * contains private data only
*
* Since: 2.28
*/
@@ -3979,6 +3982,86 @@
/**
+ * GMenu:
+ *
+ * #GMenu is an opaque structure type. You must access it using the
+ * functions below.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GMenuAttributeIter:
+ *
+ * #GMenuAttributeIter is an opaque structure type. You must access it
+ * using the functions below.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GMenuItem:
+ *
+ * #GMenuItem is an opaque structure type. You must access it using the
+ * functions below.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GMenuLinkIter:
+ *
+ * #GMenuLinkIter is an opaque structure type. You must access it using
+ * the functions below.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GMenuModel:
+ *
+ * #GMenuModel is an opaque structure type. You must access it using the
+ * functions below.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GMenuModel::items-changed:
+ * @model: the #GMenuModel that is changing
+ * @position: the position of the change
+ * @removed: the number of items removed
+ * @added: the number of items added
+ *
+ * Emitted when a change has occured to the menu.
+ *
+ * The only changes that can occur to a menu is that items are removed
+ * or added. Items may not change (except by being removed and added
+ * back in the same location). This signal is capable of describing
+ * both of those changes (at the same time).
+ *
+ * The signal means that starting at the index @position, @removed
+ * items were removed and @added items were added in their place. If
+ * @removed is zero then only items were added. If @added is zero
+ * then only items were removed.
+ *
+ * As an example, if the menu contains items a, b, c, d (in that
+ * order) and the signal (2, 1, 3) occurs then the new composition of
+ * the menu will be a, b, _, _, _, d (with each _ representing some
+ * new item).
+ *
+ * Signal handlers may query the model (particularly the added items)
+ * and expect to see the results of the modification that is being
+ * reported. The signal is emitted after the modification.
+ */
+
+
+/**
* GMount:
*
* A handle to an object implementing the #GMountIface interface.
@@ -4930,7 +5013,8 @@
* @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR.
* @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
*
- *
+ * Represents a file descriptor, which events to poll for, and which events
+ * occurred.
*/
@@ -6092,7 +6176,7 @@
* call malloc(), which includes POSIX functions such as setenv().
* If you need to set up the child environment differently from
* the parent, you should use g_get_environ(), g_environ_setenv(),
- * and g_environ_unsetev(), and then pass the complete environment
+ * and g_environ_unsetenv(), and then pass the complete environment
* list to the <literal>g_spawn...</literal> function.
*/
@@ -6102,22 +6186,22 @@
* @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
* @G_SPAWN_ERROR_READ: Read or select on pipes failed.
* @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
- * @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
- * @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
- * @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
- * @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
- * @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
- * @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
- * @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
- * @G_SPAWN_ERROR_IO: execv() returned %EIO.
- * @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
- * @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
- * @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
- * @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
- * @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
+ * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
+ * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
+ * @G_SPAWN_ERROR_2BIG: execv() returned <literal>E2BIG</literal>
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
+ * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
+ * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
+ * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
+ * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
+ * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
+ * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
+ * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
+ * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
* @G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error-&gt;message</literal> should explain.
*
* Error codes returned by spawning processes.
@@ -6661,16 +6745,6 @@
/**
- * GTlsDatabaseVerifyFlags:
- * @G_TLS_DATABASE_VERIFY_NONE: No verification flags
- *
- * Flags for g_tls_database_verify_chain().
- *
- * Since: 2.30
- */
-
-
-/**
* GTlsError:
* @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available
* @G_TLS_ERROR_MISC: Miscellaneous TLS error
@@ -7809,7 +7883,7 @@
* Inserts a breakpoint instruction into the code.
*
* On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a %SIGTRAP signal.
+ * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
*/
@@ -8167,7 +8241,7 @@
* (GInstanceInitFunc) gtk_gadget_init,
* (GTypeFlags) flags);
* {
- * static const GInterfaceInfo g_implement_interface_info = {
+ * const GInterfaceInfo g_implement_interface_info = {
* (GInterfaceInitFunc) gtk_gadget_gizmo_init
* };
* g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
@@ -10085,6 +10159,15 @@
/**
+ * G_TYPE_BYTES:
+ *
+ * The #GType for #GBytes.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* G_TYPE_BYTE_ARRAY:
*
* The #GType for a boxed type holding a #GByteArray reference.
@@ -11156,6 +11239,18 @@
/**
+ * G_UNICHAR_MAX_DECOMPOSITION_LENGTH:
+ *
+ * The maximum length (in codepoints) of a compatibility or canonical
+ * decomposition of a single Unicode character.
+ *
+ * This is as defined by Unicode 6.1.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* G_UNICODE_COMBINING_MARK:
*
* Older name for %G_UNICODE_SPACING_MARK.
@@ -11819,7 +11914,7 @@
/**
* SECTION:gaction
* @title: GAction
- * @short_description: An action
+ * @short_description: An action interface
*
* #GAction represents a single named action.
*
@@ -11857,8 +11952,32 @@
* SECTION:gactiongroup
* @title: GActionGroup
* @short_description: A group of actions
- *
- * #GActionGroup represents a group of actions.
+ * @see_also: #GAction
+ *
+ * #GActionGroup represents a group of actions. Actions can be used to
+ * expose functionality in a structured way, either from one part of a
+ * program to another, or to the outside world. Action groups are often
+ * used together with a #GMenuModel that provides additional
+ * representation data for displaying the actions to the user, e.g. in
+ * a menu.
+ *
+ * The main way to interact with the actions in a GActionGroup is to
+ * activate them with g_action_group_activate_action(). Activating an
+ * action may require a #GVariant parameter. The required type of the
+ * parameter can be inquired with g_action_group_get_action_parameter_type().
+ * Actions may be disabled, see g_action_group_get_action_enabled().
+ * Activating a disabled action has no effect.
+ *
+ * Actions may optionally have a state in the form of a #GVariant. The
+ * current state of an action can be inquired with
+ * g_action_group_get_action_state(). Activating a stateful action may
+ * change its state, but it is also possible to set the state by calling
+ * g_action_group_change_action_state().
+ *
+ * As typical example, consider a text editing application which has an
+ * option to change the current font to 'bold'. A good way to represent
+ * this would be a stateful action, with a boolean state. Activating the
+ * action would toggle the state.
*
* Each action in the group has a unique name (which is a string). All
* method calls, except g_action_group_list_actions() take the name of
@@ -11869,11 +11988,51 @@
* forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
* with actions. 'Internal' APIs (ie: ones meant only to be accessed by
* the action group implementation) are found on subclasses. This is
- * why you will find -- for example -- g_action_group_get_action_enabled()
+ * why you will find - for example - g_action_group_get_action_enabled()
* but not an equivalent <function>set()</function> call.
*
* Signals are emitted on the action group in response to state changes
* on individual actions.
+ *
+ * Implementations of #GActionGroup should provide implementations for
+ * the virtual functions g_action_group_list_actions() and
+ * g_action_group_query_action(). The other virtual functions should
+ * not be implemented - their "wrappers" are actually implemented with
+ * calls to g_action_group_query_action().
+ */
+
+
+/**
+ * SECTION:gactiongroupexporter
+ * @title: GActionGroup exporter
+ * @short_description: Export GActionGroups on D-Bus
+ * @see_also: #GActionGroup, #GDBusActionGroup
+ *
+ * These functions support exporting a #GActionGroup on D-Bus.
+ * The D-Bus interface that is used is a private implementation
+ * detail.
+ *
+ * To access an exported #GActionGroup remotely, use
+ * g_dbus_action_group_new() to obtain a #GDBusActionGroup.
+ */
+
+
+/**
+ * SECTION:gactionmap
+ * @title: GActionMap
+ * @short_description: Interface for action containers
+ *
+ * The GActionMap interface is implemented by #GActionGroup
+ * implementations that operate by containing a number of
+ * named #GAction instances, such as #GSimpleActionGroup.
+ *
+ * One useful application of this interface is to map the
+ * names of actions from various action groups to unique,
+ * prefixed names (e.g. by prepending "app." or "win.").
+ * This is the motivation for the 'Map' part of the interface
+ * name.
+ *
+ * Since: 2.32
*/
@@ -11953,42 +12112,48 @@
* login. When your application is launched again, its arguments
* are passed through platform communication to the already running
* program. The already running instance of the program is called the
- * <firstterm>primary instance</firstterm>.
- *
- * Before using GApplication, you must choose an "application identifier".
- * The expected form of an application identifier is very close to that of
- * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
- * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
- * For details on valid application identifiers, see
- * g_application_id_is_valid().
- *
- * The application identifier is claimed by the application as a
- * well-known bus name on the user's session bus. This means that the
- * uniqueness of your application is scoped to the current session. It
- * also means that your application may provide additional services
- * (through registration of other object paths) at that bus name.
- *
- * The registration of these object paths should be done with the shared
- * GDBus session bus. Note that due to the internal architecture of
- * GDBus, method calls can be dispatched at any time (even if a main
- * loop is not running). For this reason, you must ensure that any
- * object paths that you wish to register are registered before
- * #GApplication attempts to acquire the bus name of your application
- * (which happens in g_application_register()). Unfortunately, this
- * means that you cannot use g_application_get_is_remote() to decide if
- * you want to register object paths.
+ * <firstterm>primary instance</firstterm>. On Linux, the D-Bus session
+ * bus is used for communication.
*
* GApplication provides convenient life cycle management by maintaining
* a <firstterm>use count</firstterm> for the primary application instance.
* The use count can be changed using g_application_hold() and
* g_application_release(). If it drops to zero, the application exits.
+ * Higher-level classes such as #GtkApplication employ the use count to
+ * ensure that the application stays alive as long as it has any opened
+ * windows.
*
- * GApplication also implements the #GActionGroup interface and lets you
- * easily export actions by adding them with g_application_set_action_group().
- * When invoking an action by calling g_action_group_activate_action() on
- * the application, it is always invoked in the primary instance.
- *
- * There is a number of different entry points into a #GApplication:
+ * Before using GApplication, you must choose an "application identifier".
+ * The expected form of an application identifier is very close to that of
+ * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
+ * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
+ * For details on valid application identifiers, see g_application_id_is_valid().
+ *
+ * On Linux, the application identifier is claimed as a well-known bus name
+ * on the user's session bus. This means that the uniqueness of your
+ * application is scoped to the current session. It also means that your
+ * application may provide additional services (through registration of other
+ * object paths) at that bus name. The registration of these object paths
+ * should be done with the shared GDBus session bus. Note that due to the
+ * internal architecture of GDBus, method calls can be dispatched at any time
+ * (even if a main loop is not running). For this reason, you must ensure that
+ * any object paths that you wish to register are registered before #GApplication
+ * attempts to acquire the bus name of your application (which happens in
+ * g_application_register()). Unfortunately, this means that you cannot use
+ * g_application_get_is_remote() to decide if you want to register object paths.
+ *
+ * GApplication also implements the #GActionGroup and #GActionMap
+ * interfaces and lets you easily export actions by adding them with
+ * g_action_map_add_action(). When invoking an action by calling
+ * g_action_group_activate_action() on the application, it is always
+ * invoked in the primary instance. The actions are also exported on
+ * the session bus, and GIO provides the #GDBusActionGroup wrapper to
+ * conveniently access them remotely. Additionally, g_application_set_app_menu()
+ * and g_application_set_menubar() can be used to export representation
+ * data for the actions, in the form of #GMenuModels. GIO provides
+ * a #GDBusMenuModel wrapper for remote access to exported #GMenuModels.
+ *
+ * There is a number of different entry points into a GApplication:
* <itemizedlist>
* <listitem>via 'Activate' (i.e. just starting the application)</listitem>
* <listitem>via 'Open' (i.e. opening some files)</listitem>
@@ -12039,6 +12204,14 @@
* </xi:include>
* </programlisting>
* </example>
+ *
+ * <example id="gapplication-example-menu"><title>A GApplication with menus</title>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
*/
@@ -12502,6 +12675,18 @@
/**
+ * SECTION:gdbusactiongroup
+ * @title: GDBusActionGroup
+ * @short_description: A D-Bus GActionGroup implementation
+ * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
+ *
+ * #GDBusActionGroup is an implementation of the #GActionGroup
+ * interface that can be used as a proxy for an action group
+ * that is exported over D-Bus with g_dbus_connection_export_action_group().
+ */
+
+
+/**
* SECTION:gdbusaddress
* @title: D-Bus Addresses
* @short_description: D-Bus connection endpoints
@@ -12703,7 +12888,19 @@
* used when registering objects with g_dbus_connection_register_object().
*
* The format of D-Bus introspection XML is specified in the
- * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html&num;introspection-format">D-Bus specification</link>.
+ * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>.
+ */
+
+
+/**
+ * SECTION:gdbusmenumodel
+ * @title: GDBusMenuModel
+ * @short_description: A D-Bus GMenuModel implementation
+ * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
+ *
+ * #GDBusMenuModel is an implementation of #GMenuModel that can be used
+ * as a proxy for a menu model that is exported over D-Bus with
+ * g_dbus_connection_export_menu_model().
*/
@@ -13086,6 +13283,7 @@
* g_file_new_for_path() if you have a path.
* g_file_new_for_uri() if you have a URI.
* g_file_new_for_commandline_arg() for a command line argument.
+ * g_file_new_tmp() to create a temporary file from a template.
* g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name().
*
* One way to think of a #GFile is as an abstraction of a pathname. For normal
@@ -13611,11 +13809,16 @@
* @see_also: #GAsyncInitable
*
* #GInitable is implemented by objects that can fail during
- * initialization. If an object implements this interface the
- * g_initable_init() function must be called as the first thing
- * after construction. If g_initable_init() is not called, or if
- * it returns an error, all further operations on the object
- * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error.
+ * initialization. If an object implements this interface then
+ * it must be initialized as the first thing after construction,
+ * either via g_initable_init() or g_async_initable_init_async()
+ * (the latter is only available if it also implements #GAsyncInitable).
+ *
+ * If the object is not initialized, or initialization returns with an
+ * error, then all operations on the object except g_object_ref() and
+ * g_object_unref() are considered to be invalid, and have undefined
+ * behaviour. They will often fail with g_critical() or g_warning(), but
+ * this must not be relied on.
*
* Users of objects implementing this are not intended to use
* the interface method directly, instead it will be used automatically
@@ -13756,6 +13959,221 @@
/**
+ * SECTION:gmenu
+ * @title: GMenu
+ * @short_description: A simple implementation of GMenuModel
+ *
+ * #GMenu is a simple implementation of #GMenuModel.
+ * You populate a #GMenu by adding #GMenuItem instances to it.
+ *
+ * There are some convenience functions to allow you to directly
+ * add items (avoiding #GMenuItem) for the common cases. To add
+ * a regular item, use g_menu_insert(). To add a section, use
+ * g_menu_insert_section(). To add a submenu, use
+ * g_menu_insert_submenu().
+ *
+ * Often it is more convenient to create a #GMenu from an XML
+ * fragment, using <link linkend="gio-GMenu-Markup">GMenu Markup</link>.
+ */
+
+
+/**
+ * SECTION:gmenuexporter
+ * @title: GMenuModel exporter
+ * @short_description: Export GMenuModels on D-Bus
+ * @see_also: #GMenuModel, #GDBusMenuModel
+ *
+ * These functions support exporting a #GMenuModel on D-Bus.
+ * The D-Bus interface that is used is a private implementation
+ * detail.
+ *
+ * To access an exported #GMenuModel remotely, use
+ * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
+ */
+
+
+/**
+ * SECTION:gmenumarkup
+ * @title: GMenu Markup
+ * @short_description: parsing and printing GMenuModel XML
+ *
+ * The functions here allow to instantiate #GMenuModels by parsing
+ * fragments of an XML document.
+ * * The XML format for #GMenuModel consists of a toplevel
+ * <tag class="starttag">menu</tag> element, which contains one or more
+ * <tag class="starttag">item</tag> elements. Each <tag class="starttag">item</tag>
+ * element contains <tag class="starttag">attribute</tag> and <tag class="starttag">link</tag>
+ * elements with a mandatory name attribute.
+ * <tag class="starttag">link</tag> elements have the same content
+ * model as <tag class="starttag">menu</tag>.
+ *
+ * Here is the XML for <xref linkend="menu-example"/>:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/menumarkup2.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
+ * The parser also understands a somewhat less verbose format, in which
+ * attributes are encoded as actual XML attributes of <tag class="starttag">item</tag>
+ * elements, and <tag class="starttag">link</tag> elements are replaced by
+ * <tag class="starttag">section</tag> and <tag class="starttag">submenu</tag> elements.
+ *
+ * Here is how the example looks in this format:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/menumarkup.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
+ * The parser can obtaing translations for attribute values using gettext.
+ * To make use of this, the <tag class="starttag">menu</tag> element must
+ * have a domain attribute which specifies the gettext domain to use, and
+ * <tag class="starttag">attribute</tag> elements can be marked for translation
+ * with a <literal>translatable="yes"</literal> attribute. It is also possible
+ * to specify message context and translator comments, using the context
+ * and comments attributes.
+ *
+ * The following DTD describes the XML format approximately:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/menumarkup.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
+ * To serialize a #GMenuModel into an XML fragment, use
+ * g_menu_markup_print_string().
+ */
+
+
+/**
+ * SECTION:gmenumodel
+ * @title: GMenuModel
+ * @short_description: An abstract class representing the contents of a menu
+ * @see_also: #GActionGroup
+ *
+ * #GMenuModel represents the contents of a menu -- an ordered list of
+ * menu items. The items are associated with actions, which can be
+ * activated through them. Items can be grouped in sections, and may
+ * have submenus associated with them. Both items and sections usually
+ * have some representation data, such as labels or icons. The type of
+ * the associated action (ie whether it is stateful, and what kind of
+ * state it has) can influence the representation of the item.
+ *
+ * The conceptual model of menus in #GMenuModel is hierarchical:
+ * sections and submenus are again represented by #GMenuModels.
+ * Menus themselves do not define their own roles. Rather, the role
+ * of a particular #GMenuModel is defined by the item that references
+ * it (or, in the case of the 'root' menu, is defined by the context
+ * in which it is used).
+ *
+ * As an example, consider the visible portions of the menu in
+ * <xref linkend="menu-example"/>.
+ *
+ * <figure id="menu-example">
+ * <title>An example menu</title>
+ * <graphic fileref="menu-example.png" format="PNG"></graphic>
+ * </figure>
+ *
+ * There are 8 "menus" visible in the screenshot: one menubar, two
+ * submenus and 5 sections:
+ * <itemizedlist>
+ * <listitem>the toplevel menubar (containing 4 items)</listitem>
+ * <listitem>the View submenu (containing 3 sections)</listitem>
+ * <listitem>the first section of the View submenu (containing 2 items)</listitem>
+ * <listitem>the second section of the View submenu (containing 1 item)</listitem>
+ * <listitem>the final section of the View submenu (containing 1 item)</listitem>
+ * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
+ * <listitem>the Sources section (containing 2 items)</listitem>
+ * <listitem>the Markup section (containing 2 items)</listitem>
+ * </itemizedlist>
+ *
+ * <xref linkend="menu-model"/> illustrates the conceptual connection between
+ * these 8 menus. Each large block in the figure represents a menu and the
+ * smaller blocks within the large block represent items in that menu. Some
+ * items contain references to other menus.
+ *
+ * <figure id="menu-model">
+ * <title>A menu model</title>
+ * <graphic fileref="menu-model.png" format="PNG"></graphic>
+ * </figure>
+ *
+ * Notice that the separators visible in <xref linkend="menu-example"/>
+ * appear nowhere in <xref linkend="menu-model"/>. This is because
+ * separators are not explicitly represented in the menu model. Instead,
+ * a separator is inserted between any two non-empty sections of a menu.
+ * Section items can have labels just like any other item. In that case,
+ * a display system may show a section header instead of a separator.
+ *
+ * The motivation for this abstract model of application controls is
+ * that modern user interfaces tend to make these controls available
+ * outside the application. Examples include global menus, jumplists,
+ * dash boards, etc. To support such uses, it is necessary to 'export'
+ * information about actions and their representation in menus, which
+ * is exactly what the
+ * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
+ * and the
+ * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
+ * do for #GActionGroup and #GMenuModel. The client-side counterparts
+ * to make use of the exported information are #GDBusActionGroup and
+ * #GDBusMenuModel.
+ *
+ * The API of #GMenuModel is very generic, with iterators for the
+ * attributes and links of an item, see g_menu_model_iterate_item_attributes()
+ * and g_menu_model_iterate_item_links(). The 'standard' attributes and
+ * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
+ * and %G_MENU_LINK_SUBMENU.
+ *
+ * Items in a #GMenuModel represent active controls if they refer to
+ * an action that can get activated when the user interacts with the
+ * menu item. The reference to the action is encoded by the string id
+ * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
+ * identifies an action in an action group. Which action group(s) provide
+ * actions depends on the context in which the menu model is used.
+ * E.g. when the model is exported as the application menu of a
+ * #GtkApplication, actions can be application-wide or window-specific
+ * (and thus come from two different action groups). By convention, the
+ * application-wide actions have names that start with "app.", while the
+ * names of window-specific actions start with "win.".
+ *
+ * While a wide variety of stateful actions is possible, the following
+ * is the minimum that is expected to be supported by all users of exported
+ * menu information:
+ * <itemizedlist>
+ * <listitem>an action with no parameter type and no state</listitem>
+ * <listitem>an action with no parameter type and boolean state</listitem>
+ * <listitem>an action with string parameter type and string state</listitem>
+ * </itemizedlist>
+ *
+ * <formalpara><title>Stateless</title>
+ * <para>
+ * A stateless action typically corresponds to an ordinary menu item.
+ * </para>
+ * <para>
+ * Selecting such a menu item will activate the action (with no parameter).
+ * </para>
+ * </formalpara>
+ *
+ * <formalpara><title>Boolean State</title>
+ * <para>
+ * An action with a boolean state will most typically be used with a "toggle"
+ * or "switch" menu item. The state can be set directly, but activating the
+ * action (with no parameter) results in the state being toggled.
+ * </para>
+ * <para>
+ * Selecting a toggle menu item will activate the action. The menu item should
+ * be rendered as "checked" when the state is true.
+ * </para>
+ * </formalpara>
+ *
+ * <formalpara><title>String Parameter and State</title>
+ * <para>
+ * Actions with string parameters and state will most typically be used to
+ * represent an enumerated choice over the items available for a group of
+ * radio menu items. Activating the action with a string parameter is
+ * equivalent to setting that parameter as the state.
+ * </para>
+ * <para>
+ * Radio menu items, in addition to being associated with the action, will
+ * have a target value. Selecting that menu item will result in activation
+ * of the action with the target value as the parameter. The menu item should
+ * be rendered as "selected" when the state of the action is equal to the
+ * target value of the menu item.
+ * </para>
+ * </formalpara>
+ */
+
+
+/**
* SECTION:gmount
* @short_description: Mount management
* @include: gio/gio.h
@@ -14304,10 +14722,10 @@
/**
* SECTION:gsimpleaction
* @title: GSimpleAction
- * @short_description: A simple GSimpleAction
+ * @short_description: A simple GAction implementation
*
* A #GSimpleAction is the obvious simple implementation of the #GAction
- * interface. This is the easiest way to create an action for purposes of
+ * interface. This is the easiest way to create an action for purposes of
* adding it to a #GSimpleActionGroup.
*
* See also #GtkAction.
@@ -14320,7 +14738,7 @@
* @short_description: A simple GActionGroup implementation
*
* #GSimpleActionGroup is a hash table filled with #GAction objects,
- * implementing the #GActionGroup interface.
+ * implementing the #GActionGroup and #GActionMap interfaces.
*/
@@ -15816,6 +16234,144 @@
/**
+ * g_action_group_query_action:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
+ * @enabled: (out): if the action is presently enabled
+ * @parameter_type: (out): the parameter type, or %NULL if none needed
+ * @state_type: (out): the state type, or %NULL if stateless
+ * @state_hint: (out): the state hint, or %NULL if none
+ * @state: (out): the current state, or %NULL if stateless
+ *
+ * Queries all aspects of the named action within an @action_group.
+ *
+ * This function acquires the information available from
+ * g_action_group_has_action(), g_action_group_get_action_enabled(),
+ * g_action_group_get_action_parameter_type(),
+ * g_action_group_get_action_state_type(),
+ * g_action_group_get_action_state_hint() and
+ * g_action_group_get_state() with a single function call.
+ *
+ * This provides two main benefits.
+ *
+ * The first is the improvement in efficiency that comes with not having
+ * to perform repeated lookups of the action in order to discover
+ * different things about it. The second is that implementing
+ * #GActionGroup can now be done by only overriding this one virtual
+ * function.
+ *
+ * The interface provides a default implementation of this function that
+ * calls the individual functions, as required, to fetch the
+ * information. The interface also provides default implementations of
+ * those functions that call this function. All implementations,
+ * therefore, must override either this function or all of the others.
+ *
+ * If the action exists, %TRUE is returned and any of the requested
+ * fields (as indicated by having a non-%NULL reference passed in) are
+ * filled. If the action doesn't exist, %FALSE is returned and the
+ * fields may or may not have been modified.
+ *
+ * Returns: %TRUE if the action exists, else %FALSE
+ * Since: 2.32
+ */
+
+
+/**
+ * g_action_map_add_action:
+ * @action_map: a #GActionMap
+ * @action: a #GAction
+ *
+ * Adds an action to the @action_map.
+ *
+ * If the action map already contains an action with the same name
+ * as @action then the old action is dropped from the action map.
+ *
+ * The action map takes its own reference on @action.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_action_map_add_action_entries:
+ * @action_map: a #GActionMap
+ * @entries: a pointer to the first item in an array of #GActionEntry structs
+ * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
+ * @user_data: the user data for signal connections
+ *
+ * A convenience function for creating multiple #GSimpleAction instances
+ * and adding them to a #GActionMap.
+ *
+ * Each action is constructed as per one #GActionEntry.
+ *
+ * <example>
+ * <title>Using g_action_map_add_action_entries()</title>
+ * <programlisting>
+ * static void
+ * activate_quit (GSimpleAction *simple,
+ * GVariant *parameter,
+ * gpointer user_data)
+ * {
+ * exit (0);
+ * }
+ *
+ * static void
+ * activate_print_string (GSimpleAction *simple,
+ * GVariant *parameter,
+ * gpointer user_data)
+ * {
+ * g_print ("%s\n", g_variant_get_string (parameter, NULL));
+ * }
+ *
+ * static GActionGroup *
+ * create_action_group (void)
+ * {
+ * const GActionEntry entries[] = {
+ * { "quit", activate_quit },
+ * { "print-string", activate_print_string, "s" }
+ * };
+ * GSimpleActionGroup *group;
+ *
+ * group = g_simple_action_group_new ();
+ * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+ *
+ * return G_ACTION_GROUP (group);
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_action_map_lookup_action:
+ * @action_map: a #GActionMap
+ * @action_name: the name of an action
+ *
+ * Looks up the action with the name @action_name in @action_map.
+ *
+ * If no such action exists, returns %NULL.
+ *
+ * Returns: (transfer none): a #GAction, or %NULL
+ * Since: 2.32
+ */
+
+
+/**
+ * g_action_map_remove_action:
+ * @action_map: a #GActionMap
+ * @action_name: the name of the action
+ *
+ * Removes the named action from the action map.
+ *
+ * If no action of this name is in the map then nothing happens.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_alloca:
* @size: number of bytes to allocate.
*
@@ -16599,6 +17155,18 @@
/**
+ * g_application_get_app_menu:
+ * @application: a #GApplication
+ *
+ * Returns the menu model that has been set with
+ * g_application_set_app_menu().
+ *
+ * Returns: the application menu of @application
+ * Since: 2.32
+ */
+
+
+/**
* g_application_get_application_id:
* @application: a #GApplication
*
@@ -16610,6 +17178,22 @@
/**
+ * g_application_get_default:
+ * @returns: (transfer none): the default application for this process, or %NULL
+ *
+ * Returns the default #GApplication instance for this process.
+ *
+ * Normally there is only one #GApplication per process and it becomes
+ * the default when it is created. You can exercise more control over
+ * this by using g_application_set_default().
+ *
+ * If there is no default application then %NULL is returned.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_application_get_flags:
* @application: a #GApplication
*
@@ -16671,6 +17255,18 @@
/**
+ * g_application_get_menubar:
+ * @application: a #GApplication
+ *
+ * Returns the menu model that has been set with
+ * g_application_set_menubar().
+ *
+ * Returns: the menubar for windows of @application
+ * Since: 2.32
+ */
+
+
+/**
* g_application_hold:
* @application: a #GApplication
*
@@ -16865,8 +17461,8 @@
*
* If, after the above is done, the use count of the application is zero
* then the exit status is returned immediately. If the use count is
- * non-zero then the mainloop is run until the use count falls to zero,
- * at which point 0 is returned.
+ * non-zero then the default main context is iterated until the use count
+ * falls to zero, at which point 0 is returned.
*
* If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
* use count of zero is delayed for a while (ie: the instance stays
@@ -16882,18 +17478,39 @@
* @application: a #GApplication
* @action_group: (allow-none): a #GActionGroup, or %NULL
*
- * Sets or unsets the group of actions associated with the application.
+ * This used to be how actions were associated with a #GApplication.
+ * Now there is #GActionMap for that.
*
- * These actions are the actions that can be remotely invoked.
*
- * It is an error to call this function after the application has been
- * registered.
+ * Deprecated:2.32:Use the #GActionMap interface instead. Never ever
+ * mix use of this API with use of #GActionMap on the same @application
+ * or things will go very badly wrong.
*
* Since: 2.28
*/
/**
+ * g_application_set_app_menu:
+ * @application: a #GApplication
+ * @app_menu: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the application menu for @application.
+ *
+ * The application menu is a single menu containing items that typically
+ * impact the application as a whole, rather than acting on a specific
+ * window or document. For example, you would expect to see
+ * "Preferences" or "Quit" in an application menu, but not "Save" or
+ * "Print".
+ *
+ * If supported, the application menu will be rendered by the desktop
+ * environment.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_application_set_application_id:
* @application: a #GApplication
* @application_id: the identifier for @application
@@ -16910,6 +17527,21 @@
/**
+ * g_application_set_default:
+ * @application: the application to set as default, or %NULL
+ *
+ * Sets or unsets the default application for the process, as returned
+ * by g_application_get_default().
+ *
+ * This function does not take its own reference on @application. If
+ * @application is destroyed then the default application will revert
+ * back to %NULL.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_application_set_flags:
* @application: a #GApplication
* @flags: the flags for @application
@@ -16944,6 +17576,27 @@
/**
+ * g_application_set_menubar:
+ * @application: a #GApplication
+ * @menubar: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the menubar for windows of @application.
+ *
+ * This is a menubar in the traditional sense.
+ *
+ * Depending on the desktop environment, this may appear at the top of
+ * each window, or at the top of the screen. In some environments, if
+ * both the application menu and the menubar are set, the application
+ * menu will be presented as if it were the first item of the menubar.
+ * Other environments treat the two as completely separate -- for
+ * example, the application menu may be rendered by the desktop shell
+ * while the menubar (if set) remains in each individual window.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_async_initable_init_async:
* @initable: a #GAsyncInitable.
* @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
@@ -16967,9 +17620,11 @@
* the object doesn't support cancellable initialization, the error
* %G_IO_ERROR_NOT_SUPPORTED will be returned.
*
- * If this function is not called, or returns with an error, then all
- * operations on the object should fail, generally returning the
- * error %G_IO_ERROR_NOT_INITIALIZED.
+ * As with #GInitable, if the object is not initialized, or initialization
+ * returns with an error, then all operations on the object except
+ * g_object_ref() and g_object_unref() are considered to be invalid, and
+ * have undefined behaviour. They will often fail with g_critical() or
+ * g_warning(), but this must not be relied on.
*
* Implementations of this method must be idempotent: i.e. multiple calls
* to this function with the same argument should return the same results.
@@ -18975,6 +19630,31 @@
/**
+ * g_dbus_action_group_get:
+ * @connection: A #GDBusConnection
+ * @bus_name: the bus name which exports the action group
+ * @object_path: the object path at which the action group is exported
+ *
+ * Obtains a #GDBusActionGroup for the action group which is exported at
+ * the given @bus_name and @object_path.
+ *
+ * The thread default main context is taken at the time of this call.
+ * All signals on the menu model (and any linked models) are reported
+ * with respect to this context. All calls on the returned menu model
+ * (and linked models) must also originate from this same context, with
+ * the thread default main context unchanged.
+ *
+ * This call is non-blocking. The returned action group may or may not
+ * already be filled in. The correct thing to do is connect the signals
+ * for the action group to monitor for changes and then to call
+ * g_action_group_list_actions() to get the initial list.
+ *
+ * Returns: (transfer full): a #GDBusActionGroup
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_address_get_for_bus_sync:
* @bus_type: A #GBusType.
* @cancellable: A #GCancellable or %NULL.
@@ -19448,6 +20128,65 @@
/**
+ * g_dbus_connection_export_action_group:
+ * @connection: a #GDBusConnection
+ * @object_path: a D-Bus object path
+ * @action_group: a #GActionGroup
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Exports @action_group on @connection at @object_path.
+ *
+ * The implemented D-Bus API should be considered private. It is
+ * subject to change in the future.
+ *
+ * A given object path can only have one action group exported on it.
+ * If this constraint is violated, the export will fail and 0 will be
+ * returned (with @error set accordingly).
+ *
+ * You can unexport the action group using
+ * g_dbus_connection_unexport_action_group() with the return value of
+ * this function.
+ *
+ * The thread default main context is taken at the time of this call.
+ * All incoming action activations and state change requests are
+ * reported from this context. Any changes on the action group that
+ * cause it to emit signals must also come from this same context.
+ * Since incoming action activations and state change requests are
+ * rather likely to cause changes on the action group, this effectively
+ * limits a given action group to being exported from only one main
+ * context.
+ *
+ * Returns: the ID of the export (never zero), or 0 in case of failure
+ * Since: 2.32
+ */
+
+
+/**
+ * g_dbus_connection_export_menu_model:
+ * @connection: a #GDBusConnection
+ * @object_path: a D-Bus object path
+ * @menu: a #GMenuModel
+ * @error: return location for an error, or %NULL
+ *
+ * Exports @menu on @connection at @object_path.
+ *
+ * The implemented D-Bus API should be considered private.
+ * It is subject to change in the future.
+ *
+ * An object path can only have one action group exported on it. If this
+ * constraint is violated, the export will fail and 0 will be
+ * returned (with @error set accordingly).
+ *
+ * You can unexport the menu model using
+ * g_dbus_connection_unexport_menu_model() with the return value of
+ * this function.
+ *
+ * Returns: the ID of the export (never zero), or 0 in case of failure
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_connection_flush:
* @connection: A #GDBusConnection.
* @cancellable: A #GCancellable or %NULL.
@@ -20099,6 +20838,38 @@
/**
+ * g_dbus_connection_unexport_action_group:
+ * @connection: a #GDBusConnection
+ * @export_id: the ID from g_dbus_connection_export_action_group()
+ *
+ * Reverses the effect of a previous call to
+ * g_dbus_connection_export_action_group().
+ *
+ * It is an error to call this function with an ID that wasn't returned
+ * from g_dbus_connection_export_action_group() or to call it with the
+ * same ID more than once.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_dbus_connection_unexport_menu_model:
+ * @connection: a #GDBusConnection
+ * @export_id: the ID from g_dbus_connection_export_menu_model()
+ *
+ * Reverses the effect of a previous call to
+ * g_dbus_connection_export_menu_model().
+ *
+ * It is an error to call this function with an ID that wasn't returned
+ * from g_dbus_connection_export_menu_model() or to call it with the
+ * same ID more than once.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_connection_unregister_object:
* @connection: A #GDBusConnection.
* @registration_id: A registration id obtained from g_dbus_connection_register_object().
@@ -20579,11 +21350,15 @@
*
* Exports @interface_ at @object_path on @connection.
*
+ * This can be called multiple times to export the same @interface_
+ * onto multiple connections however the @object_path provided must be
+ * the same for all connections.
+ *
* Use g_dbus_interface_skeleton_unexport() to unexport the object.
*
* @error set.
*
- * Returns: %TRUE if the interface was exported, other %FALSE with
+ * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
* Since: 2.30
*/
@@ -20609,7 +21384,7 @@
* g_dbus_interface_skeleton_get_connection:
* @interface_: A #GDBusInterfaceSkeleton.
*
- * Gets the connection that @interface_ is exported on, if any.
+ * Gets the first connection that @interface_ is exported on, if any.
*
* not exported anywhere. Do not free, the object belongs to @interface_.
*
@@ -20619,6 +21394,21 @@
/**
+ * g_dbus_interface_skeleton_get_connections:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ *
+ * Gets a list of the connections that @interface_ is exported on.
+ *
+ * all the connections that @interface_ is exported on. The returned
+ * list should be freed with g_list_free() after each element has
+ * been freed with g_object_unref().
+ *
+ * Returns: (element-type GDBusConnection) (transfer full): A list of
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_interface_skeleton_get_flags:
* @interface_: A #GDBusInterfaceSkeleton.
*
@@ -20680,6 +21470,18 @@
/**
+ * g_dbus_interface_skeleton_has_connection:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ * @connection: A #GDBusConnection.
+ *
+ * Checks if @interface_ is export on @connection.
+ *
+ * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_interface_skeleton_set_flags:
* @interface_: A #GDBusInterfaceSkeleton.
* @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
@@ -20694,14 +21496,30 @@
* g_dbus_interface_skeleton_unexport:
* @interface_: A #GDBusInterfaceSkeleton.
*
- * Stops exporting an interface previously exported with
- * g_dbus_interface_skeleton_export().
+ * Stops exporting @interface_ on all connections it is exported on.
+ *
+ * To unexport @interface_ from only a single connection, use
+ * g_dbus_interface_skeleton_export_from_connection()
*
* Since: 2.30
*/
/**
+ * g_dbus_interface_skeleton_unexport_from_connection:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ * @connection: A #GDBusConnection.
+ *
+ * Stops exporting @interface_ on @connection.
+ *
+ * To stop exporting on all connections the interface is exported on,
+ * use g_dbus_interface_skeleton_unexport().
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_is_address:
* @string: A string.
*
@@ -20791,6 +21609,28 @@
/**
+ * g_dbus_menu_model_get:
+ * @connection: a #GDBusConnection
+ * @bus_name: the bus name which exports the menu model
+ * @object_path: the object path at which the menu model is exported
+ *
+ * Obtains a #GDBusMenuModel for the menu model which is exported
+ * at the given @bus_name and @object_path.
+ *
+ * The thread default main context is taken at the time of this call.
+ * All signals on the menu model (and any linked models) are reported
+ * with respect to this context. All calls on the returned menu model
+ * (and linked models) must also originate from this same context, with
+ * the thread default main context unchanged.
+ *
+ * g_object_unref().
+ *
+ * Returns: (transfer full): a #GDBusMenuModel object. Free with
+ * Since: 2.32
+ */
+
+
+/**
* g_dbus_message_bytes_needed:
* @blob: A blob represent a binary D-Bus message.
* @blob_len: The length of @blob (must be at least 16).
@@ -21731,6 +22571,10 @@
*
* Parses @xml_data and returns a #GDBusNodeInfo representing the data.
*
+ * Note that this routine is using a
+ * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
+ * parser that only accepts a subset of valid XML documents.
+ *
* with g_dbus_node_info_unref().
*
* Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
@@ -26075,6 +26919,30 @@
/**
+ * g_file_new_tmp:
+ * @tmpl: (type filename) (allow-none): Template for the file name, as in g_file_open_tmp(), or %NULL for a default template.
+ * @iostream: (out): on return, a #GFileIOStream for the created file.
+ * @error: a #GError, or %NULL
+ *
+ * Opens a file in the preferred directory for temporary files (as
+ * returned by g_get_tmp_dir()) and returns a #GFile and
+ * #GFileIOStream pointing to it.
+ *
+ * @template should be a string in the GLib file name encoding
+ * containing a sequence of six 'X' characters, and containing no
+ * directory components. If it is %NULL, a default template is used.
+ *
+ * Unlike the other #GFile constructors, this will return %NULL if
+ * a temporary file could not be created.
+ *
+ * Free the returned object with g_object_unref().
+ *
+ * Returns: (transfer full): a new #GFile.
+ * Since: 2.32
+ */
+
+
+/**
* g_file_open_readwrite:
* @file: #GFile to open
* @cancellable: (allow-none): a #GCancellable
@@ -26837,7 +27705,7 @@
* @file: input #GFile.
* @attribute: a string containing the attribute's name.
* @type: The type of the attribute
- * @value_p: a pointer to the value (or the pointer itself if the type is a pointer type)
+ * @value_p: (allow-none): a pointer to the value (or the pointer itself if the type is a pointer type)
* @flags: a set of #GFileQueryInfoFlags.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @error: a #GError, or %NULL
@@ -26845,7 +27713,7 @@
* Sets an attribute in the file with attribute name @attribute to @value.
*
* Some attributes can be unset by setting @attribute to
- * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value to %NULL.
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
*
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
@@ -27858,8 +28726,10 @@
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @error: a #GError location to store the error occurring, or %NULL to ignore.
*
- * Initializes the object implementing the interface. This must be
- * done before any real use of the object after initial construction.
+ * Initializes the object implementing the interface.
+ *
+ * The object must be initialized before any real use after initial
+ * construction, either with this function or g_async_initable_init_async().
*
* Implementations may also support cancellation. If @cancellable is not %NULL,
* then initialization can be cancelled by triggering the cancellable object
@@ -27868,14 +28738,16 @@
* the object doesn't support cancellable initialization the error
* %G_IO_ERROR_NOT_SUPPORTED will be returned.
*
- * If this function is not called, or returns with an error then all
- * operations on the object should fail, generally returning the
- * error %G_IO_ERROR_NOT_INITIALIZED.
+ * If the object is not initialized, or initialization returns with an
+ * error, then all operations on the object except g_object_ref() and
+ * g_object_unref() are considered to be invalid, and have undefined
+ * behaviour. See the <xref linkend="ginitable"/> section introduction
+ * for more details.
*
* Implementations of this method must be idempotent, i.e. multiple calls
* to this function with the same argument should return the same results.
* Only the first call initializes the object, further calls return the result
- * of the first call. This is so that its safe to implement the singleton
+ * of the first call. This is so that it's safe to implement the singleton
* pattern in the GObject constructor function.
*
* return %FALSE and set @error appropriately if present.
@@ -29163,6 +30035,992 @@
/**
+ * g_menu_append:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Convenience function for appending a normal menu item to the end of
+ * @menu. Combine g_menu_new() and g_menu_insert_item() for a more
+ * flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_append_item:
+ * @menu: a #GMenu
+ * @item: a #GMenuItem to append
+ *
+ * Appends @item to the end of @menu.
+ *
+ * See g_menu_insert_item() for more information.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_append_section:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Convenience function for appending a section menu item to the end of
+ * @menu. Combine g_menu_new_section() and g_menu_insert_item() for a
+ * more flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_append_submenu:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Convenience function for appending a submenu menu item to the end of
+ * @menu. Combine g_menu_new_submenu() and g_menu_insert_item() for a
+ * more flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_attribute_iter_get_name:
+ * @iter: a #GMenuAttributeIter
+ *
+ * Gets the name of the attribute at the current iterator position, as
+ * a string.
+ *
+ * The iterator is not advanced.
+ *
+ * Returns: the name of the attribute
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_attribute_iter_get_next:
+ * @iter: a #GMenuAttributeIter
+ * @out_name: (out) (allow-none) (transfer none): the type of the attribute
+ * @value: (out) (allow-none) (transfer full): the attribute value
+ *
+ * This function combines g_menu_attribute_iter_next() with
+ * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
+ *
+ * First the iterator is advanced to the next (possibly first) attribute.
+ * If that fails, then %FALSE is returned and there are no other
+ * effects.
+ *
+ * If successful, @name and @value are set to the name and value of the
+ * attribute that has just been advanced to. At this point,
+ * g_menu_item_get_name() and g_menu_item_get_value() will return the
+ * same values again.
+ *
+ * The value returned in @name remains valid for as long as the iterator
+ * remains at the current position. The value returned in @value must
+ * be unreffed using g_variant_unref() when it is no longer in use.
+ *
+ * attribute
+ *
+ * Returns: %TRUE on success, or %FALSE if there is no additional
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_attribute_iter_get_value:
+ * @iter: a #GMenuAttributeIter
+ *
+ * Gets the value of the attribute at the current iterator position.
+ *
+ * The iterator is not advanced.
+ *
+ * Returns: (transfer full): the value of the current attribute
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_attribute_iter_next:
+ * @iter: a #GMenuAttributeIter
+ *
+ * Attempts to advance the iterator to the next (possibly first)
+ * attribute.
+ *
+ * %TRUE is returned on success, or %FALSE if there are no more
+ * attributes.
+ *
+ * You must call this function when you first acquire the iterator
+ * to advance it to the first attribute (and determine if the first
+ * attribute exists at all).
+ *
+ * Returns: %TRUE on success, or %FALSE when there are no more attributes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_freeze:
+ * @menu: a #GMenu
+ *
+ * Marks @menu as frozen.
+ *
+ * After the menu is frozen, it is an error to attempt to make any
+ * changes to it. In effect this means that the #GMenu API must no
+ * longer be used.
+ *
+ * This function causes g_menu_model_is_mutable() to begin returning
+ * %FALSE, which has some positive performance implications.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_insert:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Convenience function for inserting a normal menu item into @menu.
+ * Combine g_menu_new() and g_menu_insert_item() for a more flexible
+ * alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_insert_item:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @item: the #GMenuItem to insert
+ *
+ * Inserts @item into @menu.
+ *
+ * The "insertion" is actually done by copying all of the attribute and
+ * link values of @item and using them to form a new item within @menu.
+ * As such, @item itself is not really inserted, but rather, a menu item
+ * that is exactly the same as the one presently described by @item.
+ *
+ * This means that @item is essentially useless after the insertion
+ * occurs. Any changes you make to it are ignored unless it is inserted
+ * again (at which point its updated values will be copied).
+ *
+ * You should probably just free @item once you're done.
+ *
+ * There are many convenience functions to take care of common cases.
+ * See g_menu_insert(), g_menu_insert_section() and
+ * g_menu_insert_submenu() as well as "prepend" and "append" variants of
+ * each of these functions.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_insert_section:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Convenience function for inserting a section menu item into @menu.
+ * Combine g_menu_new_section() and g_menu_insert_item() for a more
+ * flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_insert_submenu:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Convenience function for inserting a submenu menu item into @menu.
+ * Combine g_menu_new_submenu() and g_menu_insert_item() for a more
+ * flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_new:
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Creates a new #GMenuItem.
+ *
+ * If @label is non-%NULL it is used to set the "label" attribute of the
+ * new item.
+ *
+ * If @detailed_action is non-%NULL it is used to set the "action" and
+ * possibly the "target" attribute of the new item. See
+ * g_menu_item_set_detailed_action() for more information.
+ *
+ * Returns: a new #GMenuItem
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_new_section:
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Creates a new #GMenuItem representing a section.
+ *
+ * This is a convenience API around g_menu_item_new() and
+ * g_menu_item_set_section().
+ *
+ * The effect of having one menu appear as a section of another is
+ * exactly as it sounds: the items from @section become a direct part of
+ * the menu that @menu_item is added to.
+ *
+ * Visual separation is typically displayed between two non-empty
+ * sections. If @label is non-%NULL then it will be encorporated into
+ * this visual indication. This allows for labeled subsections of a
+ * menu.
+ *
+ * As a simple example, consider a typical "Edit" menu from a simple
+ * program. It probably contains an "Undo" and "Redo" item, followed by
+ * a separator, followed by "Cut", "Copy" and "Paste".
+ *
+ * This would be accomplished by creating three #GMenu instances. The
+ * first would be populated with the "Undo" and "Redo" items, and the
+ * second with the "Cut", "Copy" and "Paste" items. The first and
+ * second menus would then be added as submenus of the third. In XML
+ * format, this would look something like the following:
+ *
+ * <informalexample><programlisting><![CDATA[
+ * <menu id='edit-menu'>
+ * <section>
+ * <item label='Undo'/>
+ * <item label='Redo'/>
+ * </section>
+ * <section>
+ * <item label='Cut'/>
+ * <item label='Copy'/>
+ * <item label='Paste'/>
+ * </section>
+ * </menu>
+ * ]]></programlisting></informalexample>
+ *
+ * The following example is exactly equivalent. It is more illustrative
+ * of the exact relationship between the menus and items (keeping in
+ * mind that the 'link' element defines a new menu that is linked to the
+ * containing one). The style of the second example is more verbose and
+ * difficult to read (and therefore not recommended except for the
+ * purpose of understanding what is really going on).
+ *
+ * <informalexample><programlisting><![CDATA[
+ * <menu id='edit-menu'>
+ * <item>
+ * <link name='section'>
+ * <item label='Undo'/>
+ * <item label='Redo'/>
+ * </link>
+ * </item>
+ * <item>
+ * <link name='section'>
+ * <item label='Cut'/>
+ * <item label='Copy'/>
+ * <item label='Paste'/>
+ * </link>
+ * </item>
+ * </menu>
+ * ]]></programlisting></informalexample>
+ *
+ * Returns: a new #GMenuItem
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_new_submenu:
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Creates a new #GMenuItem representing a submenu.
+ *
+ * This is a convenience API around g_menu_item_new() and
+ * g_menu_item_set_submenu().
+ *
+ * Returns: a new #GMenuItem
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_action_and_target:
+ * @menu_item: a #GMenuItem
+ * @action: (allow-none): the name of the action for this item
+ * @format_string: (allow-none): a GVariant format string
+ * @...: positional parameters, as per @format_string
+ *
+ * Sets or unsets the "action" and "target" attributes of @menu_item.
+ *
+ * If @action is %NULL then both the "action" and "target" attributes
+ * are unset (and @format_string is ignored along with the positional
+ * parameters).
+ *
+ * If @action is non-%NULL then the "action" attribute is set.
+ * @format_string is then inspected. If it is non-%NULL then the proper
+ * position parameters are collected to create a #GVariant instance to
+ * use as the target value. If it is %NULL then the positional
+ * parameters are ignored and the "target" attribute is unset.
+ *
+ * See also g_menu_item_set_action_and_target_value() for an equivalent
+ * call that directly accepts a #GVariant. See
+ * g_menu_item_set_detailed_action() for a more convenient version that
+ * works with string-typed targets.
+ *
+ * See also g_menu_item_set_action_and_target_value() for a
+ * description of the semantics of the action and target attributes.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_action_and_target_value:
+ * @menu_item: a #GMenuItem
+ * @action: (allow-none): the name of the action for this item
+ * @target_value: (allow-none): a #GVariant to use as the action target
+ *
+ * Sets or unsets the "action" and "target" attributes of @menu_item.
+ *
+ * If @action is %NULL then both the "action" and "target" attributes
+ * are unset (and @target_value is ignored).
+ *
+ * If @action is non-%NULL then the "action" attribute is set. The
+ * "target" attribute is then set to the value of @target_value if it is
+ * non-%NULL or unset otherwise.
+ *
+ * Normal menu items (ie: not submenu, section or other custom item
+ * types) are expected to have the "action" attribute set to identify
+ * the action that they are associated with. The state type of the
+ * action help to determine the disposition of the menu item. See
+ * #GAction and #GActionGroup for an overview of actions.
+ *
+ * In general, clicking on the menu item will result in activation of
+ * the named action with the "target" attribute given as the parameter
+ * to the action invocation. If the "target" attribute is not set then
+ * the action is invoked with no parameter.
+ *
+ * If the action has no state then the menu item is usually drawn as a
+ * plain menu item (ie: with no additional decoration).
+ *
+ * If the action has a boolean state then the menu item is usually drawn
+ * as a toggle menu item (ie: with a checkmark or equivalent
+ * indication). The item should be marked as 'toggled' or 'checked'
+ * when the boolean state is %TRUE.
+ *
+ * If the action has a string state then the menu item is usually drawn
+ * as a radio menu item (ie: with a radio bullet or equivalent
+ * indication). The item should be marked as 'selected' when the string
+ * state is equal to the value of the @target property.
+ *
+ * See g_menu_item_set_action_and_target() or
+ * g_menu_item_set_detailed_action() for two equivalent calls that are
+ * probably more convenient for most uses.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_attribute:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute to set
+ * @format_string: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as per @format_string
+ *
+ * Sets or unsets an attribute on @menu_item.
+ *
+ * The attribute to set or unset is specified by @attribute. This
+ * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+ * attribute name.
+ * Attribute names are restricted to lowercase characters, numbers
+ * and '-'. Furthermore, the names must begin with a lowercase character,
+ * must not end with a '-', and must not contain consecutive dashes.
+ *
+ * If @format_string is non-%NULL then the proper position parameters
+ * are collected to create a #GVariant instance to use as the attribute
+ * value. If it is %NULL then the positional parameterrs are ignored
+ * and the named attribute is unset.
+ *
+ * See also g_menu_item_set_attribute_value() for an equivalent call
+ * that directly accepts a #GVariant.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_attribute_value:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute to set
+ * @value: (allow-none): a #GVariant to use as the value, or %NULL
+ *
+ * Sets or unsets an attribute on @menu_item.
+ *
+ * The attribute to set or unset is specified by @attribute. This
+ * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+ * attribute name.
+ * Attribute names are restricted to lowercase characters, numbers
+ * and '-'. Furthermore, the names must begin with a lowercase character,
+ * must not end with a '-', and must not contain consecutive dashes.
+ *
+ * must consist only of lowercase
+ * ASCII characters, digits and '-'.
+ *
+ * If @value is non-%NULL then it is used as the new value for the
+ * attribute. If @value is %NULL then the attribute is unset. If
+ * the @value #GVariant is floating, it is consumed.
+ *
+ * See also g_menu_item_set_attribute() for a more convenient way to do
+ * the same.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_detailed_action:
+ * @menu_item: a #GMenuItem
+ * @detailed_action: the "detailed" action string
+ *
+ * Sets the "action" and possibly the "target" attribute of @menu_item.
+ *
+ * If @detailed_action contains a double colon ("::") then it is used as
+ * a separator between an action name and a target string. In this
+ * case, this call is equivalent to calling
+ * g_menu_item_set_action_and_target() with the part before the "::" and
+ * g_menu_item_set_target_value() with a string-type #GVariant
+ * containing the part following the "::".
+ *
+ * If @detailed_action doesn't contain "::" then the action is set to
+ * the given string (verbatim) and the target value is unset.
+ *
+ * See g_menu_item_set_action_and_target() or
+ * g_menu_item_set_action_and_target_value() for more flexible (but
+ * slightly less convenient) alternatives.
+ *
+ * See also g_menu_set_action_and_target_value() for a description of
+ * the semantics of the action and target attributes.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_label:
+ * @menu_item: a #GMenuItem
+ * @label: (allow-none): the label to set, or %NULL to unset
+ *
+ * Sets or unsets the "label" attribute of @menu_item.
+ *
+ * If @label is non-%NULL it is used as the label for the menu item. If
+ * it is %NULL then the label attribute is unset.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_link:
+ * @menu_item: a #GMenuItem
+ * @link: type of link to establish or unset
+ * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
+ *
+ * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
+ *
+ * Links are used to establish a relationship between a particular menu
+ * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
+ * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
+ * is used to create a section. Other types of link can be used, but there
+ * is no guarantee that clients will be able to make sense of them.
+ * Link types are restricted to lowercase characters, numbers
+ * and '-'. Furthermore, the names must begin with a lowercase character,
+ * must not end with a '-', and must not contain consecutive dashes.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_section:
+ * @menu_item: a #GMenuItem
+ * @section: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the "section" link of @menu_item to @section.
+ *
+ * The effect of having one menu appear as a section of another is
+ * exactly as it sounds: the items from @section become a direct part of
+ * the menu that @menu_item is added to. See g_menu_item_new_section()
+ * for more information about what it means for a menu item to be a
+ * section.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_item_set_submenu:
+ * @menu_item: a #GMenuItem
+ * @submenu: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the "submenu" link of @menu_item to @submenu.
+ *
+ * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
+ * link is unset.
+ *
+ * The effect of having one menu appear as a submenu of another is
+ * exactly as it sounds.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_link_iter_get_name:
+ * @iter: a #GMenuLinkIter
+ *
+ * Gets the name of the link at the current iterator position.
+ *
+ * The iterator is not advanced.
+ *
+ * Returns: the type of the link
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_link_iter_get_next:
+ * @iter: a #GMenuLinkIter
+ * @out_link: (out) (allow-none) (transfer none): the name of the link
+ * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
+ *
+ * This function combines g_menu_link_iter_next() with
+ * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
+ *
+ * First the iterator is advanced to the next (possibly first) link.
+ * If that fails, then %FALSE is returned and there are no other effects.
+ *
+ * If successful, @out_link and @value are set to the name and #GMenuModel
+ * of the link that has just been advanced to. At this point,
+ * g_menu_item_get_name() and g_menu_item_get_value() will return the
+ * same values again.
+ *
+ * The value returned in @out_link remains valid for as long as the iterator
+ * remains at the current position. The value returned in @value must
+ * be unreffed using g_object_unref() when it is no longer in use.
+ *
+ * Returns: %TRUE on success, or %FALSE if there is no additional link
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_link_iter_get_value:
+ * @iter: a #GMenuLinkIter
+ *
+ * Gets the linked #GMenuModel at the current iterator position.
+ *
+ * The iterator is not advanced.
+ *
+ * Returns: (transfer full): the #GMenuModel that is linked to
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_link_iter_next:
+ * @iter: a #GMenuLinkIter
+ *
+ * Attempts to advance the iterator to the next (possibly first)
+ * link.
+ *
+ * %TRUE is returned on success, or %FALSE if there are no more links.
+ *
+ * You must call this function when you first acquire the iterator to
+ * advance it to the first link (and determine if the first link exists
+ * at all).
+ *
+ * Returns: %TRUE on success, or %FALSE when there are no more links
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_markup_parser_end:
+ * @context: a #GMarkupParseContext
+ *
+ * Stop the parsing of a set of menus and return the #GHashTable.
+ *
+ * The #GHashTable maps strings to #GObject instances. The parser only
+ * adds #GMenu instances to the table, but it may contain other types if
+ * a table was provided to g_menu_markup_parser_start().
+ *
+ * This call should be matched with g_menu_markup_parser_start().
+ * See that function for more information
+ *
+ * Returns: (transfer full): the #GHashTable containing the objects
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_markup_parser_end_menu:
+ * @context: a #GMarkupParseContext
+ *
+ * Stop the parsing of a menu and return the newly-created #GMenu.
+ *
+ * This call should be matched with g_menu_markup_parser_start_menu().
+ * See that function for more information
+ *
+ * Returns: (transfer full): the newly-created #GMenu
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_markup_parser_start:
+ * @context: a #GMarkupParseContext
+ * @domain: (allow-none): translation domain for labels, or %NULL
+ * @objects: (allow-none): a #GHashTable for the objects, or %NULL
+ *
+ * Begin parsing a group of menus in XML form.
+ *
+ * If @domain is not %NULL, it will be used to translate attributes
+ * that are marked as translatable, using gettext().
+ *
+ * If @objects is specified then it must be a #GHashTable that was
+ * created using g_hash_table_new_full() with g_str_hash(),
+ * g_str_equal(), g_free() and g_object_unref(). Any named menus (ie:
+ * those with an id='' attribute) that are encountered while parsing
+ * will be added to this table. Each toplevel menu must be named.
+ *
+ * If @objects is %NULL then an empty hash table will be created.
+ *
+ * This function should be called from the start_element function for
+ * the element representing the group containing the menus. In other
+ * words, the content inside of this element is expected to be a list of
+ * menus.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_markup_parser_start_menu:
+ * @context: a #GMarkupParseContext
+ * @domain: (allow-none): translation domain for labels, or %NULL
+ * @objects: (allow-none): a #GHashTable for the objects, or %NULL
+ *
+ * Begin parsing the XML definition of a menu.
+ *
+ * This function should be called from the start_element function for
+ * the element representing the menu itself. In other words, the
+ * content inside of this element is expected to be a list of items.
+ *
+ * If @domain is not %NULL, it will be used to translate attributes
+ * that are marked as translatable, using gettext().
+ *
+ * If @objects is specified then it must be a #GHashTable that was
+ * created using g_hash_table_new_full() with g_str_hash(),
+ * g_str_equal(), g_free() and g_object_unref(). Any named menus (ie:
+ * those with an * id='' attribute) that are encountered while parsing
+ * will be added to this table.
+ *
+ * If @objects is %NULL then named menus will not be supported.
+ *
+ * You should call g_menu_markup_parser_end_menu() from the
+ * corresponding end_element function in order to collect the newly
+ * parsed menu.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_markup_print_stderr:
+ * @model: a #GMenuModel
+ *
+ * Print @model to stderr for debugging purposes.
+ *
+ * This debugging function will be removed in the future.
+ */
+
+
+/**
+ * g_menu_markup_print_string:
+ * @string: a #GString
+ * @model: the #GMenuModel to print
+ * @indent: the intentation level to start at
+ * @tabstop: how much to indent each level
+ *
+ * Print the contents of @model to @string.
+ * Note that you have to provide the containing
+ * <tag class="starttag">menu</tag> element yourself.
+ *
+ * Returns: @string
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_get_item_attribute:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @attribute: the attribute to query
+ * @format_string: a #GVariant format string
+ * @...: positional parameters, as per @format_string
+ *
+ * Queries item at position @item_index in @model for the attribute
+ * specified by @attribute.
+ *
+ * If the attribute exists and matches the #GVariantType corresponding
+ * to @format_string then @format_string is used to deconstruct the
+ * value into the positional parameters and %TRUE is returned.
+ *
+ * If the attribute does not exist, or it does exist but has the wrong
+ * type, then the positional parameters are ignored and %FALSE is
+ * returned.
+ *
+ * type
+ *
+ * Returns: %TRUE if the named attribute was found with the expected
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_get_item_attribute_value:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @attribute: the attribute to query
+ * @expected_type: (allow-none): the expected type of the attribute, or %NULL
+ *
+ * Queries the item at position @item_index in @model for the attribute
+ * specified by @attribute.
+ *
+ * If @expected_type is non-%NULL then it specifies the expected type of
+ * the attribute. If it is %NULL then any type will be accepted.
+ *
+ * If the attribute exists and matches @expected_type (or if the
+ * expected type is unspecified) then the value is returned.
+ *
+ * If the attribute does not exist, or does not match the expected type
+ * then %NULL is returned.
+ *
+ * Returns: (transfer full): the value of the attribute
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_get_item_link:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @link: the link to query
+ *
+ * Queries the item at position @item_index in @model for the link
+ * specified by @link.
+ *
+ * If the link exists, the linked #GMenuModel is returned. If the link
+ * does not exist, %NULL is returned.
+ *
+ * Returns: (transfer full): the linked #GMenuModel, or %NULL
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_get_n_items:
+ * @model: a #GMenuModel
+ *
+ * Query the number of items in @model.
+ *
+ * Returns: the number of items
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_is_mutable:
+ * @model: a #GMenuModel
+ *
+ * Queries if @model is mutable.
+ *
+ * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
+ * signal. Consumers of the model may make optimisations accordingly.
+ *
+ * emitted).
+ *
+ * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_items_changed:
+ * @model: a #GMenuModel
+ * @position: the position of the change
+ * @removed: the number of items removed
+ * @added: the number of items added
+ *
+ * Requests emission of the #GMenuModel::items-changed signal on @model.
+ *
+ * This function should never be called except by #GMenuModel
+ * subclasses. Any other calls to this function will very likely lead
+ * to a violation of the interface of the model.
+ *
+ * The implementation should update its internal representation of the
+ * menu before emitting the signal. The implementation should further
+ * expect to receive queries about the new state of the menu (and
+ * particularly added menu items) while signal handlers are running.
+ *
+ * The implementation must dispatch this call directly from a mainloop
+ * entry and not in response to calls -- particularly those from the
+ * #GMenuModel API. Said another way: the menu must not change while
+ * user code is running without returning to the mainloop.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_iterate_item_attributes:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ *
+ * Creates a #GMenuAttributeIter to iterate over the attributes of
+ * the item at position @item_index in @model.
+ *
+ * You must free the iterator with g_object_unref() when you are done.
+ *
+ * Returns: (transfer full): a new #GMenuAttributeIter
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_model_iterate_item_links:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ *
+ * Creates a #GMenuLinkIter to iterate over the links of the item at
+ * position @item_index in @model.
+ *
+ * You must free the iterator with g_object_unref() when you are done.
+ *
+ * Returns: (transfer full): a new #GMenuLinkIter
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_new:
+ *
+ * Creates a new #GMenu.
+ *
+ * The new menu has no items.
+ *
+ * Returns: a new #GMenu
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_prepend:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Convenience function for prepending a normal menu item to the start
+ * of @menu. Combine g_menu_new() and g_menu_insert_item() for a more
+ * flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_prepend_item:
+ * @menu: a #GMenu
+ * @item: a #GMenuItem to prepend
+ *
+ * Prepends @item to the start of @menu.
+ *
+ * See g_menu_insert_item() for more information.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_prepend_section:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Convenience function for prepending a section menu item to the start
+ * of @menu. Combine g_menu_new_section() and g_menu_insert_item() for
+ * a more flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_prepend_submenu:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Convenience function for prepending a submenu menu item to the start
+ * of @menu. Combine g_menu_new_submenu() and g_menu_insert_item() for
+ * a more flexible alternative.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_remove:
+ * @menu: a #GMenu
+ * @position: the position of the item to remove
+ *
+ * Removes an item from the menu.
+ *
+ * @position gives the index of the item to remove.
+ *
+ * It is an error if position is not in range the range from 0 to one
+ * less than the number of items in the menu.
+ *
+ * It is not possible to remove items by identity since items are added
+ * to the menu simply by copying their links and attributes (ie:
+ * identity of the item itself is not preserved).
+ *
+ * Since: 2.32
+ */
+
+
+/**
* g_mount_can_eject:
* @mount: a #GMount.
*
@@ -29811,6 +31669,8 @@
* @network: a #GInetAddressMask
*
* Adds @network to @monitor's list of available networks.
+ *
+ * Since: 2.32
*/
@@ -29820,6 +31680,8 @@
* @network: a #GInetAddressMask
*
* Removes @network from @monitor's list of available networks.
+ *
+ * Since: 2.32
*/
@@ -30201,8 +32063,9 @@
* @cancellable: (allow-none): optional cancellable object
* @error: location to store the error occurring, or %NULL to ignore
*
- * Flushed any outstanding buffers in the stream. Will block during
- * the operation. Closing the stream will implicitly cause a flush.
+ * Forces a write of all user-space buffered data for the given
+ * @stream. Will block during the operation. Closing the stream will
+ * implicitly cause a flush.
*
* This function is optional for inherited classes.
*
@@ -30222,7 +32085,8 @@
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
- * Flushes a stream asynchronously.
+ * Forces an asynchronous write of all user-space buffered data for
+ * the given @stream.
* For behaviour details see g_output_stream_flush().
*
* When the operation is finished @callback will be
@@ -32780,44 +34644,6 @@
* A convenience function for creating multiple #GSimpleAction instances
* and adding them to the action group.
*
- * Each action is constructed as per one #GActionEntry.
- *
- * <example>
- * <title>Using g_simple_action_group_add_entries()</title>
- * <programlisting>
- * static void
- * activate_quit (GSimpleAction *simple,
- * GVariant *parameter,
- * gpointer user_data)
- * {
- * exit (0);
- * }
- *
- * static void
- * activate_print_string (GSimpleAction *simple,
- * GVariant *parameter,
- * gpointer user_data)
- * {
- * g_print ("%s\n", g_variant_get_string (parameter, NULL));
- * }
- *
- * static GActionGroup *
- * create_action_group (void)
- * {
- * const GActionEntry entries[] = {
- * { "quit", activate_quit },
- * { "print-string", activate_print_string, "s" }
- * };
- * GSimpleActionGroup *group;
- *
- * group = g_simple_action_group_new ();
- * g_simple_action_group_add_entries (group, entries, G_N_ELEMENTS (entries), NULL);
- *
- * return G_ACTION_GROUP (group);
- * }
- * </programlisting>
- * </example>
- *
* Since: 2.30
*/
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 4c0302e9..39f1190b 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -209,6 +209,38 @@
/**
+ * GBytes:
+ *
+ * A simple refcounted data type representing an immutable byte sequence
+ * from an unspecified origin.
+ *
+ * The purpose of a #GBytes is to keep the memory region that it holds
+ * alive for as long as anyone holds a reference to the bytes. When
+ * the last reference count is dropped, the memory is released. Multiple
+ * unrelated callers can use byte data in the #GBytes without coordinating
+ * their activities, resting assured that the byte data will not change or
+ * move while they hold a reference.
+ *
+ * A #GBytes can come from many different origins that may have
+ * different procedures for freeing the memory region. Examples are
+ * memory from g_malloc(), from memory slices, from a #GMappedFile or
+ * memory from other allocators.
+ *
+ * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
+ * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
+ * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
+ * function to g_tree_new().
+ *
+ * The data pointed to by this bytes must not be modified. For a mutable
+ * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
+ * mutable array for a #GBytes sequence. To create an immutable #GBytes from
+ * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* GCClosure:
* @closure: the #GClosure
* @callback: the callback function
@@ -703,6 +735,7 @@
/**
* GDoubleIEEE754:
+ * @v_double: the double value
*
* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
* mantissa and exponent of IEEE floats and doubles. These unions are defined
@@ -771,7 +804,7 @@
* @G_ERR_FLOAT_MALFORMED: malformed floating point number
*
* The possible errors, used in the @v_error field
- * of #GTokenValue, when the token is a #G_TOKEN_ERROR.
+ * of #GTokenValue, when the token is a %G_TOKEN_ERROR.
*/
@@ -784,7 +817,8 @@
* @G_FILE_ERROR_NOENT: No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist.
* @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when a directory is required.
* @G_FILE_ERROR_NXIO: No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or not correctly attached to the computer.
- * @G_FILE_ERROR_NODEV: The underlying file system of the specified file does not support memory mapping. G_FILE_ERROR_ROFS: The directory containing the new link can't be modified because it's on a read-only file system.
+ * @G_FILE_ERROR_NODEV: The underlying file system of the specified file does not support memory mapping.
+ * @G_FILE_ERROR_ROFS: The directory containing the new link can't be modified because it's on a read-only file system.
* @G_FILE_ERROR_TXTBSY: Text file busy.
* @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. (GLib won't reliably return this, don't pass in pointers to bad memory.)
* @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links.
@@ -854,6 +888,7 @@
/**
* GFloatIEEE754:
+ * @v_float: the double value
*
* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
* mantissa and exponent of IEEE floats and doubles. These unions are defined
@@ -1052,7 +1087,7 @@
* GHookFlagMask:
* @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed
* @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run
- * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for hook flags; see #G_HOOK_FLAGS_USER_SHIFT
+ * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for hook flags; see %G_HOOK_FLAG_USER_SHIFT
*
* Flags used internally in the #GHook implementation.
*/
@@ -1317,8 +1352,8 @@
/**
* GIOFlags:
- * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the documentation of the UNIX open() syscall).
- * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() syscall).
+ * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal> (see the documentation of the UNIX open() syscall).
+ * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> (see the documentation of the UNIX open() syscall).
* @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag cannot be changed.
* @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. This flag cannot be changed.
* @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that g_io_channel_seek_position() can be used on it. This flag cannot be changed.
@@ -2465,7 +2500,8 @@
* @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR.
* @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
*
- *
+ * Represents a file descriptor, which events to poll for, and which events
+ * occurred.
*/
@@ -2862,6 +2898,12 @@
/**
* GScanner:
+ * @user_data: unused
+ * @max_parse_errors: unused
+ * @parse_errors: g_scanner_error() increments this field
+ * @input_name: name of input stream, featured by the default message handler
+ * @qdata: quarked data
+ * @config: link into the scanner configuration
* @token: token parsed by the last g_scanner_get_next_token()
* @value: value of the last token from g_scanner_get_next_token()
* @line: line number of the last token from g_scanner_get_next_token()
@@ -2870,6 +2912,7 @@
* @next_value: value of the last token from g_scanner_peek_next_token()
* @next_line: line number of the last token from g_scanner_peek_next_token()
* @next_position: char number of the last token from g_scanner_peek_next_token()
+ * @msg_handler: handler function for _warn and _error
*
* The data structure representing a lexical scanner.
*
@@ -2900,7 +2943,7 @@
* @scan_comment_multi: specifies if multi-line comments are recognized (the default is %TRUE).
* @scan_identifier: specifies if identifiers are recognized (the default is %TRUE).
* @scan_identifier_1char: specifies if single-character identifiers are recognized (the default is %FALSE).
- * @scan_identifier_NULL: specifies if %NULL is reported as #G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
+ * @scan_identifier_NULL: specifies if %NULL is reported as %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
* @scan_symbols: specifies if symbols are recognized (the default is %TRUE).
* @scan_binary: specifies if binary numbers are recognized (the default is %FALSE).
* @scan_octal: specifies if octal numbers are recognized (the default is %TRUE).
@@ -2910,11 +2953,12 @@
* @scan_string_sq: specifies if strings can be enclosed in single quotes (the default is %TRUE).
* @scan_string_dq: specifies if strings can be enclosed in double quotes (the default is %TRUE).
* @numbers_2_int: specifies if binary, octal and hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE).
- * @int_2_float: specifies if all numbers are reported as #G_TOKEN_FLOAT (the default is %FALSE).
+ * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT (the default is %FALSE).
* @identifier_2_string: specifies if identifiers are reported as strings (the default is %FALSE).
- * @char_2_token: specifies if characters are reported by setting <literal>token = ch</literal> or as #G_TOKEN_CHAR (the default is %TRUE).
- * @symbol_2_token: specifies if symbols are reported by setting <literal>token = v_symbol</literal> or as #G_TOKEN_SYMBOL (the default is %FALSE).
+ * @char_2_token: specifies if characters are reported by setting <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default is %TRUE).
+ * @symbol_2_token: specifies if symbols are reported by setting <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the default is %FALSE).
* @scope_0_fallback: specifies if a symbol is searched for in the default scope in addition to the current scope (the default is %FALSE).
+ * @store_int64: use value.v_int64 rather than v_int
*
* Specifies the #GScanner parser configuration. Most settings can
* be changed during the parsing phase and will affect the lexical
@@ -3192,7 +3236,7 @@
* call malloc(), which includes POSIX functions such as setenv().
* If you need to set up the child environment differently from
* the parent, you should use g_get_environ(), g_environ_setenv(),
- * and g_environ_unsetev(), and then pass the complete environment
+ * and g_environ_unsetenv(), and then pass the complete environment
* list to the <literal>g_spawn...</literal> function.
*/
@@ -3202,22 +3246,22 @@
* @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
* @G_SPAWN_ERROR_READ: Read or select on pipes failed.
* @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
- * @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
- * @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
- * @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
- * @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
- * @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
- * @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
- * @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
- * @G_SPAWN_ERROR_IO: execv() returned %EIO.
- * @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
- * @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
- * @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
- * @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
- * @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
+ * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
+ * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
+ * @G_SPAWN_ERROR_2BIG: execv() returned <literal>E2BIG</literal>
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
+ * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
+ * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
+ * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
+ * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
+ * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
+ * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
+ * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
+ * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
* @G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error-&gt;message</literal> should explain.
*
* Error codes returned by spawning processes.
@@ -3405,6 +3449,11 @@
/**
* GTime:
*
+ * Simply a replacement for <type>time_t</type>. It has been deprecated
+ * since it is <emphasis>not</emphasis> equivalent to <type>time_t</type>
+ * on 64-bit platforms with a 64-bit <type>time_t</type>.
+ * Unrelated to #GTimer.
+ *
* Note that <type>GTime</type> is defined to always be a 32bit integer,
* unlike <type>time_t</type> which may be 64bit on some systems.
* Therefore, <type>GTime</type> will overflow in the year 2038, and
@@ -3495,6 +3544,20 @@
* @G_TOKEN_LEFT_PAREN: a '(' character
* @G_TOKEN_LEFT_CURLY: a '{' character
* @G_TOKEN_RIGHT_CURLY: a '}' character
+ * @G_TOKEN_RIGHT_PAREN: a ')' character
+ * @G_TOKEN_ERROR: an error occurred
+ * @G_TOKEN_CHAR: a character
+ * @G_TOKEN_BINARY: a binary integer
+ * @G_TOKEN_OCTAL: an octal integer
+ * @G_TOKEN_INT: an integer
+ * @G_TOKEN_HEX: a hex integer
+ * @G_TOKEN_FLOAT: a floating point number
+ * @G_TOKEN_STRING: a string
+ * @G_TOKEN_SYMBOL: a symbol
+ * @G_TOKEN_IDENTIFIER: an identifier
+ * @G_TOKEN_IDENTIFIER_NULL: a null identifier
+ * @G_TOKEN_COMMENT_SINGLE: one line comment
+ * @G_TOKEN_COMMENT_MULTI: multi line comment
*
* The possible types of token returned from each
* g_scanner_get_next_token() call.
@@ -3503,6 +3566,18 @@
/**
* GTokenValue:
+ * @v_symbol: token symbol value
+ * @v_identifier: token identifier value
+ * @v_binary: token binary integer value
+ * @v_octal: octal integer value
+ * @v_int: integer value
+ * @v_int64: 64-bit integer value
+ * @v_float: floating point value
+ * @v_hex: hex integer value
+ * @v_string: string value
+ * @v_comment: comment value
+ * @v_char: character value
+ * @v_error: error value
*
* A union holding the value of the token.
*/
@@ -4531,7 +4606,7 @@
* Inserts a breakpoint instruction into the code.
*
* On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a %SIGTRAP signal.
+ * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
*/
@@ -4592,7 +4667,7 @@
/**
* G_CONST_RETURN:
*
- * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
+ * If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands
* to nothing. By default, the macro expands to <literal>const</literal>.
* The macro should be used in place of <literal>const</literal> for
* functions that return a value that should not be modified. The
@@ -4961,7 +5036,7 @@
* (GInstanceInitFunc) gtk_gadget_init,
* (GTypeFlags) flags);
* {
- * static const GInterfaceInfo g_implement_interface_info = {
+ * const GInterfaceInfo g_implement_interface_info = {
* (GInterfaceInitFunc) gtk_gadget_gizmo_init
* };
* g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
@@ -5641,7 +5716,7 @@
* G_HOOK_FLAGS:
* @hook: a #GHook
*
- * Returns the flags of a hook.
+ * Gets the flags of a hook.
*/
@@ -5767,7 +5842,7 @@
*
* This macro is used to export function prototypes so they can be linked
* with an external version when no inlining is performed. The file which
- * implements the functions should define %G_IMPLEMENTS_INLINES
+ * implements the functions should define <literal>G_IMPLEMENTS_INLINES</literal>
* before including the headers which contain %G_INLINE_FUNC declarations.
* Since inlining is very compiler-dependent using these macros correctly
* is very difficult. Their use is strongly discouraged.
@@ -6436,7 +6511,7 @@
* G_LOCK_DEFINE:
* @name: the name of the lock
*
- * The %G_LOCK_* macros provide a convenient interface to #GMutex.
+ * The <literal>G_LOCK_*</literal> macros provide a convenient interface to #GMutex.
* #G_LOCK_DEFINE defines a lock. It can appear in any place where
* variable definitions may appear in programs, i.e. in the first block
* of a function or outside of functions. The @name parameter will be
@@ -6444,10 +6519,10 @@
* can use names of existing variables as the parameter - e.g. the name
* of the variable you intend to protect with the lock. Look at our
* <function>give_me_next_number()</function> example using the
- * %G_LOCK_* macros:
+ * <literal>G_LOCK_*</literal> macros:
*
* <example>
- * <title>Using the %G_LOCK_* convenience macros</title>
+ * <title>Using the <literal>G_LOCK_*</literal> convenience macros</title>
* <programlisting>
* G_LOCK_DEFINE (current_number);
*
@@ -7730,6 +7805,15 @@
/**
+ * G_TYPE_BYTES:
+ *
+ * The #GType for #GBytes.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* G_TYPE_BYTE_ARRAY:
*
* The #GType for a boxed type holding a #GByteArray reference.
@@ -8720,6 +8804,18 @@
/**
+ * G_UNICHAR_MAX_DECOMPOSITION_LENGTH:
+ *
+ * The maximum length (in codepoints) of a compatibility or canonical
+ * decomposition of a single Unicode character.
+ *
+ * This is as defined by Unicode 6.1.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* G_UNICODE_COMBINING_MARK:
*
* Older name for %G_UNICODE_SPACING_MARK.
@@ -8740,8 +8836,8 @@
* It is expected that most code will not look at %errno from these
* APIs. Important cases where one would want to differentiate between
* errors are already covered by existing cross-platform GLib API,
- * such as e.g. #GFile wrapping %ENOENT. However, it is provided for
- * completeness, at least.
+ * such as e.g. #GFile wrapping <literal>ENOENT</literal>. However, it is
+ * provided for completeness, at least.
*/
@@ -9561,15 +9657,13 @@
/**
* SECTION:arrays_byte
* @title: Byte Arrays
- * @short_description: arrays of bytes, which grow automatically as elements are added
- *
- * #GByteArray is based on #GArray, to provide arrays of bytes which
- * grow automatically as elements are added.
+ * @short_description: arrays of bytes
*
- * To create a new #GByteArray use g_byte_array_new().
+ * #GByteArray is a mutable array of bytes based on #GArray, to provide arrays
+ * of bytes which grow automatically as elements are added.
*
- * To add elements to a #GByteArray, use g_byte_array_append(), and
- * g_byte_array_prepend().
+ * To create a new #GByteArray use g_byte_array_new(). To add elements to a
+ * #GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
*
* To set the size of a #GByteArray, use g_byte_array_set_size().
*
@@ -9596,6 +9690,9 @@
* g_byte_array_free (gbarray, TRUE);
* </programlisting>
* </example>
+ *
+ * See #GBytes if you are interested in an immutable object representing a
+ * sequence of bytes.
*/
@@ -10400,7 +10497,7 @@
* If there's a "generic" or "unknown" error code for unrecoverable
* errors it doesn't make sense to distinguish with specific codes,
* it should be called <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</literal>,
- * for example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
+ * for example %G_SPAWN_ERROR_FAILED.
* </para></listitem>
* </itemizedlist>
*
@@ -12489,7 +12586,7 @@
* Note that it is not safe to assume that your program has no threads
* even if you don't call g_thread_new() yourself. GLib and GIO can
* and will create threads for their own purposes in some cases, such
- * as when using g_unix_signal_source_new() or when using #GDBus.
+ * as when using g_unix_signal_source_new() or when using GDBus.
*
* Originally, UNIX did not have threads, and therefore some traditional
* UNIX APIs are problematic in threaded programs. Some notable examples
@@ -13130,8 +13227,8 @@
* greater than second arg).
*
* If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order &#8211; i.e.
- * you want a stable sort &#8211; you can write a comparison function that,
+ * is undefined. If you want equal elements to keep their order (i.e.
+ * you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
*/
@@ -13224,7 +13321,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII alphanumeric character
@@ -13241,7 +13338,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII alphabetic character
@@ -13258,7 +13355,7 @@
* recognizes standard ASCII control characters and ignores the
* locale, returning %FALSE for all non-ASCII characters. Also,
* unlike the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII control character.
@@ -13273,7 +13370,7 @@
*
* Unlike the standard C library isdigit() function, this takes
* a <type>char</type>, not an <type>int</type>, so don't call it
- * on %EOF, but no need to cast to #guchar before passing a possibly
+ * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
* non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII digit.
@@ -13290,7 +13387,7 @@
* recognizes standard ASCII characters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII printing character other than space.
@@ -13307,7 +13404,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to worry about casting to #guchar before passing a possibly
* non-ASCII character in.
*
@@ -13325,7 +13422,7 @@
* recognizes standard ASCII characters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII printing character.
@@ -13342,7 +13439,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII punctuation character.
@@ -13359,7 +13456,7 @@
* recognizes standard ASCII white-space and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII white-space character
@@ -13376,7 +13473,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* worry about casting to #guchar before passing a possibly non-ASCII
* character in.
*
@@ -13392,7 +13489,7 @@
*
* Unlike the standard C library isxdigit() function, this takes
* a <type>char</type>, not an <type>int</type>, so don't call it
- * on %EOF, but no need to cast to #guchar before passing a
+ * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
* possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
@@ -13484,12 +13581,12 @@
* To convert from a #gdouble to a string in a locale-insensitive
* way, use g_ascii_dtostr().
*
- * If the correct value would cause overflow, plus or minus %HUGE_VAL
- * is returned (according to the sign of the value), and %ERANGE is
- * stored in %errno. If the correct value would cause underflow,
- * zero is returned and %ERANGE is stored in %errno.
+ * If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
+ * is returned (according to the sign of the value), and <literal>ERANGE</literal> is
+ * stored in <literal>errno</literal>. If the correct value would cause underflow,
+ * zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
*
- * This function resets %errno before calling strtod() so that
+ * This function resets <literal>errno</literal> before calling strtod() so that
* you can reliably detect overflow and underflow.
*
* Returns: the #gdouble value.
@@ -13514,10 +13611,11 @@
* locale-sensitive system strtoll() function.
*
* If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
- * is returned, and %ERANGE is stored in %errno. If the base is
- * outside the valid range, zero is returned, and %EINVAL is stored
- * in %errno. If the string conversion fails, zero is returned, and
- * @endptr returns @nptr (if @endptr is non-%NULL).
+ * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * If the base is outside the valid range, zero is returned, and
+ * <literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
+ * string conversion fails, zero is returned, and @endptr returns @nptr
+ * (if @endptr is non-%NULL).
*
* Returns: the #gint64 value or zero on error.
* Since: 2.12
@@ -13542,10 +13640,11 @@
* locale-sensitive system strtoull() function.
*
* If the correct value would cause overflow, %G_MAXUINT64
- * is returned, and %ERANGE is stored in %errno. If the base is
- * outside the valid range, zero is returned, and %EINVAL is stored
- * in %errno. If the string conversion fails, zero is returned, and
- * @endptr returns @nptr (if @endptr is non-%NULL).
+ * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * If the base is outside the valid range, zero is returned, and
+ * <literal>EINVAL</literal> is stored in <literal>errno</literal>.
+ * If the string conversion fails, zero is returned, and @endptr returns
+ * @nptr (if @endptr is non-%NULL).
*
* Returns: the #guint64 value or zero on error.
* Since: 2.2
@@ -13579,7 +13678,7 @@
* all non-ASCII characters unchanged, even if they are lower case
* letters in a particular character set. Also unlike the standard
* library function, this takes and returns a char, not an int, so
- * don't call it on %EOF but no need to worry about casting to #guchar
+ * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
*
* If @c is not an ASCII upper case letter,
@@ -13600,7 +13699,7 @@
* all non-ASCII characters unchanged, even if they are upper case
* letters in a particular character set. Also unlike the standard
* library function, this takes and returns a char, not an int, so
- * don't call it on %EOF but no need to worry about casting to #guchar
+ * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
*
* If @c is not an ASCII lower case letter,
@@ -13634,7 +13733,7 @@
* an error message is logged and the application is terminated.
*
* The macro can be turned off in final releases of code by defining
- * #G_DISABLE_ASSERT when compiling the application.
+ * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
*/
@@ -13778,7 +13877,7 @@
* application is terminated.
*
* The macro can be turned off in final releases of code by defining
- * #G_DISABLE_ASSERT when compiling the application.
+ * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
*/
@@ -15526,6 +15625,27 @@
/**
+ * g_byte_array_free_to_bytes:
+ * @array: (transfer full): a #GByteArray
+ *
+ * Transfers the data from the #GByteArray into a new immutable #GBytes.
+ *
+ * The #GByteArray is freed unless the reference count of @array is greater
+ * than one, the #GByteArray wrapper is preserved but the size of @array
+ * will be set to zero.
+ *
+ * This is identical to using g_bytes_new_take() and g_byte_array_free()
+ * together.
+ *
+ *
+ * data that was in the array
+ *
+ * Since: 2.32
+ * Returns: (transfer full): a new immutable #GBytes representing same byte
+ */
+
+
+/**
* g_byte_array_new:
* @Returns: the new #GByteArray.
*
@@ -15534,6 +15654,19 @@
/**
+ * g_byte_array_new_take:
+ * @data: (array length=len): byte data for the array
+ * @len: length of @data
+ *
+ * Create byte array containing the data. The data will be owned by the array
+ * and will be freed with g_free(), i.e. it could be allocated using g_strdup().
+ *
+ * Since: 2.32
+ * Returns: (transfer full): a new #GByteArray
+ */
+
+
+/**
* g_byte_array_prepend:
* @array: a #GByteArray.
* @data: the byte data to be added.
@@ -15628,8 +15761,8 @@
* first arg is greater than second arg).
*
* If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order &#8211; i.e.
- * you want a stable sort &#8211; you can write a comparison function that,
+ * is undefined. If you want equal elements to keep their order (i.e.
+ * you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
*/
@@ -15660,6 +15793,223 @@
/**
+ * g_bytes_compare:
+ * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
+ * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
+ *
+ * Compares the two #GBytes values.
+ *
+ * This function can be used to sort GBytes instances in lexographical order.
+ *
+ * greater, and zero if bytes2 is equal to bytes1
+ *
+ * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_equal:
+ * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
+ * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
+ *
+ * Compares the two #GBytes values being pointed to and returns
+ * %TRUE if they are equal.
+ *
+ * This function can be passed to g_hash_table_new() as the @key_equal_func
+ * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
+ *
+ * Returns: %TRUE if the two keys match.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_get_data:
+ * @bytes: a #GBytes
+ * @size: (out) (allow-none): location to return size of byte data
+ *
+ * Get the byte data in the #GBytes. This data should not be modified.
+ *
+ * This function will always return the same pointer for a given #GBytes.
+ *
+ * Returns: (array length=size) (type guint8): a pointer to the byte data
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_get_size:
+ * @bytes: a #GBytes
+ *
+ * Get the size of the byte data in the #GBytes.
+ *
+ * This function will always return the same value for a given #GBytes.
+ *
+ * Returns: the size
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_hash:
+ * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
+ *
+ * Creates an integer hash code for the byte data in the #GBytes.
+ *
+ * This function can be passed to g_hash_table_new() as the @key_equal_func
+ * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
+ *
+ * Returns: a hash value corresponding to the key.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_new:
+ * @data: (array length=size): the data to be used for the bytes
+ * @size: the size of @data
+ *
+ * Creates a new #GBytes from @data.
+ *
+ * @data is copied.
+ *
+ * Returns: (transfer full): a new #GBytes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_new_from_bytes:
+ * @bytes: a #GBytes
+ * @offset: offset which subsection starts at
+ * @length: length of subsection
+ *
+ * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
+ * @length may not be longer than the size of @bytes.
+ *
+ * A reference to @bytes will be held by the newly created #GBytes until
+ * the byte data is no longer needed.
+ *
+ * Returns: (transfer full): a new #GBytes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_new_static:
+ * @data: (array length=size): the data to be used for the bytes
+ * @size: the size of @data
+ * @data must be static (ie: never modified or freed).
+ *
+ * Creates a new #GBytes from static data.
+ *
+ * Returns: (transfer full): a new #GBytes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_new_take:
+ * @data: (transfer full) (array length=size): the data to be used for the bytes
+ * @size: the size of @data
+ *
+ * Creates a new #GBytes from @data.
+ *
+ * After this call, @data belongs to the bytes and may no longer be
+ * modified by the caller. g_free() will be called on @data when the
+ * bytes is no longer in use. Because of this @data must have been created by
+ * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
+ * functions that wrap these calls (such as g_new(), g_strdup(), etc).
+ *
+ * For creating #GBytes with memory from other allocators, see
+ * g_bytes_new_with_free_func().
+ *
+ * Returns: (transfer full): a new #GBytes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_new_with_free_func:
+ * @data: (array length=size): the data to be used for the bytes
+ * @size: the size of @data
+ * @free_func: the function to call to release the data
+ * @user_data: data to pass to @free_func
+ *
+ * Creates a #GBytes from @data.
+ *
+ * When the last reference is dropped, @free_func will be called with the
+ * @user_data argument.
+ *
+ * @data must not be modified after this call is made until @free_func has
+ * been called to indicate that the bytes is no longer in use.
+ *
+ * Returns: (transfer full): a new #GBytes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_ref:
+ * @bytes: a #GBytes
+ *
+ * Increase the reference count on @bytes.
+ *
+ * Returns: the #GBytes
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_unref:
+ * @bytes: (allow-none): a #GBytes
+ *
+ * Releases a reference on @bytes. This may result in the bytes being
+ * freed.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_unref_to_array:
+ * @bytes: (transfer full): a #GBytes
+ *
+ * Unreferences the bytes, and returns a new mutable #GByteArray containing
+ * the same byte data.
+ *
+ * As an optimization, the byte data is transferred to the array without copying
+ * if this was the last reference to bytes and bytes was created with
+ * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
+ * other cases the data is copied.
+ *
+ * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
+ * Since: 2.32
+ */
+
+
+/**
+ * g_bytes_unref_to_data:
+ * @bytes: (transfer full): a #GBytes
+ * @size: location to place the length of the returned data
+ *
+ * Unreferences the bytes, and returns a pointer the same byte data
+ * contents.
+ *
+ * As an optimization, the byte data is returned without copying if this was
+ * the last reference to bytes and bytes was created with g_bytes_new(),
+ * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
+ * data is copied.
+ *
+ * be freed with g_free()
+ *
+ * Returns: (transfer full): a pointer to the same byte data, which should
+ * Since: 2.32
+ */
+
+
+/**
* g_chdir:
* @path: a pathname in the GLib file name encoding (UTF-8 on Windows)
*
@@ -16265,7 +16615,7 @@
* example.
*
* You can also make critical warnings fatal at runtime by
- * setting the %G_DEBUG environment variable (see
+ * setting the <envar>G_DEBUG</envar> environment variable (see
* <ulink url="glib-running.html">Running GLib Applications</ulink>).
*/
@@ -16672,6 +17022,7 @@
/**
* g_date_free:
+ * @date: a #GDate to free
*
* Frees a #GDate returned from g_date_new().
*/
@@ -16796,6 +17147,8 @@
* year. This function is basically telling you how many
* Sundays are in the year, i.e. there are 53 Sundays if
* one of the extra days happens to be a Sunday.)
+ *
+ * Returns: the number of weeks in @year
*/
@@ -16884,8 +17237,8 @@
/**
* g_date_new_julian:
+ * @julian_day: days since January 1, Year 1
*
- * julian_day: days since January 1, Year 1
* Like g_date_new(), but also sets the value of the date. Assuming the
* Julian day number you pass in is valid (greater than 0, less than an
* unreasonably large number), the returned date will be valid.
@@ -18215,7 +18568,7 @@
* @category: a locale category
*
* This is a variant of g_dgettext() that allows specifying a locale
- * category instead of always using %LC_MESSAGES. See g_dgettext() for
+ * category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for
* more information about how this functions differs from calling
* dcgettext() directly.
*
@@ -18654,9 +19007,9 @@
* g_file_error_from_errno:
* @err_no: an "errno" value
*
- * Gets a #GFileError constant based on the passed-in @errno.
- * For example, if you pass in %EEXIST this function returns
- * #G_FILE_ERROR_EXIST. Unlike @errno values, you can portably
+ * Gets a #GFileError constant based on the passed-in @err_no.
+ * For example, if you pass in <literal>EEXIST</literal> this function returns
+ * #G_FILE_ERROR_EXIST. Unlike <literal>errno</literal> values, you can portably
* assume that all #GFileError values will exist.
*
* Normally a #GFileError value goes into a #GError returned
@@ -18824,7 +19177,7 @@
* %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
* %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
* its name indicates that it is executable, checking for well-known
- * extensions and those listed in the %PATHEXT environment variable.
+ * extensions and those listed in the <envar>PATHEXT</envar> environment variable.
*
* Returns: whether a test was %TRUE
*/
@@ -19101,7 +19454,7 @@
*
* opened, or %NULL if an error occurred.
*
- * Returns: A <type>FILE</type> pointer if the file was successfully
+ * Returns: A <literal>FILE</literal> pointer if the file was successfully
* Since: 2.6
*/
@@ -19342,13 +19695,13 @@
*
* Queries the system monotonic time, if available.
*
- * On POSIX systems with clock_gettime() and %CLOCK_MONOTONIC this call
+ * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call
* is a very shallow wrapper for that. Otherwise, we make a best effort
* that probably involves returning the wall clock time (with at least
* microsecond accuracy, subject to the limitations of the OS kernel).
*
- * It's important to note that POSIX %CLOCK_MONOTONIC does not count
- * time spent while the machine is suspended.
+ * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does
+ * not count time spent while the machine is suspended.
*
* On Windows, "limitations of the OS kernel" is a rather substantial
* statement. Depending on the configuration of the system, the wall
@@ -20825,7 +21178,7 @@
/**
* g_io_channel_error_from_errno:
- * @en: an <literal>errno</literal> error number, e.g. %EINVAL
+ * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal>
*
* Converts an <literal>errno</literal> error number to a #GIOChannelError.
*
@@ -21213,7 +21566,7 @@
* @flags: the flags to set on the IO channel
* @error: A location to return an error of type #GIOChannelError
*
- * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
+ * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
*
* Returns: the status of the operation.
*/
@@ -22802,7 +23155,7 @@
* %G_LOG_LEVEL_ERROR is always fatal.
*
* You can also make some message levels fatal at runtime by setting
- * the %G_DEBUG environment variable (see
+ * the <envar>G_DEBUG</envar> environment variable (see
* <ulink url="glib-running.html">Running GLib Applications</ulink>).
*
* Returns: the old fatal mask
@@ -24505,7 +24858,7 @@
* g_mem_gc_friendly:
*
* This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
- * includes the key <link linkend="G_DEBUG">gc-friendly</link>.
+ * includes the key <literal>gc-friendly</literal>.
*/
@@ -26512,8 +26865,8 @@
* greater than second arg).
*
* If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order &#8211; i.e.
- * you want a stable sort &#8211; you can write a comparison function that,
+ * is undefined. If you want equal elements to keep their order (i.e.
+ * you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
*
@@ -27389,7 +27742,7 @@
/**
* g_rec_mutex_unlock:
- * @rec_mutex: a #RecGMutex
+ * @rec_mutex: a #GRecMutex
*
* Unlocks @rec_mutex. If another thread is blocked in a
* g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
@@ -28551,8 +28904,8 @@
* g_scanner_unexp_token:
* @scanner: a #GScanner
* @expected_token: the expected token
- * @identifier_spec: a string describing how the scanner's user refers to identifiers (%NULL defaults to "identifier"). This is used if @expected_token is #G_TOKEN_IDENTIFIER or #G_TOKEN_IDENTIFIER_NULL.
- * @symbol_spec: a string describing how the scanner's user refers to symbols (%NULL defaults to "symbol"). This is used if @expected_token is #G_TOKEN_SYMBOL or any token value greater than #G_TOKEN_LAST.
+ * @identifier_spec: a string describing how the scanner's user refers to identifiers (%NULL defaults to "identifier"). This is used if @expected_token is %G_TOKEN_IDENTIFIER or %G_TOKEN_IDENTIFIER_NULL.
+ * @symbol_spec: a string describing how the scanner's user refers to symbols (%NULL defaults to "symbol"). This is used if @expected_token is %G_TOKEN_SYMBOL or any token value greater than %G_TOKEN_LAST.
* @symbol_name: the name of the symbol, if the scanner's current token is a symbol.
* @message: a message string to output at the end of the warning/error, or %NULL.
* @is_error: if %TRUE it is output as an error. If %FALSE it is output as a warning.
@@ -30553,7 +30906,7 @@
* will only be searched if you pass the %G_SPAWN_SEARCH_PATH flag.
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
* used, then the program will be run from the current directory (or
- * %working_directory, if specified); this might be unexpected or even
+ * @working_directory, if specified); this might be unexpected or even
* dangerous in some cases when the current directory is world-writable.
*
* On Windows, note that all the string or string vector arguments to
@@ -30607,7 +30960,7 @@
* call g_spawn_close_pid() on the @child_pid, in order to free
* resources which may be associated with the child process. (On Unix,
* using a child watch is equivalent to calling waitpid() or handling
- * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
+ * the <literal>SIGCHLD</literal> signal manually. On Windows, calling g_spawn_close_pid()
* is equivalent to calling CloseHandle() on the process handle returned
* in @child_pid). See g_child_watch_add().
*
@@ -32210,10 +32563,10 @@
* Create a new #GTestCase, named @test_name, this API is fairly
* low level, calling g_test_add() or g_test_add_func() is preferable.
* When this test is executed, a fixture structure of size @data_size
- * will be allocated and filled with 0s. Then data_setup() is called
+ * will be allocated and filled with 0s. Then @data_setup is called
* to initialize the fixture. After fixture setup, the actual test
- * function data_test() is called. Once the test run completed, the
- * fixture structure is torn down by calling data_teardown() and
+ * function @data_test is called. Once the test run completed, the
+ * fixture structure is torn down by calling @data_teardown and
* after that the memory is released.
*
* Splitting up a test run into fixture setup, test function and
@@ -32472,7 +32825,7 @@
* @destroy_func: Destroy callback for teardown phase.
* @destroy_data: Destroy callback data.
*
- * This function enqueus a callback @destroy_func() to be executed
+ * This function enqueus a callback @destroy_func to be executed
* during the next test case teardown phase. This is most useful
* to auto destruct allocted test resources at the end of a test run.
* Resources are released in reverse queue order, that means enqueueing
@@ -34320,7 +34673,8 @@
* this may change in the future (very unlikely though).
* At any rate, Unicode does guarantee that a buffer of length
* 18 is always enough for both compatibility and canonical
- * decompositions.
+ * decompositions, so that is the size recommended. This is provided
+ * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
*
* See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
* for details.
@@ -34761,12 +35115,13 @@
* Similar to the UNIX pipe() call, but on modern systems like Linux
* uses the pipe2() system call, which atomically creates a pipe with
* the configured flags. The only supported flag currently is
- * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK,
- * that must still be done separately with fcntl().
+ * <literal>FD_CLOEXEC</literal>. If for example you want to configure
+ * <literal>O_NONBLOCK</literal>, that must still be done separately with
+ * fcntl().
*
- * <note>This function does *not* take %O_CLOEXEC, it takes
- * %FD_CLOEXEC as if for fcntl(); these are different on
- * Linux/glibc.</note>
+ * <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
+ * <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
+ * different on Linux/glibc.</note>
*
* Returns: %TRUE on success, %FALSE if not (and errno will be set).
* Since: 2.30
@@ -34780,8 +35135,8 @@
* @error: a #GError
*
* Control the non-blocking state of the given file descriptor,
- * according to @nonblock. On most systems this uses %O_NONBLOCK, but
- * on some older ones may use %O_NDELAY.
+ * according to @nonblock. On most systems this uses <literal>O_NONBLOCK</literal>, but
+ * on some older ones may use <literal>O_NDELAY</literal>.
*
* Returns: %TRUE if successful
* Since: 2.30
@@ -34825,12 +35180,13 @@
* @signum: A signal number
*
* Create a #GSource that will be dispatched upon delivery of the UNIX
- * signal @signum. Currently only %SIGHUP, %SIGINT, and %SIGTERM can
+ * signal @signum. Currently only <literal>SIGHUP</literal>,
+ * <literal>SIGINT</literal>, and <literal>SIGTERM</literal> can
* be monitored. Note that unlike the UNIX default, all sources which
* have created a watch will be dispatched, regardless of which
* underlying thread invoked g_unix_signal_source_new().
*
- * For example, an effective use of this function is to handle SIGTERM
+ * For example, an effective use of this function is to handle <literal>SIGTERM</literal>
* cleanly; flushing any outstanding files, and then calling
* g_main_loop_quit (). It is not safe to do any of this a regular
* UNIX signal handler; your handler may be invoked while malloc() or
@@ -38366,7 +38722,7 @@
* A convenience function/macro to log a warning message.
*
* You can make warnings fatal at runtime by setting the
- * %G_DEBUG environment variable (see
+ * <envar>G_DEBUG</envar> environment variable (see
* <ulink url="glib-running.html">Running GLib Applications</ulink>).
*/
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index e5c2eaae..16d8491d 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -1301,7 +1301,8 @@
* @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR.
* @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
*
- *
+ * Represents a file descriptor, which events to poll for, and which events
+ * occurred.
*/
@@ -1667,7 +1668,7 @@
* call malloc(), which includes POSIX functions such as setenv().
* If you need to set up the child environment differently from
* the parent, you should use g_get_environ(), g_environ_setenv(),
- * and g_environ_unsetev(), and then pass the complete environment
+ * and g_environ_unsetenv(), and then pass the complete environment
* list to the <literal>g_spawn...</literal> function.
*/
@@ -1677,22 +1678,22 @@
* @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
* @G_SPAWN_ERROR_READ: Read or select on pipes failed.
* @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
- * @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
- * @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
- * @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
- * @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
- * @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
- * @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
- * @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
- * @G_SPAWN_ERROR_IO: execv() returned %EIO.
- * @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
- * @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
- * @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
- * @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
- * @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
+ * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
+ * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
+ * @G_SPAWN_ERROR_2BIG: execv() returned <literal>E2BIG</literal>
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
+ * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
+ * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
+ * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
+ * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
+ * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
+ * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
+ * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
+ * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
* @G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error-&gt;message</literal> should explain.
*
* Error codes returned by spawning processes.
@@ -2332,7 +2333,7 @@
* Inserts a breakpoint instruction into the code.
*
* On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a %SIGTRAP signal.
+ * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
*/
@@ -2674,7 +2675,7 @@
* (GInstanceInitFunc) gtk_gadget_init,
* (GTypeFlags) flags);
* {
- * static const GInterfaceInfo g_implement_interface_info = {
+ * const GInterfaceInfo g_implement_interface_info = {
* (GInterfaceInitFunc) gtk_gadget_gizmo_init
* };
* g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
@@ -3765,6 +3766,15 @@
/**
+ * G_TYPE_BYTES:
+ *
+ * The #GType for #GBytes.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* G_TYPE_BYTE_ARRAY:
*
* The #GType for a boxed type holding a #GByteArray reference.
@@ -4755,6 +4765,18 @@
/**
+ * G_UNICHAR_MAX_DECOMPOSITION_LENGTH:
+ *
+ * The maximum length (in codepoints) of a compatibility or canonical
+ * decomposition of a single Unicode character.
+ *
+ * This is as defined by Unicode 6.1.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* G_UNICODE_COMBINING_MARK:
*
* Older name for %G_UNICODE_SPACING_MARK.
@@ -5776,9 +5798,9 @@
/**
* SECTION:objects
+ * @title: GObject
* @short_description: The base object type
* @see_also: #GParamSpecObject, g_param_spec_object()
- * @title: The Base Object Type
*
* GObject is the fundamental type providing the common attributes and
* methods for all object types in GTK+, Pango and other libraries
@@ -6764,7 +6786,7 @@
* @info: the #GTypeInfo struct to be filled in
* @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0.
*
- * This function is meant to be called from the complete_type_info()
+ * This function is meant to be called from the <literal>complete_type_info</literal>
* function of a #GTypePlugin implementation, as in the following
* example:
*