add extjs 6.0.1 sources

[extjs.git] / extjs / modern / modern / src / field / Text.js

/**\r
 * The text field is the basis for most of the input fields. It provides a baseline of shared\r
 * functionality such as input validation, standard events, state management and look and feel. Typically we create\r
 * text fields inside a form, like this:\r
 *\r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         fullscreen: true,\r
 *         items: [\r
 *             {\r
 *                 xtype: 'fieldset',\r
 *                 title: 'Enter your name',\r
 *                 items: [\r
 *                     {\r
 *                         xtype: 'textfield',\r
 *                         label: 'First Name',\r
 *                         name: 'firstName'\r
 *                     },\r
 *                     {\r
 *                         xtype: 'textfield',\r
 *                         label: 'Last Name',\r
 *                         name: 'lastName'\r
 *                     }\r
 *                 ]\r
 *             }\r
 *         ]\r
 *     });\r
 *\r
 * This creates two text fields inside a form. Text Fields can also be created outside of a Form, like this:\r
 *\r
 *     Ext.create('Ext.field.Text', {\r
 *         label: 'Your Name',\r
 *         value: 'Ed Spencer'\r
 *     });\r
 *\r
 * ## Configuring\r
 *\r
 * Text field offers several configuration options, including {@link #placeHolder}, {@link #maxLength},\r
 * {@link #autoComplete}, {@link #autoCapitalize} and {@link #autoCorrect}. For example, here is how we would configure\r
 * a text field to have a maximum length of 10 characters, with placeholder text that disappears when the field is\r
 * focused:\r
 *\r
 *     Ext.create('Ext.field.Text', {\r
 *         label: 'Username',\r
 *         maxLength: 10,\r
 *         placeHolder: 'Enter your username'\r
 *     });\r
 *\r
 * The autoComplete, autoCapitalize and autoCorrect configs simply set those attributes on the text field and allow the\r
 * native browser to provide those capabilities. For example, to enable auto complete and auto correct, simply\r
 * configure your text field like this:\r
 *\r
 *     Ext.create('Ext.field.Text', {\r
 *         label: 'Username',\r
 *         autoComplete: true,\r
 *         autoCorrect: true\r
 *     });\r
 *\r
 * These configurations will be picked up by the native browser, which will enable the options at the OS level.\r
 *\r
 * Text field inherits from {@link Ext.field.Field}, which is the base class for all fields and provides\r
 * a lot of shared functionality for all fields, including setting values, clearing and basic validation. See the\r
 * {@link Ext.field.Field} documentation to see how to leverage its capabilities.\r
 */\r
