Importation initiale du code de CKEditor 3.6.1.
[ckeditor.git] / _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 */