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 //  Member functions
  61 //  ==============================================================================================================================
  62 /**
  63  * Adds an item to this menu.
  64  * @param name the name of the item added to this menu
  65  * @param item the added item
  66  */
  67     public void addItem (String name, MenuItem item) {
  68 //  ------------------------------------------------
  69       indices.put(name, menu.size());
  70       menu.add(item);
  71     }
  72 /**
  73  * Returns the list of items of this menu.
  74  * @return the list of items of this menu.
  75  */
  76     public List<MenuItem> asList () {
  77 //  -------------------------------
  78       return menu;
  79     }
  80 /**
  81  * Disables the menu item of given name.
  82  * @param name the name of the item
  83  */
  84     public void disables (String name) {
  85 //  ----------------------------------
  86       String   action = disabled.get(name);
  87       MenuItem item   = menu.get(indices.get(name));
  88
  89       if (action != null) return;             // Item already disabled
  90       disabled.put(name, item.getAction());   // Saves the current action for latter enabling
  91       item.action(null);
  92     }
  93 /**
  94  * Enables the menu item of given name, if previously disabled.
  95  * @param name the name of the item
  96  */
  97     public void enables (String name) {
  98 //  ---------------------------------
  99       String   action = disabled.get(name);
 100       MenuItem item   = menu.get(indices.get(name));
 101
 102       if (action == null) return;             // Item not previously disabled
 103       disabled.remove(name);
 104       item.action(action);
 105     }
 106 /**
 107  * Returns the name of this menu.
 108  * @return the name of this menu.
 109  */
 110     public String getName () {
 111 //  ------------------------
 112       return myname;
 113     }
 114 /**
 115  * Returns the namespace of this menu.
 116  * @return the namespace of this menu.
 117  */
 118     public String getNamespace () {
 119 //  -----------------------------
 120       return myscope;
 121     }
 122 /**
 123  * Returns the currently selected item of this menu previously set by selects().
 124  * @return the currently selected item of this menu.
 125  */
 126     public MenuItem getSelectedItem () {
 127 //  ----------------------------------
 128       return menu.get(indices.get(selection));
 129     }
 130 /**
 131  * Returns the name of the currently selected item of this menu previously set by selects().
 132  * If no item selected, returns null.
 133  * @return the name of the currently selected item of this menu.
 134  */
 135     public String getSelection () {
 136 //  -----------------------------
 137       return selection;        // May be null
 138     }
 139 /**
 140  * Sets the given menu-item as selected.
 141  * @param name the name of the selected menu-item.
 142  */
 143     public void selects (String name) {
 144 //  ---------------------------------
 145       Integer  newdex = indices.get(name);
 146
 147       if (selection != null) menu.get(indices.get(selection)).unselect();
 148       if (newdex    == null) return;
 149       menu.get(newdex).select();
 150       selection = name;
 151     }
 152 }