* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
- * USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* Author: Ryan Lortie <desrt@desrt.ca>
*/
+#include "config.h"
+
#include "gmenumodel.h"
/**
* SECTION:gmenumodel
* @title: GMenuModel
* @short_description: An abstract class representing the contents of a menu
+ * @include: gio/gio.h
* @see_also: #GActionGroup
*
* #GMenuModel represents the contents of a menu -- an ordered list of
* 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"/>.
+ * As an example, consider the visible portions of this menu:
+ *
+ * ## An example menu # {#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
+ *
+ * - the toplevel menubar (containing 4 items)
+ * - the View submenu (containing 3 sections)
+ * - the first section of the View submenu (containing 2 items)
+ * - the second section of the View submenu (containing 1 item)
+ * - the final section of the View submenu (containing 1 item)
+ * - the Highlight Mode submenu (containing 2 sections)
+ * - the Sources section (containing 2 items)
+ * - the Markup section (containing 2 items)
+ *
+ * The [example][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>
+ * ## A menu example # {#menu-model}
+ *
+ * 
*
- * Notice that the separators visible in <xref linkend="menu-example"/>
- * appear nowhere in <xref linkend="menu-model"/>. This is because
+ * Notice that the separators visible in the [example][menu-example]
+ * appear nowhere in the [menu model][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,
* 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
- * #GMenuProxy.
+ * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
+ * and the [GMenuModel exporter][gio-GMenuModel-exporter] 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()
* %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
* and %G_MENU_LINK_SUBMENU.
*
- * FIXME: explain how items are associated with actions.
+ * 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>
+ * - an action with no parameter type and no state
+ * - an action with no parameter type and boolean state
+ * - an action with string parameter type and string state
+ *
+ * ## Stateless
+ *
* 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>
+ * ## Boolean State
+ *
* 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>
+ * ## String Parameter and State
+ *
* 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>
*/
/**
*
* #GMenuModel 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
+ */
/**
* GMenuLinkIter:
*
* #GMenuLinkIter is an opaque structure type. You must access it using
* the functions below.
- **/
+ *
+ * Since: 2.32
+ */
typedef struct
{
typedef GMenuLinkIterClass GMenuLinkHashIterClass;
+static GType g_menu_link_hash_iter_get_type (void);
+
G_DEFINE_TYPE (GMenuLinkHashIter, g_menu_link_hash_iter, G_TYPE_MENU_LINK_ITER)
static gboolean
typedef GMenuAttributeIterClass GMenuAttributeHashIterClass;
+static GType g_menu_attribute_hash_iter_get_type (void);
+
G_DEFINE_TYPE (GMenuAttributeHashIter, g_menu_attribute_hash_iter, G_TYPE_MENU_ATTRIBUTE_ITER)
static gboolean
G_DEFINE_ABSTRACT_TYPE (GMenuModel, g_menu_model, G_TYPE_OBJECT)
-guint g_menu_model_items_changed_signal;
+static guint g_menu_model_items_changed_signal;
static GMenuAttributeIter *
g_menu_model_real_iterate_item_attributes (GMenuModel *model,
else
g_assert_not_reached ();
+ if (value != NULL)
+ g_object_ref (value);
+
if (table != NULL)
g_hash_table_unref (table);
- return value ? g_object_ref (value) : NULL;
+ return value;
}
static void
* signal. Consumers of the model may make optimisations accordingly.
*
* Returns: %TRUE if the model is mutable (ie: "items-changed" may be
- * emitted).
- **/
+ * emitted).
+ *
+ * Since: 2.32
+ */
gboolean
g_menu_model_is_mutable (GMenuModel *model)
{
* Query the number of items in @model.
*
* Returns: the number of items
- **/
+ *
+ * Since: 2.32
+ */
gint
g_menu_model_get_n_items (GMenuModel *model)
{
* You must free the iterator with g_object_unref() when you are done.
*
* Returns: (transfer full): a new #GMenuAttributeIter
+ *
+ * Since: 2.32
*/
GMenuAttributeIter *
g_menu_model_iterate_item_attributes (GMenuModel *model,
* then %NULL is returned.
*
* Returns: (transfer full): the value of the attribute
- **/
+ *
+ * Since: 2.32
+ */
GVariant *
g_menu_model_get_item_attribute_value (GMenuModel *model,
gint item_index,
* type, then the positional parameters are ignored and %FALSE is
* returned.
*
+ * This function is a mix of g_menu_model_get_item_attribute_value() and
+ * g_variant_get(), followed by a g_variant_unref(). As such,
+ * @format_string must make a complete copy of the data (since the
+ * #GVariant may go away after the call to g_variant_unref()). In
+ * particular, no '&' characters are allowed in @format_string.
+ *
* Returns: %TRUE if the named attribute was found with the expected
- * type
- **/
+ * type
+ *
+ * Since: 2.32
+ */
gboolean
g_menu_model_get_item_attribute (GMenuModel *model,
gint item_index,
const gchar *format_string,
...)
{
- const GVariantType *expected_type;
GVariant *value;
va_list ap;
- expected_type = NULL; /* XXX devine the type, ensure no '&' */
+ value = g_menu_model_get_item_attribute_value (model, item_index, attribute, NULL);
- value = g_menu_model_get_item_attribute_value (model, item_index, attribute, expected_type);
if (value == NULL)
return FALSE;
+ if (!g_variant_check_format_string (value, format_string, TRUE))
+ {
+ g_variant_unref (value);
+ return FALSE;
+ }
+
va_start (ap, format_string);
g_variant_get_va (value, format_string, NULL, &ap);
g_variant_unref (value);
* You must free the iterator with g_object_unref() when you are done.
*
* Returns: (transfer full): a new #GMenuLinkIter
- **/
+ *
+ * Since: 2.32
+ */
GMenuLinkIter *
g_menu_model_iterate_item_links (GMenuModel *model,
gint item_index)
* does not exist, %NULL is returned.
*
* Returns: (transfer full): the linked #GMenuModel, or %NULL
- **/
+ *
+ * Since: 2.32
+ */
GMenuModel *
g_menu_model_get_item_link (GMenuModel *model,
gint item_index,
* @removed: the number of items removed
* @added: the number of items added
*
- * Requests emission of the #GMenuMode::items-changed signal on @model.
+ * 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
* 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
+ */
void
g_menu_model_items_changed (GMenuModel *model,
gint position,
g_signal_emit (model, g_menu_model_items_changed_signal, 0, position, removed, added);
}
-G_DEFINE_ABSTRACT_TYPE (GMenuAttributeIter, g_menu_attribute_iter, G_TYPE_OBJECT)
-
struct _GMenuAttributeIterPrivate
{
GQuark name;
gboolean valid;
};
+G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuAttributeIter, g_menu_attribute_iter, G_TYPE_OBJECT)
+
/**
* g_menu_attribute_iter_get_next:
* @iter: a #GMenuAttributeIter
*
* 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.
+ * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_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.
*
* Returns: %TRUE on success, or %FALSE if there is no additional
- * attribute
- **/
+ * attribute
+ *
+ * Since: 2.32
+ */
gboolean
g_menu_attribute_iter_get_next (GMenuAttributeIter *iter,
const gchar **out_name,
* attribute exists at all).
*
* Returns: %TRUE on success, or %FALSE when there are no more attributes
- **/
+ *
+ * Since: 2.32
+ */
gboolean
g_menu_attribute_iter_next (GMenuAttributeIter *iter)
{
* The iterator is not advanced.
*
* Returns: the name of the attribute
- **/
+ *
+ * Since: 2.32
+ */
const gchar *
g_menu_attribute_iter_get_name (GMenuAttributeIter *iter)
{
* The iterator is not advanced.
*
* Returns: (transfer full): the value of the current attribute
- **/
+ *
+ * Since: 2.32
+ */
GVariant *
g_menu_attribute_iter_get_value (GMenuAttributeIter *iter)
{
static void
g_menu_attribute_iter_init (GMenuAttributeIter *iter)
{
- iter->priv = G_TYPE_INSTANCE_GET_PRIVATE (iter, G_TYPE_MENU_ATTRIBUTE_ITER, GMenuAttributeIterPrivate);
+ iter->priv = g_menu_attribute_iter_get_instance_private (iter);
}
static void
GObjectClass *object_class = G_OBJECT_CLASS (class);
object_class->finalize = g_menu_attribute_iter_finalize;
-
- g_type_class_add_private (class, sizeof (GMenuAttributeIterPrivate));
}
-G_DEFINE_ABSTRACT_TYPE (GMenuLinkIter, g_menu_link_iter, G_TYPE_OBJECT)
-
struct _GMenuLinkIterPrivate
{
GQuark name;
gboolean valid;
};
+G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GMenuLinkIter, g_menu_link_iter, G_TYPE_OBJECT)
+
/**
* g_menu_link_iter_get_next:
* @iter: a #GMenuLinkIter
- * @out_name: (out) (allow-none) (transfer none): the name of the link
+ * @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.
+ * 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_name and @value are set to the name and #GMenuModel
+ * 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
+ * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
* same values again.
*
- * The value returned in @out_name remains valid for as long as the iterator
+ * 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
+ */
gboolean
g_menu_link_iter_get_next (GMenuLinkIter *iter,
- const gchar **out_name,
+ const gchar **out_link,
GMenuModel **value)
{
const gchar *name;
g_assert (name != NULL);
iter->priv->name = g_quark_from_string (name);
- if (out_name)
- *out_name = g_quark_to_string (iter->priv->name);
+ if (out_link)
+ *out_link = g_quark_to_string (iter->priv->name);
if (value)
*value = g_object_ref (iter->priv->value);
* at all).
*
* Returns: %TRUE on success, or %FALSE when there are no more links
- **/
+ *
+ * Since: 2.32
+ */
gboolean
g_menu_link_iter_next (GMenuLinkIter *iter)
{
* The iterator is not advanced.
*
* Returns: the type of the link
- **/
+ *
+ * Since: 2.32
+ */
const gchar *
g_menu_link_iter_get_name (GMenuLinkIter *iter)
{
* The iterator is not advanced.
*
* Returns: (transfer full): the #GMenuModel that is linked to
- **/
+ *
+ * Since: 2.32
+ */
GMenuModel *
g_menu_link_iter_get_value (GMenuLinkIter *iter)
{
static void
g_menu_link_iter_init (GMenuLinkIter *iter)
{
- iter->priv = G_TYPE_INSTANCE_GET_PRIVATE (iter, G_TYPE_MENU_LINK_ITER, GMenuLinkIterPrivate);
+ iter->priv = g_menu_link_iter_get_instance_private (iter);
}
static void
GObjectClass *object_class = G_OBJECT_CLASS (class);
object_class->finalize = g_menu_link_iter_finalize;
-
- g_type_class_add_private (class, sizeof (GMenuLinkIterPrivate));
}
projects / platform / upstream / glib.git / blobdiff