Ext.define('Ext.field.Text', {\r
    extend: 'Ext.field.Field',\r
    xtype: 'textfield',\r
    alternateClassName: 'Ext.form.Text',\r
\r
    /**\r
     * @event focus\r
     * Fires when this field receives input focus\r
     * @param {Ext.field.Text} this This field\r
     * @param {Ext.event.Event} e\r
     */\r
\r
    /**\r
     * @event blur\r
     * Fires when this field loses input focus\r
     * @param {Ext.field.Text} this This field\r
     * @param {Ext.event.Event} e\r
     */\r
\r
    /**\r
     * @event paste\r
     * Fires when this field is pasted.\r
     * @param {Ext.field.Text} this This field\r
     * @param {Ext.event.Event} e\r
     */\r
\r
    /**\r
     * @event mousedown\r
     * Fires when this field receives a mousedown\r
     * @param {Ext.field.Text} this This field\r
     * @param {Ext.event.Event} e\r
     */\r
\r
    /**\r
     * @event keyup\r
     * @preventable\r
     * Fires when a key is released on the input element\r
     * @param {Ext.field.Text} this This field\r
     * @param {Ext.event.Event} e\r
     */\r
\r
    /**\r
     * @event clearicontap\r
     * @preventable\r
     * Fires when the clear icon is tapped\r
     * @param {Ext.field.Text} this This field\r
     * @param {Ext.field.Input} input The field's input component.\r
     * @param {Ext.event.Event} e\r
     */\r
\r
    /**\r
     * @event change\r
     * Fires when the value has changed.\r
     * @param {Ext.field.Text} this This field\r
     * @param {String} newValue The new value\r
     * @param {String} oldValue The original value\r
     */\r
\r
    /**\r
     * @event action\r
     * @preventable\r
     * Fires whenever the return key or go is pressed. FormPanel listeners\r
     * for this event, and submits itself whenever it fires. Also note\r
     * that this event bubbles up to parent containers.\r
     * @param {Ext.field.Text} this This field\r
     * @param {Mixed} e The key event object\r
     */\r
\r
    config: {\r
        /**\r
         * @cfg\r
         * @inheritdoc\r
         */\r
        ui: 'text',\r
\r
        /**\r
         * @cfg\r
         * @inheritdoc\r
         */\r
        clearIcon: true,\r
\r
        /**\r
         * @cfg {String} placeHolder A string value displayed in the input (if supported) when the control is empty.\r
         * @accessor\r
         */\r
        placeHolder: null,\r
\r
        /**\r
         * @cfg {Number} maxLength The maximum number of permitted input characters.\r
         * @accessor\r
         */\r
        maxLength: null,\r
\r
        /**\r
         * True to set the field's DOM element autocomplete attribute to "on", false to set to "off".\r
         * @cfg {Boolean} autoComplete\r
         * @accessor\r
         */\r
        autoComplete: null,\r
\r
        /**\r
         * True to set the field's DOM element autocapitalize attribute to "on", false to set to "off".\r
         * @cfg {Boolean} autoCapitalize\r
         * @accessor\r
         */\r
        autoCapitalize: null,\r
\r
        /**\r
         * True to set the field DOM element autocorrect attribute to "on", false to set to "off".\r
         * @cfg {Boolean} autoCorrect\r
         * @accessor\r
         */\r
        autoCorrect: null,\r
\r
        /**\r
         * True to set the field DOM element readonly attribute to true.\r
         * @cfg {Boolean} readOnly\r
         * @accessor\r
         */\r
        readOnly: null,\r
\r
        /**\r
         * @cfg {Object} component The inner component for this field, which defaults to an input text.\r
         * @accessor\r
         */\r
        component: {\r
            xtype: 'input',\r
            type: 'text',\r
            fastFocus: false\r
        },\r
\r
        bubbleEvents: ['action']\r
    },\r
\r
    defaultBindProperty: 'value',\r
    twoWayBindable: {\r
        value: 1\r
    },\r
    \r
    publishes: {\r
        value: 1\r
    },\r
\r
    focusedCls: Ext.baseCSSPrefix + 'field-focused',\r
    clearableCls: Ext.baseCSSPrefix + 'field-clearable',\r
    emptyCls: Ext.baseCSSPrefix + 'empty',\r
\r
    /**\r
     * @private\r
     */\r
    initialize: function() {\r
        var me = this;\r
\r
        me.callParent();\r
\r
        me.getComponent().on({\r
            scope: this,\r
\r
            keyup       : 'onKeyUp',\r
            input       : 'onInput',\r
            focus       : 'onFocus',\r
            blur        : 'onBlur',\r
            paste       : 'onPaste',\r
            mousedown   : 'onMouseDown',\r
            clearicontap: 'onClearIconTap'\r
        });\r
\r
        // set the originalValue of the textfield, if one exists\r
        me.originalValue = me.getValue() || "";\r
        me.getComponent().originalValue = me.originalValue;\r
\r
        me.syncEmptyCls();\r
    },\r
\r
    syncEmptyCls: function() {\r
        var val = this._value,\r
            empty = val ? val.length : false;\r
\r
        this.toggleCls(this.emptyCls, !empty);\r
    },\r
\r
    applyValue: function(value) {\r
        return Ext.isEmpty(value) ? '' : value;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateValue: function(value, oldValue) {\r
        var me = this,\r
            component  = me.getComponent(),\r
            // allows value to be zero but not undefined or null (other falsey values)\r
            valueValid = value !== undefined && value !== null && value !== '';\r
\r
        if (component) {\r
            component.setValue(value);\r
        }\r
\r
        me.toggleClearIcon(valueValid && me.isDirty())\r
\r
        me.syncEmptyCls();\r
\r
        if (me.initialized) {\r
            me.fireEvent('change', me, value, oldValue);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updatePlaceHolder: function(newPlaceHolder) {\r
        this.getComponent().setPlaceHolder(newPlaceHolder);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateMaxLength: function(newMaxLength) {\r
        this.getComponent().setMaxLength(newMaxLength);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateAutoComplete: function(newAutoComplete) {\r
        this.getComponent().setAutoComplete(newAutoComplete);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateAutoCapitalize: function(newAutoCapitalize) {\r
        this.getComponent().setAutoCapitalize(newAutoCapitalize);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateAutoCorrect: function(newAutoCorrect) {\r
        this.getComponent().setAutoCorrect(newAutoCorrect);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateReadOnly: function(newReadOnly) {\r
        this.toggleClearIcon(!newReadOnly);\r
        this.getComponent().setReadOnly(newReadOnly);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateInputType: function(newInputType) {\r
        var component = this.getComponent();\r
        if (component) {\r
            component.setType(newInputType);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateName: function(newName) {\r
        var component = this.getComponent();\r
        if (component) {\r
            component.setName(newName);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateTabIndex: function(newTabIndex) {\r
        var component = this.getComponent();\r
        if (component) {\r
            component.setTabIndex(newTabIndex);\r
        }\r
    },\r
\r
    /**\r
     * Updates the {@link #inputCls} configuration on this fields {@link #component}\r
     * @private\r
     */\r
    updateInputCls: function(newInputCls, oldInputCls) {\r
        var component = this.getComponent();\r
        if (component) {\r
            component.replaceCls(oldInputCls, newInputCls);\r
        }\r
    },\r
\r
    updateDisabled: function(disabled, oldDisabled) {\r
        this.callParent([disabled, oldDisabled]);\r
\r
        var component = this.getComponent();\r
        if (component) {\r
            component.setDisabled(disabled);\r
        }\r
\r
        this.toggleClearIcon(!disabled);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    showClearIcon: function() {\r
        var me         = this,\r
            value      = me.getValue(),\r
            // allows value to be zero but not undefined or null (other falsey values)\r
            valueValid = value !== undefined && value !== null && value !== "";\r
\r
        if (me.getClearIcon() && !me.getDisabled() && !me.getReadOnly() && valueValid) {\r
            me.element.addCls(me.clearableCls);\r
        }\r
\r
        return me;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    hideClearIcon: function() {\r
        if (this.getClearIcon()) {\r
            this.element.removeCls(this.clearableCls);\r
        }\r
    },\r
\r
    onKeyUp: function(e) {\r
        this.fireAction('keyup', [this, e], 'doKeyUp');\r
    },\r
\r
    /**\r
     * Called when a key has been pressed in the `<input>`\r
     * @private\r
     */\r
    doKeyUp: function(me, e) {\r
        // getValue to ensure that we are in sync with the dom\r
        var value      = me.getValue(),\r
            // allows value to be zero but not undefined or null (other falsey values)\r
            valueValid = value !== undefined && value !== null && value !== '';\r
\r
        me.toggleClearIcon(valueValid);\r
\r
        if (e.browserEvent.keyCode === 13) {\r
            me.fireAction('action', [me, e], 'doAction');\r
        }\r
    },\r
\r
    doAction: function() {\r
        this.blur();\r
    },\r
\r
    onClearIconTap: function(input, e) {\r
        this.fireAction('clearicontap', [this, input, e], 'doClearIconTap');\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    doClearIconTap: function(me, e) {\r
        me.setValue('');\r
    },\r
\r
    onInput: function(component, value) {\r
        this.setValue(value);\r
    },\r
\r
    onFocus: function(e) {\r
        var me = this;\r
\r
        me.addCls(me.focusedCls);\r
        me.isFocused = true;\r
        me.fireEvent('focus', me, e);\r
    },\r
\r
    onBlur: function(e) {\r
        var me = this;\r
\r
        me.removeCls(me.focusedCls);\r
        me.isFocused = false;\r
\r
        me.fireEvent('blur', me, e);\r
\r
        Ext.defer(function() {\r
            me.isFocused = false;\r
        }, 50);\r
    },\r
\r
    onPaste: function(e) {\r
        this.fireEvent('paste', this, e);\r
    },\r
\r
    onMouseDown: function(e) {\r
        this.fireEvent('mousedown', this, e);\r
    },\r
\r
    /**\r
     * Attempts to set the field as the active input focus.\r
     * @return {Ext.field.Text} This field\r
     */\r
    focus: function() {\r
        this.getComponent().focus();\r
        return this;\r
    },\r
\r
    /**\r
     * Attempts to forcefully blur input focus for the field.\r
     * @return {Ext.field.Text} This field\r
     */\r
    blur: function() {\r
        this.getComponent().blur();\r
        return this;\r
    },\r
\r
    /**\r
     * Attempts to forcefully select all the contents of the input field.\r
     * @return {Ext.field.Text} this\r
     */\r
    select: function() {\r
        this.getComponent().select();\r
        return this;\r
    },\r
\r
    resetOriginalValue: function() {\r
        var me = this,\r
            comp;\r
\r
        me.callParent();\r
        component = me.getComponent();\r
        if(component && component.hasOwnProperty("originalValue")) {\r
            me.getComponent().originalValue = me.originalValue;\r
        }\r
        me.reset();\r
    },\r
\r
    reset: function() {\r
        var me = this;\r
        me.getComponent().reset();\r
\r
        //we need to call this to sync the input with this field\r
        me.getValue();\r
\r
        me.toggleClearIcon(me.isDirty());\r
    },\r
\r
    isDirty: function() {\r
        var component = this.getComponent();\r
        if (component) {\r
            return component.isDirty();\r
        }\r
        return false;\r
    },\r
\r
    privates: {\r
        toggleClearIcon: function(state) {\r
            if (state) {\r
                this.showClearIcon();\r
            } else {\r
                this.hideClearIcon();\r
            }\r
        }\r
    }\r
});\r
\r