webapps/qooxdoo-0.6.3-sdk/frontend/framework/source/class/qx/client/Command.js

   1 /* ************************************************************************
   2
   3    qooxdoo - the new era of web development
   4
   5    http://qooxdoo.org
   6
   7    Copyright:
   8      2004-2006 by 1&1 Internet AG, Germany, http://www.1and1.org
   9
  10    License:
  11      LGPL 2.1: http://www.gnu.org/licenses/lgpl.html
  12
  13    Authors:
  14      * Sebastian Werner (wpbasti)
  15      * Andreas Ecker (ecker)
  16      * Fabian Jakobs (fjakobs)
  17
  18 ************************************************************************ */
  19
  20 /* ************************************************************************
  21
  22 #module(ui_core)
  23
  24 ************************************************************************ */
  25
  26 /**
  27  * This contains a command with shortcut.
  28  *
  29  * Each command could be assigned to multiple widgets.
  30  *
  31  * @event execute {qx.event.type.DataEvent} when the command is executed.
  32  *
  33  * @param vShortcut (string) shortcuts can be composed of optional modifier
  34  *    keys Control, Alt, Shift, Meta and a non modifier key.
  35  *    If no non modifier key is specified, the second paramater is evaluated.
  36  *    The key must be seperated by a ''+'' or ''-'' character.
  37  *    Examples: Alt+F1, Control+C, Control+Alt+Enf
  38  *
  39  * @param vKeyCodeOrIdentifier (int)  Additional key of the command. It is interpreted as a
  40  *    keyIdentifier if it is given as integer. Otherwhise it is interpreted as keyCode.
  41  */
  42 qx.OO.defineClass("qx.client.Command", qx.core.Target,
  43 function(vShortcut, vKeyCodeOrIdentifier)
  44 {
  45   qx.core.Target.call(this);
  46
  47   this._modifier = {};
  48   this._key = null;
  49
  50   if (qx.util.Validation.isValid(vShortcut)) {
  51     this.setShortcut(vShortcut);
  52   }
  53
  54   if (qx.util.Validation.isValid(vKeyCodeOrIdentifier))
  55   {
  56      if (qx.util.Validation.isValidString(vKeyCodeOrIdentifier))
  57      {
  58       this.setKeyIdentifier(vKeyCodeOrIdentifier);
  59      }
  60      else if (qx.util.Validation.isValidNumber(vKeyCodeOrIdentifier))
  61      {
  62       this.warn("The use of keyCode in command is deprecated. Use keyIdentifier instead.");
  63       this.setKeyCode(vKeyCodeOrIdentifier);
  64     }
  65     else
  66     {
  67       var msg = "vKeyCodeOrIdentifier must be of type string or number: " + vKeyCodeOrIdentifier;
  68       this.error(msg);
  69       throw msg;
  70     }
  71   }
  72
  73   // OSX warning for Alt key combinations
  74   if (this._modifier.Alt && this._key && this._key.length == 1) {
  75     if (
  76       (this._key >= "A" && this._key <= "Z") ||
  77       (this._key >= "0" && this._key <= "9")
  78     ) {
  79       this.warn("A shortcut containing Alt and a letter or number will not work under OS X!");
  80     }
  81   }
  82   qx.event.handler.EventHandler.getInstance().addCommand(this);
  83 });
  84
  85
  86 /** the command shortcut */
  87 qx.OO.addProperty({ name : "shortcut", type : "string" });
  88
  89 /**
  90  * keyCode (Deprecated)
  91  * Still there for compatibility with the old key handler/commands
  92  */
  93 qx.OO.addProperty({ name : "keyCode", type : "number" });
  94
  95 /** KeyIdentifier */
  96 qx.OO.addProperty({ name : "keyIdentifier", type : "string" });
  97
  98
  99
 100 /*
 101 ---------------------------------------------------------------------------
 102   USER METHODS
 103 ---------------------------------------------------------------------------
 104 */
 105
 106 /**
 107  * Fire the "execute" event on this command.
 108  *
 109  * @param vTarget (Object)
 110  */
 111 qx.Proto.execute = function(vTarget)
 112 {
 113   if (this.hasEventListeners("execute")) {
 114     this.dispatchEvent(new qx.event.type.DataEvent("execute", vTarget), true);
 115   }
 116
 117   return false;
 118 };
 119
 120
 121
 122 /*
 123 ---------------------------------------------------------------------------
 124   MODIFIER
 125 ---------------------------------------------------------------------------
 126 */
 127
 128 qx.Proto._modifyShortcut = function(propValue, propOldValue, propData)
 129 {
 130   if (propValue)
 131   {
 132     this._modifier = {};
 133     this._key = null;
 134
 135     // split string to get each key which must be pressed
 136     // build a hash with active keys
 137     var a = propValue.split(/[-+\s]+/);
 138     var al = a.length;
 139
 140     for (var i=0; i<al; i++)
 141     {
 142       var identifier = qx.event.handler.KeyEventHandler.getInstance().oldKeyNameToKeyIdentifier(a[i]);
 143
 144       switch (identifier)
 145       {
 146         case "Control":
 147         case "Shift":
 148         case "Meta":
 149         case "Alt":
 150           this._modifier[identifier] = true;
 151           break;
 152
 153         case "Unidentified":
 154           var msg = "Not a valid key name for a command: " + a[i];
 155           this.error(msg);
 156           throw msg;
 157
 158         default:
 159           if (this._key) {
 160             var msg = "You can only specify one non modifier key!";
 161             this.error(msg);
 162             throw msg;
 163           }
 164           this._key = identifier;
 165       }
 166     }
 167   }
 168   return true;
 169 };
 170
 171
 172
 173 /*
 174 ---------------------------------------------------------------------------
 175   INTERNAL MATCHING LOGIC
 176 ---------------------------------------------------------------------------
 177 */
 178
 179 /**
 180  * Checks wether the given key event matches the command's shortcut
 181  *
 182  * @param e (qx.event.type.KeyEvent) the key event object
 183  * @return (boolean) wether the commands shortcut matches the key event
 184  */
 185 qx.Proto._matchesKeyEvent = function(e)
 186 {
 187   var key = this._key || this.getKeyIdentifier();
 188   if (!key && !this.getKeyCode()) {
 189     // no shortcut defined.
 190     return;
 191   }
 192
 193   // pre-check for check special keys
 194   // we handle this here to omit to check this later again.
 195   if (
 196     (this._modifier.Shift && !e.getShiftKey()) ||
 197     (this._modifier.Control && !e.getCtrlKey()) ||
 198 //    (this._modifier.Meta && !e.getCtrlKey()) ||
 199     (this._modifier.Alt && !e.getAltKey())
 200   ) {
 201     return false;
 202   }
 203
 204   if (key)
 205   {
 206     if (key == e.getKeyIdentifier()) {
 207       return true;
 208     }
 209   }
 210   else
 211   {
 212     if (this.getKeyCode() == e.getKeyCode()) {
 213       return true;
 214     }
 215   }
 216
 217   return false;
 218 };
 219
 220
 221
 222 /*
 223 ---------------------------------------------------------------------------
 224   STRING CONVERTION
 225 ---------------------------------------------------------------------------
 226 */
 227
 228 /**
 229  * Returns the shortcut as string
 230  *
 231  * @return (string) shortcut
 232  */
 233 qx.Proto.toString = function()
 234 {
 235   var vShortcut = this.getShortcut();
 236   var vKeyCode = this.getKeyCode();
 237   var vString = "";
 238   var vKeyIdentifier = this._key || this.getKeyIdentifier();
 239
 240   var vKeyString = "";
 241   if (qx.util.Validation.isValidString(vKeyIdentifier))
 242   {
 243     vKeyString = vKeyIdentifier;
 244   }
 245   else if (qx.util.Validation.isValidNumber(vKeyCode))
 246   {
 247     var vTemp = qx.event.type.KeyEvent.codes[vKeyCode];
 248     vKeyString = vTemp ? qx.lang.String.toFirstUp(vTemp) : String(vKeyCode);
 249   }
 250
 251   if (qx.util.Validation.isValidString(vShortcut))
 252   {
 253     vString = vShortcut + "+" + vKeyString;
 254   }
 255   else if (qx.util.Validation.isValidNumber(vKeyCode))
 256   {
 257     vString = vKeyString;
 258   }
 259
 260   return vString;
 261 };
 262
 263
 264
 265 /*
 266 ---------------------------------------------------------------------------
 267   DISPOSER
 268 ---------------------------------------------------------------------------
 269 */
 270
 271 /**
 272  * Destructor
 273  */
 274 qx.Proto.dispose = function()
 275 {
 276   if (this.getDisposed()) {
 277     return;
 278   }
 279
 280   this._shortcutParts = null;
 281
 282   var vMgr = qx.event.handler.EventHandler.getInstance();
 283   if (vMgr) {
 284     vMgr.removeCommand(this);
 285   }
 286
 287   return qx.core.Target.prototype.dispose.call(this);
 288 };