diff options
Diffstat (limited to 'gir/gio-2.0.c')
| -rw-r--r-- | gir/gio-2.0.c | 2138 |
1 files changed, 1982 insertions, 156 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->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#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 */ |