1 /*
  2  * CKEditor - The text editor for Internet - http://ckeditor.com
  3  * Copyright (C) 2003-2008 Frederico Caldeira Knabben
  4  *
  5  * == BEGIN LICENSE ==
  6  *
  7  * Licensed under the terms of any of the following licenses at your
  8  * choice:
  9  *
 10  *  - GNU General Public License Version 2 or later (the "GPL")
 11  *    http://www.gnu.org/licenses/gpl.html
 12  *
 13  *  - GNU Lesser General Public License Version 2.1 or later (the "LGPL")
 14  *    http://www.gnu.org/licenses/lgpl.html
 15  *
 16  *  - Mozilla Public License Version 1.1 or later (the "MPL")
 17  *    http://www.mozilla.org/MPL/MPL-1.1.html
 18  *
 19  * == END LICENSE ==
 20  */
 21
 22 /**
 23  * @fileOverview Defines the {@link CKEDITOR.tools} object, which constains
 24  *		utility functions.
 25  */
 26
 27 /**
 28  * Utility functions.
 29  * @namespace
 30  * @example
 31  */
 32 CKEDITOR.tools =
 33 {
 34 	/**
 35 	 * Evaluates a script in a window (global) scope.
 36 	 * @param {String} script The script code to be evaluated.
 37 	 * @param {Object} [win] The target window. Defaults to the current window.
 38 	 * @type undefined
 39 	 * @example
 40 	 * var script = 'function sample() { alert( "Go!" ); }';
 41 	 *
 42 	 * // Evaluates a script in the current window.
 43 	 * CKEDITOR.tools.globalEval( script );
 44 	 *
 45 	 * // Evaluates a script in the parent window.
 46 	 * CKEDITOR.tools.globalEval( script, window.parent );
 47 	 *
 48 	 * // Alerts "Go!" twice.
 49 	 * window.sample();
 50 	 * window.parent.sample();
 51 	 */
 52 	globalEval : function( script, win )
 53 	{
 54 		if ( !win )
 55 			win = window;
 56
 57 		if ( win.execScript )
 58 			win.execScript( script );	// IE
 59 		else if ( CKEDITOR.env.webkit )
 60 		{
 61 			// win.eval in Safari executes in the current window environment,
 62 			// instead of win. The following should make it work.
 63 			var doc = win.document;
 64 			var scriptEl = doc.createElement('script');
 65 			scriptEl.appendChild( doc.createTextNode( script ) );
 66 			doc.documentElement.appendChild( scriptEl );
 67 		}
 68 		else
 69 			eval.call( win, script );
 70 	},
 71
 72 	/**
 73 	 * Copy the properties from one object to another. By default, properties
 74 	 * already present in the target object <strong>are not</strong> overwritten.
 75 	 * @param {Object} target The object to be extended.
 76 	 * @param {Object} source The object from which copy properties.
 77 	 * @param {Boolean} [overwrite] Indicates that properties already present
 78 	 *		in the target object must be overwritten.
 79 	 * @returns {Object} the extended object (target).
 80 	 * @example
 81 	 * // Create the sample object.
 82 	 * var myObject =
 83 	 * {
 84 	 *     prop1 : true
 85 	 * };
 86 	 *
 87 	 * // Extend the above object with two properties.
 88 	 * CKEDITOR.tools.extend( myObject,
 89 	 *     {
 90 	 *         prop2 : true,
 91 	 *         prop3 : true
 92 	 *     } );
 93 	 *
 94 	 * // Alert "prop1", "prop2" and "prop3".
 95 	 * for ( var p in myObject )
 96 	 *     alert( p ) ;
 97 	 */
 98 	extend : function( target, source, overwrite )
 99 	{
100 		for ( var propertyName in source )
101 		{
102 			if ( overwrite || target[ propertyName ] == undefined )
103 				target[ propertyName ] = source[ propertyName ];
104 		}
105 		return target;
106 	},
107
108 	/**
109 	 * Checks if an object is an Array.
110 	 * @param {Object} object The object to be checked.
111 	 * @type Boolean
112 	 * @returns <i>true</i> if the object is an Array, otherwise <i>false</i>.
113 	 * @example
114 	 * alert( CKEDITOR.tools.isArray( [] ) );      // "true"
115 	 * alert( CKEDITOR.tools.isArray( 'Test' ) );  // "false"
116 	 */
117 	isArray : function( object )
118 	{
119 		return ( object && object instanceof Array );
120 	}
121 };
122