gio/gmenumodel.h

   1 /*
   2  * Copyright © 2011 Canonical Ltd.
   3  *
   4  * This library is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as
   6  * published by the Free Software Foundation; either version 2 of the
   7  * licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Author: Ryan Lortie <desrt@desrt.ca>
  18  */
  19
  20 #ifndef __G_MENU_MODEL_H__
  21 #define __G_MENU_MODEL_H__
  22
  23 #include <glib-object.h>
  24
  25 #include <gio/giotypes.h>
  26
  27 G_BEGIN_DECLS
  28
  29 /**
  30  * G_MENU_ATTRIBUTE_ACTION:
  31  *
  32  * The menu item attribute which holds the action name of the item.  Action
  33  * names are namespaced with an identifier for the action group in which the
  34  * action resides. For example, "win." for window-specific actions and "app."
  35  * for application-wide actions.
  36  *
  37  * See also g_menu_model_get_item_attribute() and g_menu_item_set_attribute().
  38  *
  39  * Since: 2.32
  40  **/
  41 #define G_MENU_ATTRIBUTE_ACTION "action"
  42
  43 /**
  44  * G_MENU_ATTRIBUTE_ACTION_NAMESPACE:
  45  *
  46  * The menu item attribute that holds the namespace for all action names in
  47  * menus that are linked from this item.
  48  *
  49  * Since: 2.36
  50  **/
  51 #define G_MENU_ATTRIBUTE_ACTION_NAMESPACE "action-namespace"
  52
  53 /**
  54  * G_MENU_ATTRIBUTE_TARGET:
  55  *
  56  * The menu item attribute which holds the target with which the item's action
  57  * will be activated.
  58  *
  59  * See also g_menu_item_set_action_and_target()
  60  *
  61  * Since: 2.32
  62  **/
  63 #define G_MENU_ATTRIBUTE_TARGET "target"
  64
  65 /**
  66  * G_MENU_ATTRIBUTE_LABEL:
  67  *
  68  * The menu item attribute which holds the label of the item.
  69  *
  70  * Since: 2.32
  71  **/
  72 #define G_MENU_ATTRIBUTE_LABEL "label"
  73
  74 /**
  75  * G_MENU_ATTRIBUTE_ICON:
  76  *
  77  * The menu item attribute which holds the icon of the item.
  78  *
  79  * The icon is stored in the format returned by g_icon_serialize().
  80  *
  81  * This attribute is intended only to represent 'noun' icons such as
  82  * favicons for a webpage, or application icons.  It should not be used
  83  * for 'verbs' (ie: stock icons).
  84  *
  85  * Since: 2.38
  86  **/
  87 #define G_MENU_ATTRIBUTE_ICON "icon"
  88
  89 /**
  90  * G_MENU_LINK_SUBMENU:
  91  *
  92  * The name of the link that associates a menu item with a submenu.
  93  *
  94  * See also g_menu_item_set_link().
  95  *
  96  * Since: 2.32
  97  **/
  98 #define G_MENU_LINK_SUBMENU "submenu"
  99
 100 /**
 101  * G_MENU_LINK_SECTION:
 102  *
 103  * The name of the link that associates a menu item with a section.  The linked
 104  * menu will usually be shown in place of the menu item, using the item's label
 105  * as a header.
 106  *
 107  * See also g_menu_item_set_link().
 108  *
 109  * Since: 2.32
 110  **/
 111 #define G_MENU_LINK_SECTION "section"
 112
 113 #define G_TYPE_MENU_MODEL                                   (g_menu_model_get_type ())
 114 #define G_MENU_MODEL(inst)                                  (G_TYPE_CHECK_INSTANCE_CAST ((inst),                     \
 115                                                              G_TYPE_MENU_MODEL, GMenuModel))
 116 #define G_MENU_MODEL_CLASS(class)                           (G_TYPE_CHECK_CLASS_CAST ((class),                       \
 117                                                              G_TYPE_MENU_MODEL, GMenuModelClass))
 118 #define G_IS_MENU_MODEL(inst)                               (G_TYPE_CHECK_INSTANCE_TYPE ((inst),                     \
 119                                                              G_TYPE_MENU_MODEL))
 120 #define G_IS_MENU_MODEL_CLASS(class)                        (G_TYPE_CHECK_CLASS_TYPE ((class),                       \
 121                                                              G_TYPE_MENU_MODEL))
 122 #define G_MENU_MODEL_GET_CLASS(inst)                        (G_TYPE_INSTANCE_GET_CLASS ((inst),                      \
 123                                                              G_TYPE_MENU_MODEL, GMenuModelClass))
 124
 125 typedef struct _GMenuModelPrivate                           GMenuModelPrivate;
 126 typedef struct _GMenuModelClass                             GMenuModelClass;
 127
 128 typedef struct _GMenuAttributeIterPrivate                   GMenuAttributeIterPrivate;
 129 typedef struct _GMenuAttributeIterClass                     GMenuAttributeIterClass;
 130 typedef struct _GMenuAttributeIter                          GMenuAttributeIter;
 131
 132 typedef struct _GMenuLinkIterPrivate                        GMenuLinkIterPrivate;
 133 typedef struct _GMenuLinkIterClass                          GMenuLinkIterClass;
 134 typedef struct _GMenuLinkIter                               GMenuLinkIter;
 135
 136 struct _GMenuModel
 137 {
 138   GObject            parent_instance;
 139   GMenuModelPrivate *priv;
 140 };
 141
 142 /**
 143  * GMenuModelClass::get_item_attributes:
 144  * @model: the #GMenuModel to query
 145  * @item_index: The #GMenuItem to query
 146  * @attributes: (out) (element-type utf8 GLib.Variant): Attributes on the item
 147  *
 148  * Gets all the attributes associated with the item in the menu model.
 149  */
 150 /**
 151  * GMenuModelClass::get_item_links:
 152  * @model: the #GMenuModel to query
 153  * @item_index: The #GMenuItem to query
 154  * @links: (out) (element-type utf8 GLib.MenuModel): Links from the item
 155  *
 156  * Gets all the links associated with the item in the menu model.
 157  */
 158 struct _GMenuModelClass
 159 {
 160   GObjectClass parent_class;
 161
 162   gboolean              (*is_mutable)                       (GMenuModel          *model);
 163   gint                  (*get_n_items)                      (GMenuModel          *model);
 164   void                  (*get_item_attributes)              (GMenuModel          *model,
 165                                                              gint                 item_index,
 166                                                              GHashTable         **attributes);
 167   GMenuAttributeIter *  (*iterate_item_attributes)          (GMenuModel          *model,
 168                                                              gint                 item_index);
 169   GVariant *            (*get_item_attribute_value)         (GMenuModel          *model,
 170                                                              gint                 item_index,
 171                                                              const gchar         *attribute,
 172                                                              const GVariantType  *expected_type);
 173   void                  (*get_item_links)                   (GMenuModel          *model,
 174                                                              gint                 item_index,
 175                                                              GHashTable         **links);
 176   GMenuLinkIter *       (*iterate_item_links)               (GMenuModel          *model,
 177                                                              gint                 item_index);
 178   GMenuModel *          (*get_item_link)                    (GMenuModel          *model,
 179                                                              gint                 item_index,
 180                                                              const gchar         *link);
 181 };
 182
 183 GLIB_AVAILABLE_IN_2_32
 184 GType                   g_menu_model_get_type                           (void) G_GNUC_CONST;
 185
 186 GLIB_AVAILABLE_IN_2_32
 187 gboolean                g_menu_model_is_mutable                         (GMenuModel         *model);
 188 GLIB_AVAILABLE_IN_2_32
 189 gint                    g_menu_model_get_n_items                        (GMenuModel         *model);
 190
 191 GLIB_AVAILABLE_IN_2_32
 192 GMenuAttributeIter *    g_menu_model_iterate_item_attributes            (GMenuModel         *model,
 193                                                                          gint                item_index);
 194 GLIB_AVAILABLE_IN_2_32
 195 GVariant *              g_menu_model_get_item_attribute_value           (GMenuModel         *model,
 196                                                                          gint                item_index,
 197                                                                          const gchar        *attribute,
 198                                                                          const GVariantType *expected_type);
 199 GLIB_AVAILABLE_IN_2_32
 200 gboolean                g_menu_model_get_item_attribute                 (GMenuModel         *model,
 201                                                                          gint                item_index,
 202                                                                          const gchar        *attribute,
 203                                                                          const gchar        *format_string,
 204                                                                          ...);
 205 GLIB_AVAILABLE_IN_2_32
 206 GMenuLinkIter *         g_menu_model_iterate_item_links                 (GMenuModel         *model,
 207                                                                          gint                item_index);
 208 GLIB_AVAILABLE_IN_2_32
 209 GMenuModel *            g_menu_model_get_item_link                      (GMenuModel         *model,
 210                                                                          gint                item_index,
 211                                                                          const gchar        *link);
 212
 213 GLIB_AVAILABLE_IN_2_32
 214 void                    g_menu_model_items_changed                      (GMenuModel         *model,
 215                                                                          gint                position,
 216                                                                          gint                removed,
 217                                                                          gint                added);
 218
 219
 220 #define G_TYPE_MENU_ATTRIBUTE_ITER                          (g_menu_attribute_iter_get_type ())
 221 #define G_MENU_ATTRIBUTE_ITER(inst)                         (G_TYPE_CHECK_INSTANCE_CAST ((inst),                     \
 222                                                              G_TYPE_MENU_ATTRIBUTE_ITER, GMenuAttributeIter))
 223 #define G_MENU_ATTRIBUTE_ITER_CLASS(class)                  (G_TYPE_CHECK_CLASS_CAST ((class),                       \
 224                                                              G_TYPE_MENU_ATTRIBUTE_ITER, GMenuAttributeIterClass))
 225 #define G_IS_MENU_ATTRIBUTE_ITER(inst)                      (G_TYPE_CHECK_INSTANCE_TYPE ((inst),                     \
 226                                                              G_TYPE_MENU_ATTRIBUTE_ITER))
 227 #define G_IS_MENU_ATTRIBUTE_ITER_CLASS(class)               (G_TYPE_CHECK_CLASS_TYPE ((class),                       \
 228                                                              G_TYPE_MENU_ATTRIBUTE_ITER))
 229 #define G_MENU_ATTRIBUTE_ITER_GET_CLASS(inst)               (G_TYPE_INSTANCE_GET_CLASS ((inst),                      \
 230                                                              G_TYPE_MENU_ATTRIBUTE_ITER, GMenuAttributeIterClass))
 231
 232 struct _GMenuAttributeIter
 233 {
 234   GObject parent_instance;
 235   GMenuAttributeIterPrivate *priv;
 236 };
 237
 238 struct _GMenuAttributeIterClass
 239 {
 240   GObjectClass parent_class;
 241
 242   gboolean      (*get_next) (GMenuAttributeIter  *iter,
 243                              const gchar        **out_name,
 244                              GVariant           **value);
 245 };
 246
 247 GLIB_AVAILABLE_IN_2_32
 248 GType                   g_menu_attribute_iter_get_type                  (void) G_GNUC_CONST;
 249
 250 GLIB_AVAILABLE_IN_2_32
 251 gboolean                g_menu_attribute_iter_get_next                  (GMenuAttributeIter  *iter,
 252                                                                          const gchar        **out_name,
 253                                                                          GVariant           **value);
 254 GLIB_AVAILABLE_IN_2_32
 255 gboolean                g_menu_attribute_iter_next                      (GMenuAttributeIter  *iter);
 256 GLIB_AVAILABLE_IN_2_32
 257 const gchar *           g_menu_attribute_iter_get_name                  (GMenuAttributeIter  *iter);
 258 GLIB_AVAILABLE_IN_2_32
 259 GVariant *              g_menu_attribute_iter_get_value                 (GMenuAttributeIter  *iter);
 260
 261
 262 #define G_TYPE_MENU_LINK_ITER                               (g_menu_link_iter_get_type ())
 263 #define G_MENU_LINK_ITER(inst)                              (G_TYPE_CHECK_INSTANCE_CAST ((inst),                     \
 264                                                              G_TYPE_MENU_LINK_ITER, GMenuLinkIter))
 265 #define G_MENU_LINK_ITER_CLASS(class)                       (G_TYPE_CHECK_CLASS_CAST ((class),                       \
 266                                                              G_TYPE_MENU_LINK_ITER, GMenuLinkIterClass))
 267 #define G_IS_MENU_LINK_ITER(inst)                           (G_TYPE_CHECK_INSTANCE_TYPE ((inst),                     \
 268                                                              G_TYPE_MENU_LINK_ITER))
 269 #define G_IS_MENU_LINK_ITER_CLASS(class)                    (G_TYPE_CHECK_CLASS_TYPE ((class),                       \
 270                                                              G_TYPE_MENU_LINK_ITER))
 271 #define G_MENU_LINK_ITER_GET_CLASS(inst)                    (G_TYPE_INSTANCE_GET_CLASS ((inst),                      \
 272                                                              G_TYPE_MENU_LINK_ITER, GMenuLinkIterClass))
 273
 274 struct _GMenuLinkIter
 275 {
 276   GObject parent_instance;
 277   GMenuLinkIterPrivate *priv;
 278 };
 279
 280 struct _GMenuLinkIterClass
 281 {
 282   GObjectClass parent_class;
 283
 284   gboolean      (*get_next) (GMenuLinkIter  *iter,
 285                              const gchar   **out_link,
 286                              GMenuModel    **value);
 287 };
 288
 289 GLIB_AVAILABLE_IN_2_32
 290 GType                   g_menu_link_iter_get_type                       (void) G_GNUC_CONST;
 291
 292 GLIB_AVAILABLE_IN_2_32
 293 gboolean                g_menu_link_iter_get_next                       (GMenuLinkIter  *iter,
 294                                                                          const gchar   **out_link,
 295                                                                          GMenuModel    **value);
 296 GLIB_AVAILABLE_IN_2_32
 297 gboolean                g_menu_link_iter_next                           (GMenuLinkIter  *iter);
 298 GLIB_AVAILABLE_IN_2_32
 299 const gchar *           g_menu_link_iter_get_name                       (GMenuLinkIter  *iter);
 300 GLIB_AVAILABLE_IN_2_32
 301 GMenuModel *            g_menu_link_iter_get_value                      (GMenuLinkIter  *iter);
 302
 303 G_END_DECLS
 304
 305 #endif /* __G_MENU_MODEL_H__ */