finch/libgnt/gntmenuitem.h

   1 /**
   2  * @file gntmenuitem.h Menuitem API
   3  * @ingroup gnt
   4  */
   5 /*
   6  * GNT - The GLib Ncurses Toolkit
   7  *
   8  * GNT is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This library is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26
  27 #ifndef GNT_MENUITEM_H
  28 #define GNT_MENUITEM_H
  29
  30 #include <glib.h>
  31 #include <glib-object.h>
  32
  33 #define GNT_TYPE_MENU_ITEM                              (gnt_menuitem_get_gtype())
  34 #define GNT_MENU_ITEM(obj)                              (G_TYPE_CHECK_INSTANCE_CAST((obj), GNT_TYPE_MENU_ITEM, GntMenuItem))
  35 #define GNT_MENU_ITEM_CLASS(klass)              (G_TYPE_CHECK_CLASS_CAST((klass), GNT_TYPE_MENU_ITEM, GntMenuItemClass))
  36 #define GNT_IS_MENU_ITEM(obj)                   (G_TYPE_CHECK_INSTANCE_TYPE((obj), GNT_TYPE_MENU_ITEM))
  37 #define GNT_IS_MENU_ITEM_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE((klass), GNT_TYPE_MENU_ITEM))
  38 #define GNT_MENU_ITEM_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS((obj), GNT_TYPE_MENU_ITEM, GntMenuItemClass))
  39
  40 #define GNT_MENU_ITEM_FLAGS(obj)                                (GNT_MENU_ITEM(obj)->priv.flags)
  41 #define GNT_MENU_ITEM_SET_FLAGS(obj, flags)             (GNT_MENU_ITEM_FLAGS(obj) |= flags)
  42 #define GNT_MENU_ITEM_UNSET_FLAGS(obj, flags)   (GNT_MENU_ITEM_FLAGS(obj) &= ~(flags))
  43
  44 typedef struct _GntMenuItem                     GntMenuItem;
  45 typedef struct _GntMenuItemPriv         GntMenuItemPriv;
  46 typedef struct _GntMenuItemClass                GntMenuItemClass;
  47
  48 #include "gntmenu.h"
  49
  50 struct _GntMenuItemPriv
  51 {
  52         /* These will be used to determine the position of the submenu */
  53         int x;
  54         int y;
  55         char trigger;
  56         char *id;
  57 };
  58
  59 typedef void (*GntMenuItemCallback)(GntMenuItem *item, gpointer data);
  60
  61 struct _GntMenuItem
  62 {
  63         GObject parent;
  64         GntMenuItemPriv priv;
  65
  66         char *text;
  67
  68         /* A GntMenuItem can have a callback associated with it.
  69          * The callback will be activated whenever the suer selects it and presses enter (or clicks).
  70          * However, if the GntMenuItem has some child, then the callback and callbackdata will be ignored. */
  71         gpointer callbackdata;
  72         GntMenuItemCallback callback;
  73
  74         GntMenu *submenu;
  75 };
  76
  77 struct _GntMenuItemClass
  78 {
  79         GObjectClass parent;
  80
  81         void (*gnt_reserved1)(void);
  82         void (*gnt_reserved2)(void);
  83         void (*gnt_reserved3)(void);
  84         void (*gnt_reserved4)(void);
  85 };
  86
  87 G_BEGIN_DECLS
  88
  89 /**
  90  * @return GType for GntMenuItem.
  91  */
  92 GType gnt_menuitem_get_gtype(void);
  93
  94 /**
  95  * Create a new menuitem.
  96  *
  97  * @param text   Label for the menuitem.
  98  *
  99  * @return  The newly created menuitem.
 100  */
 101 GntMenuItem * gnt_menuitem_new(const char *text);
 102
 103 /**
 104  * Set a callback function for a menuitem.
 105  *
 106  * @param item       The menuitem.
 107  * @param callback   The callback function.
 108  * @param data       Data to send to the callback function.
 109  */
 110 void gnt_menuitem_set_callback(GntMenuItem *item, GntMenuItemCallback callback, gpointer data);
 111
 112 /**
 113  * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback.
 114  *
 115  * @param item  The menuitem.
 116  * @param menu  The submenu.
 117  */
 118 void gnt_menuitem_set_submenu(GntMenuItem *item, GntMenu *menu);
 119
 120 /**
 121  * Get the submenu for a menuitem.
 122  *
 123  * @param item   The menuitem.
 124  *
 125  * @return  The submenu, or @c NULL.
 126  *
 127  * @since 2.3.0
 128  */
 129 GntMenu *gnt_menuitem_get_submenu(GntMenuItem *item);
 130
 131 /**
 132  * Set a trigger key for the item.
 133  *
 134  * @param item     The menuitem
 135  * @param trigger  The key that will trigger the item when the parent manu is visible
 136  */
 137 void gnt_menuitem_set_trigger(GntMenuItem *item, char trigger);
 138
 139 /**
 140  * Get the trigger key for a menuitem.
 141  *
 142  * @param item   The menuitem
 143  *
 144  * @return The trigger key for the menuitem.
 145  *
 146  * @see gnt_menuitem_set_trigger
 147  */
 148 char gnt_menuitem_get_trigger(GntMenuItem *item);
 149
 150 /**
 151  * Set an ID for the menuitem.
 152  *
 153  * @param item   The menuitem.
 154  * @param id     The ID for the menuitem.
 155  *
 156  * @since 2.3.0
 157  */
 158 void gnt_menuitem_set_id(GntMenuItem *item, const char *id);
 159
 160 /**
 161  * Get the ID of the menuitem.
 162  *
 163  * @param item   The menuitem.
 164  *
 165  * @return  The ID for the menuitem.
 166  *
 167  * @since 2.3.0
 168  */
 169 const char * gnt_menuitem_get_id(GntMenuItem *item);
 170
 171 /**
 172  * Activate a menuitem.
 173  * Activating the menuitem will first trigger the 'activate' signal for the
 174  * menuitem. Then the callback for the menuitem is triggered, if there is one.
 175  *
 176  * @param item   The menuitem.
 177  *
 178  * @return  Whether the callback for the menuitem was called.
 179  *
 180  * @since 2.3.0
 181  */
 182 gboolean gnt_menuitem_activate(GntMenuItem *item);
 183
 184 G_END_DECLS
 185
 186 #endif /* GNT_MENUITEM_H */