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