-/**
+/*!
* These plugins provide extra functionality for interaction with textareas.
*
* - encapsulateSelection: Ported from skins/common/edit.js by Trevor Parscal
* https://github.com/Wikia/app/blob/c0cd8b763/extensions/wikia/LinkSuggest/js/jquery.wikia.linksuggest.js
* © 2010 Inez Korczyński (korczynski@gmail.com) & Jesús Martínez Novo (martineznovo@gmail.com) (GPLv2)
*/
+
+/**
+ * @class jQuery.plugin.textSelection
+ *
+ * Do things to the selection in a `<textarea>`, or a textarea-like editable element.
+ *
+ * var $textbox = $( '#wpTextbox1' );
+ * $textbox.textSelection( 'setContents', 'This is bold!' );
+ * $textbox.textSelection( 'setSelection', { start: 8, end: 12 } );
+ * $textbox.textSelection( 'encapsulateSelection', { pre: '<b>', post: '</b>' } );
+ * // Result: Textbox contains 'This is <b>bold</b>!', with cursor before the '!'
+ */
( function ( $ ) {
+ /**
+ * Do things to the selection in a `<textarea>`, or a textarea-like editable element.
+ *
+ * var $textbox = $( '#wpTextbox1' );
+ * $textbox.textSelection( 'setContents', 'This is bold!' );
+ * $textbox.textSelection( 'setSelection', { start: 8, end: 12 } );
+ * $textbox.textSelection( 'encapsulateSelection', { pre: '<b>', post: '</b>' } );
+ * // Result: Textbox contains 'This is <b>bold</b>!', with cursor before the '!'
+ *
+ * @param {string} command Command to execute, one of:
+ *
+ * - {@link jQuery.plugin.textSelection#getContents getContents}
+ * - {@link jQuery.plugin.textSelection#setContents setContents}
+ * - {@link jQuery.plugin.textSelection#getSelection getSelection}
+ * - {@link jQuery.plugin.textSelection#encapsulateSelection encapsulateSelection}
+ * - {@link jQuery.plugin.textSelection#getCaretPosition getCaretPosition}
+ * - {@link jQuery.plugin.textSelection#setSelection setSelection}
+ * - {@link jQuery.plugin.textSelection#scrollToCaretPosition scrollToCaretPosition}
+ * - {@link jQuery.plugin.textSelection#register register}
+ * - {@link jQuery.plugin.textSelection#unregister unregister}
+ * @param {Mixed} [options] Options to pass to the command
+ * @return {Mixed} Depending on the command
+ */
$.fn.textSelection = function ( command, options ) {
var fn,
alternateFn,
fn = {
/**
- * Get the contents of the textarea
+ * Get the contents of the textarea.
*
+ * @private
* @return {string}
*/
getContents: function () {
return this.val();
},
+
/**
- * Set the contents of the textarea, replacing anything that was there before
+ * Set the contents of the textarea, replacing anything that was there before.
*
+ * @private
* @param {string} content
*/
setContents: function ( content ) {
this.val( content );
},
+
/**
* Get the currently selected text in this textarea.
*
+ * @private
* @return {string}
*/
getSelection: function () {
return retval;
},
+
/**
- * Inserts text at the beginning and end of a text selection, optionally
+ * Insert text at the beginning and end of a text selection, optionally
* inserting text at the caret when selection is empty.
*
- * @param {Object} options Options
- * FIXME document the options parameters
+ * Also focusses the textarea.
+ *
+ * @private
+ * @param {Object} [options]
+ * @param {string} [options.pre] Text to insert before the cursor/selection
+ * @param {string} [options.peri] Text to insert between pre and post and select afterwards
+ * @param {string} [options.post] Text to insert after the cursor/selection
+ * @param {boolean} [options.ownline=false] Put the inserted text on a line of its own
+ * @param {boolean} [options.replace=false] If there is a selection, replace it with peri
+ * instead of leaving it alone
+ * @param {boolean} [options.selectPeri=true] Select the peri text if it was inserted (but not
+ * if there was a selection and replace==false, or if splitlines==true)
+ * @param {boolean} [options.splitlines=false] If multiple lines are selected, encapsulate
+ * each line individually
+ * @param {number} [options.selectionStart] Position to start selection at
+ * @param {number} [options.selectionEnd=options.selectionStart] Position to end selection at
* @return {jQuery}
+ * @chainable
*/
encapsulateSelection: function ( options ) {
return this.each( function () {
post = options.post;
/**
+ * @ignore
* Check if the selected text is the same as the insert text
*/
function checkSelectedText() {
}
/**
+ * @ignore
* Do the splitlines stuff.
*
* Wrap each line of the selected text with pre and post
options.replace, options.splitlines ] );
} );
},
+
/**
- * Get the position (in resolution of bytes not necessarily characters)
- * in a textarea
+ * Get the current cursor position (in UTF-16 code units) in a textarea.
*
- * @param {Object} options Options
- * FIXME document the options parameters
- * @return {number} Position
+ * @private
+ * @param {Object} [options]
+ * @param {Object} [options.startAndEnd=false] Return range of the selection rather than just start
+ * @return {Mixed}
+ * - When `startAndEnd` is `false`: number
+ * - When `startAndEnd` is `true`: array with two numbers, for start and end of selection
*/
getCaretPosition: function ( options ) {
function getCaret( e ) {
}
return getCaret( this.get( 0 ) );
},
+
/**
- * @param {Object} options options
- * FIXME document the options parameters
+ * Set the current cursor position (in UTF-16 code units) in a textarea.
+ *
+ * @private
+ * @param {Object} [options]
+ * @param {number} options.start
+ * @param {number} [options.end=options.start]
* @return {jQuery}
+ * @chainable
*/
setSelection: function ( options ) {
return this.each( function () {
}
} );
},
+
/**
* Scroll a textarea to the current cursor position. You can set the cursor
- * position with setSelection()
+ * position with #setSelection.
*
- * @param {Object} options options
- * @cfg {boolean} [force=false] Whether to force a scroll even if the caret position
+ * @private
+ * @param {Object} [options]
+ * @param {string} [options.force=false] Whether to force a scroll even if the caret position
* is already visible.
- * FIXME document the options parameters
* @return {jQuery}
+ * @chainable
*/
scrollToCaretPosition: function ( options ) {
function getLineLength( e ) {
}
};
+ /**
+ * @method register
+ *
+ * Register an alternative textSelection API for this element.
+ *
+ * @private
+ * @param {Object} functions Functions to replace. Keys are command names (as in #textSelection,
+ * except 'register' and 'unregister'). Values are functions to execute when a given command is
+ * called.
+ */
+
+ /**
+ * @method unregister
+ *
+ * Unregister the alternative textSelection API for this element (see #register).
+ *
+ * @private
+ */
+
alternateFn = $( this ).data( 'jquery.textSelection' );
// Apply defaults
// case 'getSelection': // no params
case 'encapsulateSelection':
options = $.extend( {
- pre: '', // Text to insert before the cursor/selection
- peri: '', // Text to insert between pre and post and select afterwards
- post: '', // Text to insert after the cursor/selection
- ownline: false, // Put the inserted text on a line of its own
- replace: false, // If there is a selection, replace it with peri instead of leaving it alone
- selectPeri: true, // Select the peri text if it was inserted (but not if there was a selection and replace==false, or if splitlines==true)
- splitlines: false, // If multiple lines are selected, encapsulate each line individually
- selectionStart: undefined, // Position to start selection at
- selectionEnd: undefined // Position to end selection at. Defaults to start
+ pre: '',
+ peri: '',
+ post: '',
+ ownline: false,
+ replace: false,
+ selectPeri: true,
+ splitlines: false,
+ selectionStart: undefined,
+ selectionEnd: undefined
}, options );
break;
case 'getCaretPosition':
options = $.extend( {
- // Return [start, end] instead of just start
startAndEnd: false
}, options );
break;
case 'setSelection':
options = $.extend( {
- // Position to start selection at
start: undefined,
- // Position to end selection at. Defaults to start
end: undefined
}, options );
-
if ( options.end === undefined ) {
options.end = options.start;
}
break;
case 'scrollToCaretPosition':
options = $.extend( {
- force: false // Force a scroll even if the caret position is already visible
+ force: false
}, options );
break;
case 'register':
return retval;
};
+ /**
+ * @class jQuery
+ */
+ /**
+ * @method textSelection
+ * @inheritdoc jQuery.plugin.textSelection#textSelection
+ */
+
}( jQuery ) );