enmi-conf.org: comparison wp/wp-includes/js/wp-pointer.js

Mercurial Mercurial > enmi-conf.org / comparison

summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help

wp/wp-includes/js/wp-pointer.js

changeset 9	177826044cd9
parent 7	cf61fcea0001
child 16	a86126ab1dd4

equal deleted inserted replaced

-:c7c34916027a
+:177826044cd9
+/**
+* @output wp-includes/js/wp-pointer.js
+*/
 /* global wpPointerL10n */
 /**
-* Pointer jQuery widget.
+* Initializes the wp-pointer widget using jQuery UI Widget Factory.
 */
 (function($){
 	var identifier = 0,
 		zindex = 9999;
-	/**
-	 * @class $.widget.wp.pointer
-	 */
 	$.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
 		options: {
 			pointerClass: 'wp-pointer',
 			pointerWidth: 320,
 			content: function() {
 				t.closed();
 			},
 			document: document
 		},
+		/**
+		 * A class that represents a WordPress pointer.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @constructs $.widget.wp.pointer
+		 */
 		_create: function() {
 			var positioning,
 				family;
 			this.content = $('<div class="wp-pointer-content"></div>');
 				.addClass( this.options.pointerClass )
 				.css({'position': positioning, 'width': this.options.pointerWidth+'px', 'display': 'none'})
 				.appendTo( this.options.document.body );
 		},
+		/**
+		 * Sets an option on the pointer instance.
+		 *
+		 * There are 4 special values that do something extra:
+		 *
+		 * - `document`     will transfer the pointer to the body of the new document
+		 *                  specified by the value.
+		 * - `pointerClass` will change the class of the pointer element.
+		 * - `position`     will reposition the pointer.
+		 * - `content`      will update the content of the pointer.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {string} key   The key of the option to set.
+		 * @param {*}      value The value to set the option to.
+		 */
 		_setOption: function( key, value ) {
 			var o   = this.options,
 				tip = this.pointer;
 			// Handle document transfer
 			} else if ( key === 'content' && this.active ) {
 				this.update();
 			}
 		},
+		/**
+		 * Removes the pointer element from of the DOM.
+		 *
+		 * Makes sure that the widget and all associated bindings are destroyed.
+		 *
+		 * @since 3.3.0
+		 */
 		destroy: function() {
 			this.pointer.remove();
 			$.Widget.prototype.destroy.call( this );
 		},
+		/**
+		 * Returns the pointer element.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @return {Object} Pointer The pointer object.
+		 */
 		widget: function() {
 			return this.pointer;
 		},
+		/**
+		 * Updates the content of the pointer.
+		 *
+		 * This function doesn't update the content of the pointer itself. That is done
+		 * by the `_update` method. This method will make sure that the `_update` method
+		 * is called with the right content.
+		 *
+		 * The content in the options can either be a string or a callback. If it is a
+		 * callback the result of this callback is used as the content.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event The event that caused the update.
+		 *
+		 * @return {Promise} Resolves when the update has been executed.
+		 */
 		update: function( event ) {
 			var self = this,
 				o    = this.options,
 				dfd  = $.Deferred(),
 				content;
 			return dfd.promise();
 		},
 		/**
-		 * Update is separated into two functions to allow events to defer
+		 * Updates the content of the pointer.
-		 * updating the pointer (e.g. fetch content with ajax, etc).
+		 *
+		 * Will make sure that the pointer is correctly positioned.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {Object} event   The event that caused the update.
+		 * @param {*}      content The content object. Either a string or a jQuery tree.
 		 */
 		_update: function( event, content ) {
 			var buttons,
 				o = this.options;
 			if ( ! content )
 				return;
-			this.pointer.stop(); // Kill any animations on the pointer.
+			// Kill any animations on the pointer.
+			this.pointer.stop();
 			this.content.html( content );
 			buttons = o.buttons.call( this.element[0], event, this._handoff() );
 			if ( buttons ) {
 				buttons.wrap('<div class="wp-pointer-buttons" />').parent().appendTo( this.content );
 			}
 			this.reposition();
 		},
+		/**
+		 * Repositions the pointer.
+		 *
+		 * Makes sure the pointer is the correct size for its content and makes sure it
+		 * is positioned to point to the right element.
+		 *
+		 * @since 3.3.0
+		 */
 		reposition: function() {
 			var position;
 			if ( this.options.disabled )
 				return;
 			}, position )); // the object comes before this.options.position so the user can override position.of.
 			this.repoint();
 		},
+		/**
+		 * Sets the arrow of the pointer to the correct side of the pointer element.
+		 *
+		 * @since 3.3.0
+		 */
 		repoint: function() {
 			var o = this.options,
 				edge;
 			if ( o.disabled )
 			// Add arrow class.
 			this.pointer.addClass( 'wp-pointer-' + edge );
 		},
+		/**
+		 * Calculates the correct position based on a position in the settings.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {string|Object} position Either a side of a pointer or an object
+		 *                                 containing a pointer.
+		 *
+		 * @return {Object} result  An object containing position related data.
+		 */
 		_processPosition: function( position ) {
 			var opposite = {
 					top: 'bottom',
 					bottom: 'top',
 					left: 'right',
 			}
 			return result;
 		},
+		/**
+		 * Opens the pointer.
+		 *
+		 * Only opens the pointer widget in case it is closed and not disabled, and
+		 * calls 'update' before doing so. Calling update makes sure that the pointer
+		 * is correctly sized and positioned.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event The event that triggered the opening of this pointer.
+		 */
 		open: function( event ) {
 			var self = this,
 				o    = this.options;
 			if ( this.active || o.disabled || this.element.is(':hidden') )
 			this.update().done( function() {
 				self._open( event );
 			});
 		},
+		/**
+		 * Opens and shows the pointer element.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {Object} event An event object.
+		 */
 		_open: function( event ) {
 			var self = this,
 				o    = this.options;
 			if ( this.active || o.disabled || this.element.is(':hidden') )
 					self._trigger( 'opened', event, self._handoff() );
 				}
 			}));
 		},
+		/**
+		 * Closes and hides the pointer element.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event An event object.
+		 */
 		close: function( event ) {
 			if ( !this.active || this.options.disabled )
 				return;
 			var self = this;
 					self._trigger( 'closed', event, self._handoff() );
 				}
 			}));
 		},
+		/**
+		 * Puts the pointer on top by increasing the z-index.
+		 *
+		 * @since 3.3.0
+		 */
 		sendToTop: function() {
 			if ( this.active )
 				this.pointer.css( 'z-index', zindex++ );
 		},
+		/**
+		 * Toggles the element between shown and hidden.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event An event object.
+		 */
 		toggle: function( event ) {
 			if ( this.pointer.is(':hidden') )
 				this.open( event );
 			else
 				this.close( event );
 		},
+		/**
+		 * Extends the pointer and the widget element with the supplied parameter, which
+		 * is either an element or a function.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {Object} extend The object to be merged into the original object.
+		 *
+		 * @return {Object} The extended object.
+		 */
 		_handoff: function( extend ) {
 			return $.extend({
 				pointer: this.pointer,
 				element: this.element
 			}, extend);

enmi-conf.org