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.  NIL
 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".  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".
 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