sources/core/ui.js

   1 /**
   2  * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
   3  * For licensing, see LICENSE.md or http://ckeditor.com/license
   4  */
   5
   6 /**
   7  * Contains UI features related to an editor instance.
   8  *
   9  * @class
  10  * @mixins CKEDITOR.event
  11  * @constructor Creates a `ui` class instance.
  12  * @param {CKEDITOR.editor} editor The editor instance.
  13  */
  14 CKEDITOR.ui = function( editor ) {
  15         if ( editor.ui )
  16                 return editor.ui;
  17
  18         this.items = {};
  19         this.instances = {};
  20         this.editor = editor;
  21
  22         /**
  23          * Object used to store private stuff.
  24          *
  25          * @private
  26          */
  27         this._ = {
  28                 handlers: {}
  29         };
  30
  31         return this;
  32 };
  33
  34 // PACKAGER_RENAME( CKEDITOR.ui )
  35
  36 CKEDITOR.ui.prototype = {
  37         /**
  38          * Adds a UI item to the items collection. These items can be later used in
  39          * the interface.
  40          *
  41          *              // Add a new button named 'MyBold'.
  42          *              editorInstance.ui.add( 'MyBold', CKEDITOR.UI_BUTTON, {
  43          *                      label: 'My Bold',
  44          *                      command: 'bold'
  45          *              } );
  46          *
  47          * @param {String} name The UI item name.
  48          * @param {Object} type The item type.
  49          * @param {Object} definition The item definition. The properties of this
  50          * object depend on the item type.
  51          */
  52         add: function( name, type, definition ) {
  53                 // Compensate the unique name of this ui item to definition.
  54                 definition.name = name.toLowerCase();
  55
  56                 var item = this.items[ name ] = {
  57                         type: type,
  58                         // The name of {@link CKEDITOR.command} which associate with this UI.
  59                         command: definition.command || null,
  60                         args: Array.prototype.slice.call( arguments, 2 )
  61                 };
  62
  63                 CKEDITOR.tools.extend( item, definition );
  64         },
  65
  66         /**
  67          * Retrieves the created UI objects by name.
  68          *
  69          * @param {String} name The name of the UI definition.
  70          */
  71         get: function( name ) {
  72                 return this.instances[ name ];
  73         },
  74
  75         /**
  76          * Gets a UI object.
  77          *
  78          * @param {String} name The UI item name.
  79          * @returns {Object} The UI element.
  80          */
  81         create: function( name ) {
  82                 var item = this.items[ name ],
  83                         handler = item && this._.handlers[ item.type ],
  84                         command = item && item.command && this.editor.getCommand( item.command );
  85
  86                 var result = handler && handler.create.apply( this, item.args );
  87
  88                 this.instances[ name ] = result;
  89
  90                 // Add reference inside command object.
  91                 if ( command )
  92                         command.uiItems.push( result );
  93
  94                 if ( result && !result.type )
  95                         result.type = item.type;
  96
  97                 return result;
  98         },
  99
 100         /**
 101          * Adds a handler for a UI item type. The handler is responsible for
 102          * transforming UI item definitions into UI objects.
 103          *
 104          * @param {Object} type The item type.
 105          * @param {Object} handler The handler definition.
 106          */
 107         addHandler: function( type, handler ) {
 108                 this._.handlers[ type ] = handler;
 109         },
 110
 111         /**
 112          * Returns the unique DOM element that represents one editor's UI part, also known as "space".
 113          * There are 3 main editor spaces available: `top`, `contents` and `bottom`
 114          * and their availability depends on editor type.
 115          *
 116          *              // Hide the bottom space in the UI.
 117          *              var bottom = editor.ui.space( 'bottom' );
 118          *              bottom.setStyle( 'display', 'none' );
 119          *
 120          * @param {String} name The name of the space.
 121          * @returns {CKEDITOR.dom.element} The element that represents the space.
 122          */
 123         space: function( name ) {
 124                 return CKEDITOR.document.getById( this.spaceId( name ) );
 125         },
 126
 127         /**
 128          * Returns the HTML ID for a specific UI space name.
 129          *
 130          * @param {String} name The name of the space.
 131          * @returns {String} The ID of an element representing this space in the DOM.
 132          */
 133         spaceId: function( name ) {
 134                 return this.editor.id + '_' + name;
 135         }
 136 };
 137
 138 CKEDITOR.event.implementOn( CKEDITOR.ui );
 139
 140 /**
 141  * Internal event fired when a new UI element is ready.
 142  *
 143  * @event ready
 144  * @param {Object} data The new UI element.
 145  */
 146
 147 /**
 148  * Virtual class which just illustrates the features of handler objects to be
 149  * passed to the {@link CKEDITOR.ui#addHandler} function.
 150  * This class is not really a part of the API, so do not call its constructor.
 151  *
 152  * @class CKEDITOR.ui.handlerDefinition
 153  */
 154
 155 /**
 156  * Transforms an item definition into a UI item object.
 157  *
 158  *              editorInstance.ui.addHandler( CKEDITOR.UI_BUTTON, {
 159  *                      create: function( definition ) {
 160  *                              return new CKEDITOR.ui.button( definition );
 161  *                      }
 162  *              } );
 163  *
 164  * @method create
 165  * @param {Object} definition The item definition.
 166  * @returns {Object} The UI element.
 167  * @todo We lack the "UI element" abstract super class.
 168  */
 169
 170 /**
 171  * The element in the {@link CKEDITOR#document host page's document} that contains the editor content.
 172  * If the [fixed editor UI](#!/guide/dev_uitypes-section-fixed-user-interface) is used, then it will be set to
 173  * `editor.ui.space( 'contents' )` &mdash; i.e. the `<div>` which contains the editor `<iframe>` (in case of classic editor)
 174  * or {@link CKEDITOR.editable} (in case of inline editor). Otherwise it is set to the {@link CKEDITOR.editable} itself.
 175  *
 176  * Use the position of this element if you need to position elements placed in the host page's document relatively to the
 177  * editor content.
 178  *
 179  *              var editor = CKEDITOR.instances.editor1;
 180  *              console.log( editor.ui.contentsElement.getName() ); // 'div'
 181  *
 182  * @since 4.5
 183  * @readonly
 184  * @property {CKEDITOR.dom.element} contentsElement
 185  */