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

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