_source/core/focusmanager.js

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