Workspace/Siman/src/org/splat/wapp/Menu.java

   1 package org.splat.wapp;
   2
   3 import java.util.HashMap;
   4 import java.util.List;
   5 import java.util.Vector;
   6
   7 /**
   8  * Base abstract class defining the minimal services for implementing menus.<br/>
   9  * A menu is an ordered list of named menu-items. Each menu-item is made of:
  10  * <ul>
  11  * <li>A non localized label (a key into a locale file)</li>
  12  * <li>Optionally, an icon (an image file name)</li>
  13  * <li>A command to be executed when selecting this menu-item</li>
  14  * </ul>
  15  * On the contrary of PopupMenus, Menus are not contextual, that is, their items are always active, and can keep the user
  16  * selection.<br/>
  17  * After its creation, a menu is in Unselected state - the getSelection() method returns null. The user selection is then
  18  * set (and changed) by the name of its corresponding menu-item, thus making getSelection() returning this name.<br/>
  19  * <br/>
  20  * The commands of menu-items are in an application-dependent format. They can be undefined, for example in a demonstration
  21  * version of the application, making the corresponding menu-items disabled.<br/>
  22  * <br/>
  23  * Menus are visible by the application as Lists (from java.util) for allowing their display.
  24  *
  25  * @see MenuItem
  26  * @see ContextualMenu
  27  * @author Daniel Brunier-Coulin
  28  */
  29 public abstract class Menu {
  30
  31     private   String                  myname;
  32     private   String                  myscope;
  33     protected Vector<MenuItem>        menu;               // For making the menu visible as a list of MenuItems
  34         protected HashMap<String,Integer> indices;            // Indices of MenuItem objects into this menu
  35         protected HashMap<String,String>  disabled;           // Actions of disabled item
  36     protected String                  selection = null;
  37
  38 //  ==============================================================================================================================
  39 //  Constructors
  40 //  ==============================================================================================================================
  41
  42     protected Menu (String name) {
  43 //  ----------------------------
  44       myname   = name;
  45       myscope  = "/";
  46       menu     = new Vector<MenuItem>();
  47       indices  = new HashMap<String,Integer>();
  48       disabled = new HashMap<String,String>();
  49     }
  50     protected Menu (String name, String scope) {
  51 //  ------------------------------------------
  52       myname   = name;
  53       myscope  = "/" + scope;
  54       menu     = new Vector<MenuItem>();
  55       indices  = new HashMap<String,Integer>();
  56       disabled = new HashMap<String,String>();
  57     }
  58
  59     /**
  60      * Initialize the menu.
  61      */
  62     protected void init() {
  63         menu.clear();
  64         indices.clear();
  65         disabled.clear();
  66     }
  67 //  ==============================================================================================================================
  68 //  Member functions
  69 //  ==============================================================================================================================
  70 /**
  71  * Adds an item to this menu.
  72  * @param name the name of the item added to this menu
  73  * @param item the added item
  74  */
  75     public void addItem (String name, MenuItem item) {
  76 //  ------------------------------------------------
  77       indices.put(name, menu.size());
  78       menu.add(item);
  79     }
  80 /**
  81  * Returns the list of items of this menu.
  82  * @return the list of items of this menu.
  83  */
  84     public List<MenuItem> asList () {
  85 //  -------------------------------
  86       return menu;
  87     }
  88 /**
  89  * Disables the menu item of given name.
  90  * @param name the name of the item
  91  */
  92     public void disables (String name) {
  93 //  ----------------------------------
  94       String   action = disabled.get(name);
  95       MenuItem item   = menu.get(indices.get(name));
  96
  97       if (action != null) return;             // Item already disabled
  98       disabled.put(name, item.getAction());   // Saves the current action for latter enabling
  99       item.action(null);
 100     }
 101 /**
 102  * Enables the menu item of given name, if previously disabled.
 103  * @param name the name of the item
 104  */
 105     public void enables (String name) {
 106 //  ---------------------------------
 107       String   action = disabled.get(name);
 108       MenuItem item   = menu.get(indices.get(name));
 109
 110       if (action == null) return;             // Item not previously disabled
 111       disabled.remove(name);
 112       item.action(action);
 113     }
 114 /**
 115  * Returns the name of this menu.
 116  * @return the name of this menu.
 117  */
 118     public String getName () {
 119 //  ------------------------
 120       return myname;
 121     }
 122 /**
 123  * Returns the namespace of this menu.
 124  * @return the namespace of this menu.
 125  */
 126     public String getNamespace () {
 127 //  -----------------------------
 128       return myscope;
 129     }
 130 /**
 131  * Returns the currently selected item of this menu previously set by selects().
 132  * @return the currently selected item of this menu.
 133  */
 134     public MenuItem getSelectedItem () {
 135 //  ----------------------------------
 136       return menu.get(indices.get(selection));
 137     }
 138 /**
 139  * Returns the name of the currently selected item of this menu previously set by selects().
 140  * If no item selected, returns null.
 141  * @return the name of the currently selected item of this menu.
 142  */
 143     public String getSelection () {
 144 //  -----------------------------
 145       return selection;        // May be null
 146     }
 147 /**
 148  * Sets the given menu-item as selected.
 149  * @param name the name of the selected menu-item.
 150  */
 151     public void selects (String name) {
 152 //  ---------------------------------
 153       Integer  newdex = indices.get(name);
 154
 155       if (selection != null) menu.get(indices.get(selection)).unselect();
 156       if (newdex    == null) return;
 157       menu.get(newdex).select();
 158       selection = name;
 159     }
 160 }