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