lib/dijit/_base/typematic.js

   1 /*
   2         Copyright (c) 2004-2011, The Dojo Foundation All Rights Reserved.
   3         Available via Academic Free License >= 2.1 OR the modified BSD license.
   4         see: http://dojotoolkit.org/license for details
   5 */
   6
   7
   8 if(!dojo._hasResource["dijit._base.typematic"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
   9 dojo._hasResource["dijit._base.typematic"] = true;
  10 dojo.provide("dijit._base.typematic");
  11
  12
  13 dijit.typematic = {
  14         // summary:
  15         //              These functions are used to repetitively call a user specified callback
  16         //              method when a specific key or mouse click over a specific DOM node is
  17         //              held down for a specific amount of time.
  18         //              Only 1 such event is allowed to occur on the browser page at 1 time.
  19
  20         _fireEventAndReload: function(){
  21                 this._timer = null;
  22                 this._callback(++this._count, this._node, this._evt);
  23
  24                 // Schedule next event, timer is at most minDelay (default 10ms) to avoid
  25                 // browser overload (particularly avoiding starving DOH robot so it never gets to send a mouseup)
  26                 this._currentTimeout = Math.max(
  27                         this._currentTimeout < 0 ? this._initialDelay :
  28                                 (this._subsequentDelay > 1 ? this._subsequentDelay : Math.round(this._currentTimeout * this._subsequentDelay)),
  29                         this._minDelay);
  30                 this._timer = setTimeout(dojo.hitch(this, "_fireEventAndReload"), this._currentTimeout);
  31         },
  32
  33         trigger: function(/*Event*/ evt, /*Object*/ _this, /*DOMNode*/ node, /*Function*/ callback, /*Object*/ obj, /*Number*/ subsequentDelay, /*Number*/ initialDelay, /*Number?*/ minDelay){
  34                 // summary:
  35                 //              Start a timed, repeating callback sequence.
  36                 //              If already started, the function call is ignored.
  37                 //              This method is not normally called by the user but can be
  38                 //              when the normal listener code is insufficient.
  39                 // evt:
  40                 //              key or mouse event object to pass to the user callback
  41                 // _this:
  42                 //              pointer to the user's widget space.
  43                 // node:
  44                 //              the DOM node object to pass the the callback function
  45                 // callback:
  46                 //              function to call until the sequence is stopped called with 3 parameters:
  47                 // count:
  48                 //              integer representing number of repeated calls (0..n) with -1 indicating the iteration has stopped
  49                 // node:
  50                 //              the DOM node object passed in
  51                 // evt:
  52                 //              key or mouse event object
  53                 // obj:
  54                 //              user space object used to uniquely identify each typematic sequence
  55                 // subsequentDelay (optional):
  56                 //              if > 1, the number of milliseconds until the 3->n events occur
  57                 //              or else the fractional time multiplier for the next event's delay, default=0.9
  58                 // initialDelay (optional):
  59                 //              the number of milliseconds until the 2nd event occurs, default=500ms
  60                 // minDelay (optional):
  61                 //              the maximum delay in milliseconds for event to fire, default=10ms
  62                 if(obj != this._obj){
  63                         this.stop();
  64                         this._initialDelay = initialDelay || 500;
  65                         this._subsequentDelay = subsequentDelay || 0.90;
  66                         this._minDelay = minDelay || 10;
  67                         this._obj = obj;
  68                         this._evt = evt;
  69                         this._node = node;
  70                         this._currentTimeout = -1;
  71                         this._count = -1;
  72                         this._callback = dojo.hitch(_this, callback);
  73                         this._fireEventAndReload();
  74                         this._evt = dojo.mixin({faux: true}, evt);
  75                 }
  76         },
  77
  78         stop: function(){
  79                 // summary:
  80                 //              Stop an ongoing timed, repeating callback sequence.
  81                 if(this._timer){
  82                         clearTimeout(this._timer);
  83                         this._timer = null;
  84                 }
  85                 if(this._obj){
  86                         this._callback(-1, this._node, this._evt);
  87                         this._obj = null;
  88                 }
  89         },
  90
  91         addKeyListener: function(/*DOMNode*/ node, /*Object*/ keyObject, /*Object*/ _this, /*Function*/ callback, /*Number*/ subsequentDelay, /*Number*/ initialDelay, /*Number?*/ minDelay){
  92                 // summary:
  93                 //              Start listening for a specific typematic key.
  94                 //              See also the trigger method for other parameters.
  95                 // keyObject:
  96                 //              an object defining the key to listen for:
  97                 //              charOrCode:
  98                 //                      the printable character (string) or keyCode (number) to listen for.
  99                 //              keyCode:
 100                 //                      (deprecated - use charOrCode) the keyCode (number) to listen for (implies charCode = 0).
 101                 //              charCode:
 102                 //                      (deprecated - use charOrCode) the charCode (number) to listen for.
 103                 //              ctrlKey:
 104                 //                      desired ctrl key state to initiate the callback sequence:
 105                 //                      - pressed (true)
 106                 //                      - released (false)
 107                 //                      - either (unspecified)
 108                 //              altKey:
 109                 //                      same as ctrlKey but for the alt key
 110                 //              shiftKey:
 111                 //                      same as ctrlKey but for the shift key
 112                 // returns:
 113                 //              an array of dojo.connect handles
 114                 if(keyObject.keyCode){
 115                         keyObject.charOrCode = keyObject.keyCode;
 116                         dojo.deprecated("keyCode attribute parameter for dijit.typematic.addKeyListener is deprecated. Use charOrCode instead.", "", "2.0");
 117                 }else if(keyObject.charCode){
 118                         keyObject.charOrCode = String.fromCharCode(keyObject.charCode);
 119                         dojo.deprecated("charCode attribute parameter for dijit.typematic.addKeyListener is deprecated. Use charOrCode instead.", "", "2.0");
 120                 }
 121                 return [
 122                         dojo.connect(node, "onkeypress", this, function(evt){
 123                                 if(evt.charOrCode == keyObject.charOrCode &&
 124                                 (keyObject.ctrlKey === undefined || keyObject.ctrlKey == evt.ctrlKey) &&
 125                                 (keyObject.altKey === undefined || keyObject.altKey == evt.altKey) &&
 126                                 (keyObject.metaKey === undefined || keyObject.metaKey == (evt.metaKey || false)) && // IE doesn't even set metaKey
 127                                 (keyObject.shiftKey === undefined || keyObject.shiftKey == evt.shiftKey)){
 128                                         dojo.stopEvent(evt);
 129                                         dijit.typematic.trigger(evt, _this, node, callback, keyObject, subsequentDelay, initialDelay, minDelay);
 130                                 }else if(dijit.typematic._obj == keyObject){
 131                                         dijit.typematic.stop();
 132                                 }
 133                         }),
 134                         dojo.connect(node, "onkeyup", this, function(evt){
 135                                 if(dijit.typematic._obj == keyObject){
 136                                         dijit.typematic.stop();
 137                                 }
 138                         })
 139                 ];
 140         },
 141
 142         addMouseListener: function(/*DOMNode*/ node, /*Object*/ _this, /*Function*/ callback, /*Number*/ subsequentDelay, /*Number*/ initialDelay, /*Number?*/ minDelay){
 143                 // summary:
 144                 //              Start listening for a typematic mouse click.
 145                 //              See the trigger method for other parameters.
 146                 // returns:
 147                 //              an array of dojo.connect handles
 148                 var dc = dojo.connect;
 149                 return [
 150                         dc(node, "mousedown", this, function(evt){
 151                                 dojo.stopEvent(evt);
 152                                 dijit.typematic.trigger(evt, _this, node, callback, node, subsequentDelay, initialDelay, minDelay);
 153                         }),
 154                         dc(node, "mouseup", this, function(evt){
 155                                 dojo.stopEvent(evt);
 156                                 dijit.typematic.stop();
 157                         }),
 158                         dc(node, "mouseout", this, function(evt){
 159                                 dojo.stopEvent(evt);
 160                                 dijit.typematic.stop();
 161                         }),
 162                         dc(node, "mousemove", this, function(evt){
 163                                 evt.preventDefault();
 164                         }),
 165                         dc(node, "dblclick", this, function(evt){
 166                                 dojo.stopEvent(evt);
 167                                 if(dojo.isIE){
 168                                         dijit.typematic.trigger(evt, _this, node, callback, node, subsequentDelay, initialDelay, minDelay);
 169                                         setTimeout(dojo.hitch(this, dijit.typematic.stop), 50);
 170                                 }
 171                         })
 172                 ];
 173         },
 174
 175         addListener: function(/*Node*/ mouseNode, /*Node*/ keyNode, /*Object*/ keyObject, /*Object*/ _this, /*Function*/ callback, /*Number*/ subsequentDelay, /*Number*/ initialDelay, /*Number?*/ minDelay){
 176                 // summary:
 177                 //              Start listening for a specific typematic key and mouseclick.
 178                 //              This is a thin wrapper to addKeyListener and addMouseListener.
 179                 //              See the addMouseListener and addKeyListener methods for other parameters.
 180                 // mouseNode:
 181                 //              the DOM node object to listen on for mouse events.
 182                 // keyNode:
 183                 //              the DOM node object to listen on for key events.
 184                 // returns:
 185                 //              an array of dojo.connect handles
 186                 return this.addKeyListener(keyNode, keyObject, _this, callback, subsequentDelay, initialDelay, minDelay).concat(
 187                         this.addMouseListener(mouseNode, _this, callback, subsequentDelay, initialDelay, minDelay));
 188         }
 189 };
 190
 191 }