3 #ifndef MENU_BASE_CLASS
4 #define MENU_BASE_CLASS
6 /*****************************************************************************\
9 * Author : Chris Koeritz *
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 \*****************************************************************************/
22 #include <basis/contracts.h>
25 class menu_common_amorph;
29 //! a common base class for referring to menu_items or menus polymorphically.
31 class menu_common_base : public virtual root_object
34 virtual ~menu_common_base();
36 bool enabled() const { return _enabled; }
37 void enable(bool enable = true) { _enabled = enable; }
40 bool _enabled; //!< is this object enabled?
45 //! A base class for the active items that can be stored inside a menu.
48 : public menu_common_base
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. */
57 menu_item(const menu_item &to_copy);
61 menu_item &operator =(const menu_item &to_copy);
63 DEFINE_CLASS_NAME("menu_item");
65 const string_array &triggers() const;
66 const astring &text() const;
67 const astring &description() const;
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. */
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.
81 //! A base class for a menu-driven interface model.
83 The base just provides functions for manipulating menu items and submenus.
86 class menu_base : public menu_common_base
89 menu_base(const astring &title, const menu_item ¶meters);
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. */
96 DEFINE_CLASS_NAME("menu_base");
98 bool validate(bool recursive = true);
99 //!< checks that all of the menu_items
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. */
105 astring recursive_text_form() const;
106 //!< does a text_form on all menus and submenus rooted here.
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. NIL
111 is returned if there is nothing that answers to that trigger value.
112 note that this does not invoke any activation functions. */
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. */
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
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". NIL 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".
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".
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.