updating cakephp apps
[feisty_meow.git] / graphiq / library / user_interface / menu_base.h
1 //note: in progress.
2
3 #ifndef MENU_BASE_CLASS
4 #define MENU_BASE_CLASS
5
6 /*****************************************************************************\
7 *                                                                             *
8 *  Name   : menu_base                                                         *
9 *  Author : Chris Koeritz                                                     *
10 *                                                                             *
11 *******************************************************************************
12 * Copyright (c) 2003-$now By Author.  This program is free software; you can  *
13 * redistribute it and/or modify it under the terms of the GNU General Public  *
14 * License as published by the Free Software Foundation; either version 2 of   *
15 * the License or (at your option) any later version.  This is online at:      *
16 *     http://www.fsf.org/copyleft/gpl.html                                    *
17 * Please send any updates to: fred@gruntose.com                               *
18 \*****************************************************************************/
19
20
21
22 #include <basis/contracts.h>
23
24 // forward.
25 class menu_common_amorph;
26
27 //////////////
28
29 //! a common base class for referring to menu_items or menus polymorphically.
30
31 class menu_common_base : public virtual root_object
32 {
33 public:
34   virtual ~menu_common_base();
35
36   bool enabled() const { return _enabled; }
37   void enable(bool enable = true) { _enabled = enable; }
38
39 private:
40   bool _enabled;  //!< is this object enabled?
41 };
42
43 //////////////
44
45 //! A base class for the active items that can be stored inside a menu.
46
47 class menu_item
48 : public menu_common_base
49 {
50 public:
51   menu_item(const string_array &triggers, const astring &text,
52           const astring &description);
53     //!< constructs a menu item that shows the "text" and "description".
54     /*!< the "triggers" is a list of characters that are used to activate this
55     menu item.  these correspond to hot keys that are often underlined. */
56
57   menu_item(const menu_item &to_copy);
58
59   virtual ~menu_item();
60
61   menu_item &operator =(const menu_item &to_copy);
62
63   DEFINE_CLASS_NAME("menu_item");
64
65   const string_array &triggers() const;
66   const astring &text() const;
67   const astring &description() const;
68
69   virtual void menu_activation(char trigger);
70     //!< invoked when the user chooses the menu item in question.
71     /*!< the "trigger" holds the value that they actually chose. */
72
73 private:
74   string_array *_triggers;  //!< the trigger values for this menu item.
75   astring *_text;  //!< the text shown for this item.
76   astring *_description;  //!< the full description of the item.
77 };
78
79 //////////////
80
81 //! A base class for a menu-driven interface model.
82 /*!
83   The base just provides functions for manipulating menu items and submenus.
84 */
85
86 class menu_base : public menu_common_base
87 {
88 public:
89   menu_base(const astring &title, const menu_item &parameters);
90     //<! constructs a menu where the "title" is the name for this menu.
91     /*!< the "parameters" record any activation triggers and descriptions for
92     this menu; these are mainly used when this is a sub-menu. */
93
94   virtual ~menu_base();
95
96   DEFINE_CLASS_NAME("menu_base");
97
98   bool validate(bool recursive = true);
99     //!< checks that all of the menu_items
100
101   astring text_form() const;
102     //!< returns a string version of all the information here.
103     /*!< this just prints out this menu without recursing to sub-menus. */
104
105   astring recursive_text_form() const;
106     //!< does a text_form on all menus and submenus rooted here.
107
108   menu_common_base *evaluate_trigger(char trigger);
109     //!< returns the item or menu associated with the "trigger" value.
110     /*!< use of dynamic cast enables one to tell what has been returned.  NULL_POINTER
111     is returned if there is nothing that answers to that trigger value.
112     note that this does not invoke any activation functions. */
113
114   virtual void activate();
115     //!< runs the menu structure by requesting input from the user.
116     /*!< this assumes that they will type a key and hit enter afterwards.  the
117     menus are displayed using the program-wide logger.  no feedback is provided
118     since the menu_items will be activated automatically.  when this method
119     returns, it is assumed that the user has chosen a menu item.  overriding
120     this method allows a different type of menu to provide a totally different
121     method for interacting with the user. */
122
123   // note about the methods here: the menu_base takes over responsibility for
124   // pointers it is handed.  do not delete the items after adding them or
125   // get an item and then delete it.
126   // also, the indices for menu items are separate from the indices for the
127   // sub-menus.
128
129   // menu item manipulators.  the indexes here range from 0 to items() - 1.
130   int items() const;  //!< returns the number of menu items stored.
131   void add_item(menu_item *to_invoke);
132     //!< adds a new menu_item onto this menu.
133   menu_item *get_item(int index);
134     //!< gets the item at position "index".  NULL_POINTER is returned if out of range.
135   bool zap_item(int index);
136     //!< removes the item at "index" if possible.
137   bool enable_item(int index, bool enable = true);
138     //!< enables or disabled the item at "index".
139
140   // submenu manipulation support.  these range from 0 to submenus() - 1.
141   int submenus() const;  //!< number of submenus total.
142   void add_submenu(menu_base *sub);  //!< add a new submenu into "sub".
143   menu_base *get_submenu(int index);
144     //!< returns the submenu stored at "index".
145   bool zap_submenu(int index);
146     //!< removes the submenu at the "index".
147   bool enable_submenu(int index, bool enable = true);
148     //!< enables or disables the submenu at the "index".
149
150 private:
151   astring *_title;  //!< the name for this menu.
152   menu_item *_parameters;  //!< information regarding this menu.
153   menu_common_amorph *_items;  //!< the list of items in this menu.
154   menu_common_amorph *_menus;  //!< the list of sub-menus accessible from here.
155 };
156
157 #endif
158