Docs: Improve JSDoc for `pointer.js`.
Props maartenleenders, dfangstrom. Fixes #44325. Built from https://develop.svn.wordpress.org/trunk@43346 git-svn-id: http://core.svn.wordpress.org/trunk@43174 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
atimmer
parent
6172dab7c1
commit
6a9a5e123c
|
|
@ -1,14 +1,12 @@
|
|||
/* 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',
|
||||
|
|
@ -37,6 +35,14 @@
|
|||
document: document
|
||||
},
|
||||
|
||||
/**
|
||||
* A class that represents a WordPress pointer.
|
||||
*
|
||||
* @since 3.3.0
|
||||
* @private
|
||||
*
|
||||
* @constructs $.widget.wp.pointer
|
||||
*/
|
||||
_create: function() {
|
||||
var positioning,
|
||||
family;
|
||||
|
|
@ -59,6 +65,23 @@
|
|||
.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;
|
||||
|
|
@ -85,15 +108,45 @@
|
|||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* 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,
|
||||
|
|
@ -124,8 +177,15 @@
|
|||
},
|
||||
|
||||
/**
|
||||
* Update is separated into two functions to allow events to defer
|
||||
* updating the pointer (e.g. fetch content with ajax, etc).
|
||||
* Updates the content of the pointer.
|
||||
*
|
||||
* 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,
|
||||
|
|
@ -134,7 +194,8 @@
|
|||
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() );
|
||||
|
|
@ -145,6 +206,14 @@
|
|||
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;
|
||||
|
||||
|
|
@ -166,6 +235,11 @@
|
|||
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;
|
||||
|
|
@ -182,6 +256,17 @@
|
|||
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',
|
||||
|
|
@ -218,6 +303,17 @@
|
|||
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;
|
||||
|
|
@ -230,6 +326,14 @@
|
|||
});
|
||||
},
|
||||
|
||||
/**
|
||||
* 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;
|
||||
|
|
@ -248,6 +352,13 @@
|
|||
}));
|
||||
},
|
||||
|
||||
/**
|
||||
* 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;
|
||||
|
|
@ -263,11 +374,23 @@
|
|||
}));
|
||||
},
|
||||
|
||||
/**
|
||||
* 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 );
|
||||
|
|
@ -275,6 +398,17 @@
|
|||
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,
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
*
|
||||
* @global string $wp_version
|
||||
*/
|
||||
$wp_version = '5.0-alpha-43345';
|
||||
$wp_version = '5.0-alpha-43346';
|
||||
|
||||
/**
|
||||
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||
|
|
|
|||
Loading…
Reference in New Issue