_source/core/focusmanager.js

   1 /*\r
   2 Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.\r
   3 For licensing, see LICENSE.html or http://ckeditor.com/license\r
   4 */\r
   5 \r
   6 /**\r
   7  * @fileOverview Defines the {@link CKEDITOR.focusManager} class, which is used\r
   8  *              to handle the focus on editor instances..\r
   9  */\r
  10 \r
  11 /**\r
  12  * Creates a focusManager class instance.\r
  13  * @class Manages the focus activity in an editor instance. This class is to be\r
  14  * used mainly by UI elements coders when adding interface elements that need\r
  15  * to set the focus state of the editor.\r
  16  * @param {CKEDITOR.editor} editor The editor instance.\r
  17  * @example\r
  18  * var focusManager = <b>new CKEDITOR.focusManager( editor )</b>;\r
  19  * focusManager.focus();\r
  20  */\r
  21 CKEDITOR.focusManager = function( editor )\r
  22 {\r
  23         if ( editor.focusManager )\r
  24                 return editor.focusManager;\r
  25 \r
  26         /**\r
  27          * Indicates that the editor instance has focus.\r
  28          * @type Boolean\r
  29          * @example\r
  30          * alert( CKEDITOR.instances.editor1.focusManager.hasFocus );  // e.g "true"\r
  31          */\r
  32         this.hasFocus = false;\r
  33 \r
  34         /**\r
  35          * Object used to hold private stuff.\r
  36          * @private\r
  37          */\r
  38         this._ =\r
  39         {\r
  40                 editor : editor\r
  41         };\r
  42 \r
  43         return this;\r
  44 };\r
  45 \r
  46 CKEDITOR.focusManager.prototype =\r
  47 {\r
  48         /**\r
  49          * Used to indicate that the editor instance has the focus.<br />\r
  50          * <br />\r
  51          * Note that this function will not explicitelly set the focus in the\r
  52          * editor (for example, making the caret blinking on it). Use\r
  53          * {@link CKEDITOR.editor#focus} for it instead.\r
  54          * @example\r
  55          * var editor = CKEDITOR.instances.editor1;\r
  56          * <b>editor.focusManager.focus()</b>;\r
  57          */\r
  58         focus : function()\r
  59         {\r
  60                 if ( this._.timer )\r
  61                         clearTimeout( this._.timer );\r
  62 \r
  63                 if ( !this.hasFocus )\r
  64                 {\r
  65                         // If another editor has the current focus, we first "blur" it. In\r
  66                         // this way the events happen in a more logical sequence, like:\r
  67                         //              "focus 1" > "blur 1" > "focus 2"\r
  68                         // ... instead of:\r
  69                         //              "focus 1" > "focus 2" > "blur 1"\r
  70                         if ( CKEDITOR.currentInstance )\r
  71                                 CKEDITOR.currentInstance.focusManager.forceBlur();\r
  72 \r
  73                         var editor = this._.editor;\r
  74 \r
  75                         editor.container.getChild( 1 ).addClass( 'cke_focus' );\r
  76 \r
  77                         this.hasFocus = true;\r
  78                         editor.fire( 'focus' );\r
  79                 }\r
  80         },\r
  81 \r
  82         /**\r
  83          * Used to indicate that the editor instance has lost the focus.<br />\r
  84          * <br />\r
  85          * Note that this functions acts asynchronously with a delay of 100ms to\r
  86          * avoid subsequent blur/focus effects. If you want the "blur" to happen\r
  87          * immediately, use the {@link #forceBlur} function instead.\r
  88          * @example\r
  89          * var editor = CKEDITOR.instances.editor1;\r
  90          * <b>editor.focusManager.blur()</b>;\r
  91          */\r
  92         blur : function()\r
  93         {\r
  94                 var focusManager = this;\r
  95 \r
  96                 if ( focusManager._.timer )\r
  97                         clearTimeout( focusManager._.timer );\r
  98 \r
  99                 focusManager._.timer = setTimeout(\r
 100                         function()\r
 101                         {\r
 102                                 delete focusManager._.timer;\r
 103                                 focusManager.forceBlur();\r
 104                         }\r
 105                         , 100 );\r
 106         },\r
 107 \r
 108         /**\r
 109          * Used to indicate that the editor instance has lost the focus. Unlike\r
 110          * {@link #blur}, this function is synchronous, marking the instance as\r
 111          * "blured" immediately.\r
 112          * @example\r
 113          * var editor = CKEDITOR.instances.editor1;\r
 114          * <b>editor.focusManager.forceBlur()</b>;\r
 115          */\r
 116         forceBlur : function()\r
 117         {\r
 118                 if ( this.hasFocus )\r
 119                 {\r
 120                         var editor = this._.editor;\r
 121 \r
 122                         editor.container.getChild( 1 ).removeClass( 'cke_focus' );\r
 123 \r
 124                         this.hasFocus = false;\r
 125                         editor.fire( 'blur' );\r
 126                 }\r
 127         }\r
 128 };\r
 129 \r
 130 /**\r
 131  * Fired when the editor instance receives the input focus.\r
 132  * @name CKEDITOR.editor#focus\r
 133  * @event\r
 134  * @param {CKEDITOR.editor} editor The editor instance.\r
 135  * @example\r
 136  * editor.on( 'focus', function( e )\r
 137  *     {\r
 138  *         alert( 'The editor named ' + e.editor.name + ' is now focused' );\r
 139  *     });\r
 140  */\r
 141 \r
 142 /**\r
 143  * Fired when the editor instance loses the input focus.\r
 144  * @name CKEDITOR.editor#blur\r
 145  * @event\r
 146  * @param {CKEDITOR.editor} editor The editor instance.\r
 147  * @example\r
 148  * editor.on( 'blur', function( e )\r
 149  *     {\r
 150  *         alert( 'The editor named ' + e.editor.name + ' lost the focus' );\r
 151  *     });\r
 152  */\r