src/data/var/dataPriv.js

/*
 * Copyright 2000-2022 Vaadin Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package com.vaadin.v7.ui;

import java.util.Collection;
import java.util.Map;

import org.jsoup.nodes.Attributes;
import org.jsoup.nodes.Element;

import com.vaadin.event.FieldEvents.BlurEvent;
import com.vaadin.event.FieldEvents.BlurListener;
import com.vaadin.event.FieldEvents.FocusEvent;
import com.vaadin.event.FieldEvents.FocusListener;
import com.vaadin.server.PaintException;
import com.vaadin.server.PaintTarget;
import com.vaadin.ui.LegacyComponent;
import com.vaadin.ui.declarative.DesignAttributeHandler;
import com.vaadin.ui.declarative.DesignContext;
import com.vaadin.v7.event.FieldEvents.BlurNotifier;
import com.vaadin.v7.event.FieldEvents.FocusNotifier;
import com.vaadin.v7.event.FieldEvents.TextChangeEvent;
import com.vaadin.v7.event.FieldEvents.TextChangeListener;
import com.vaadin.v7.event.FieldEvents.TextChangeNotifier;
import com.vaadin.v7.shared.ui.textfield.AbstractTextFieldState;
import com.vaadin.v7.shared.ui.textfield.TextFieldConstants;

@Deprecated
public abstract class AbstractTextField extends AbstractField<String> implements
        BlurNotifier, FocusNotifier, TextChangeNotifier, LegacyComponent {

    /**
     * Null representation.
     */
    private String nullRepresentation = "null";
    /**
     * Is setting to null from non-null value allowed by setting with null
     * representation .
     */
    private boolean nullSettingAllowed = false;
    /**
     * The text content when the last messages to the server was sent. Cleared
     * when value is changed.
     */
    private String lastKnownTextContent;

    /**
     * The position of the cursor when the last message to the server was sent.
     */
    private int lastKnownCursorPosition;

    /**
     * Flag indicating that a text change event is pending to be triggered.
     * Cleared by {@link #setInternalValue(Object)} and when the event is fired.
     */
    private boolean textChangeEventPending;

    private boolean isFiringTextChangeEvent = false;

    private TextChangeEventMode textChangeEventMode = TextChangeEventMode.LAZY;

    private static final int DEFAULT_TEXTCHANGE_TIMEOUT = 400;

    private int textChangeEventTimeout = DEFAULT_TEXTCHANGE_TIMEOUT;

    /**
     * Temporarily holds the new selection position. Cleared on paint.
     */
    private int selectionPosition = -1;

    /**
     * Temporarily holds the new selection length.
     */
    private int selectionLength;

    /**
     * Flag used to determine whether we are currently handling a state change
     * triggered by a user. Used to properly fire text change event before value
     * change event triggered by the client side.
     */
    private boolean changingVariables;

    protected AbstractTextField() {
        super();
    }

    @Override
    protected AbstractTextFieldState getState() {
        return (AbstractTextFieldState) super.getState();
    }

    @Override
    protected AbstractTextFieldState getState(boolean markAsDirty) {
        return (AbstractTextFieldState) super.getState(markAsDirty);
    }

    @Override
    public void beforeClientResponse(boolean initial) {
        super.beforeClientResponse(initial);

        String value = getValue();
        if (value == null) {
            value = getNullRepresentation();
        }
        getState().text = value;
    }

    @Override
    public void paintContent(PaintTarget target) throws PaintException {

        if (selectionPosition != -1) {
            target.addAttribute("selpos", selectionPosition);
            target.addAttribute("sellen", selectionLength);
            selectionPosition = -1;
        }

        if (hasListeners(TextChangeEvent.class)) {
            target.addAttribute(TextFieldConstants.ATTR_TEXTCHANGE_EVENTMODE,
                    getTextChangeEventMode().toString());
            target.addAttribute(TextFieldConstants.ATTR_TEXTCHANGE_TIMEOUT,
                    getTextChangeTimeout());
            if (lastKnownTextContent != null) {
                /*
                 * The field has be repainted for some reason (e.g. caption,
                 * size, stylename), but the value has not been changed since
                 * the last text change event. Let the client side know about
                 * the value the server side knows. Client side may then ignore
                 * the actual value, depending on its state.
                 */
                target.addAttribute(
                        TextFieldConstants.ATTR_NO_VALUE_CHANGE_BETWEEN_PAINTS,
                        true);
            }
        }

    }

    @Override
    public void changeVariables(Object source, Map<String, Object> variables) {
        changingVariables = true;

        try {

            // Sets the height set by the user when resize the <textarea>.
            String newHeight = (String) variables.get("height");
            if (newHeight != null) {
                setHeight(newHeight);
            }

            // Sets the width set by the user when resize the <textarea>.
            String newWidth = (String) variables.get("width");
            if (newWidth != null) {
                setWidth(newWidth);
            }

            if (variables.containsKey(TextFieldConstants.VAR_CURSOR)) {
                Integer object = (Integer) variables
                        .get(TextFieldConstants.VAR_CURSOR);
                lastKnownCursorPosition = object.intValue();
            }

            if (variables.containsKey(TextFieldConstants.VAR_CUR_TEXT)) {
                /*
                 * NOTE, we might want to develop this further so that on a
                 * value change event the whole text content don't need to be
                 * sent from the client to server. Just "commit" the value from
                 * currentText to the value.
                 */
                handleInputEventTextChange(variables);
            }

            // Sets the text
            if (variables.containsKey("text") && !isReadOnly()) {

                // Only do the setting if the string representation of the value
                // has been updated
                String newValue = (String) variables.get("text");

                // server side check for max length
                if (getMaxLength() != -1
                        && newValue.length() > getMaxLength()) {
                    newValue = newValue.substring(0, getMaxLength());
                }
                final String oldValue = getValue();
                if (newValue != null
                        && (oldValue == null || isNullSettingAllowed())
                        && newValue.equals(getNullRepresentation())) {
                    newValue = null;
                }
                if (newValue != oldValue
                        && (newValue == null || !newValue.equals(oldValue))) {
                    boolean wasModified = isModified();
                    setValue(newValue, true);

                    // If the modified status changes, or if we have a
                    // formatter, repaint is needed after all.
                    if (wasModified != isModified()) {
                        markAsDirty();
                    }
                }
            }
            firePendingTextChangeEvent();

            if (variables.containsKey(FocusEvent.EVENT_ID)) {
                fireEvent(new FocusEvent(this));
            }
            if (variables.containsKey(BlurEvent.EVENT_ID)) {
                fireEvent(new BlurEvent(this));
            }
        } finally {
            changingVariables = false;

        }

    }

    @Override
    public Class<String> getType() {
        return String.class;
    }

    /**
     * Gets the null-string representation.
     *
     * <p>
     * The null-valued strings are represented on the user interface by
     * replacing the null value with this string. If the null representation is
     * set null (not 'null' string), painting null value throws exception.
     * </p>
     *
     * <p>
     * The default value is string 'null'.
     * </p>
     *
     * @return the String Textual representation for null strings.
     * @see TextField#isNullSettingAllowed()
     */
    public String getNullRepresentation() {
        return nullRepresentation;
    }

    /**
     * Is setting nulls with null-string representation allowed.
     *
     * <p>
     * If this property is true, writing null-representation string to text
     * field always sets the field value to real null. If this property is
     * false, null setting is not made, but the null values are maintained.
     * Maintenance of null-values is made by only converting the textfield
     * contents to real null, if the text field matches the null-string
     * representation and the current value of the field is null.
     * </p>
     *
     * <p>
     * By default this setting is false
     * </p>
     *
     * @return boolean Should the null-string represenation be always converted
     *         to null-values.
     * @see TextField#getNullRepresentation()
     */
    public boolean isNullSettingAllowed() {
        return nullSettingAllowed;
    }

    /**
     * Sets the null-string representation.
     *
     * <p>
     * The null-valued strings are represented on the user interface by
     * replacing the null value with this string. If the null representation is
     * set null (not 'null' string), painting null value throws exception.
     * </p>
     *
     * <p>
     * The default value is string 'null'
     * </p>
     *
     * @param nullRepresentation
     *            Textual representation for null strings.
     * @see TextField#setNullSettingAllowed(boolean)
     */
    public void setNullRepresentation(String nullRepresentation) {
        this.nullRepresentation = nullRepresentation;
        markAsDirty();
    }

    /**
     * Sets the null conversion mode.
     *
     * <p>
     * If this property is true, writing null-representation string to text
     * field always sets the field value to real null. If this property is
     * false, null setting is not made, but the null values are maintained.
     * Maintenance of null-values is made by only converting the textfield
     * contents to real null, if the text field matches the null-string
     * representation and the current value of the field is null.
     * </p>
     *
     * <p>
     * By default this setting is false.
     * </p>
     *
     * @param nullSettingAllowed
     *            Should the null-string representation always be converted to
     *            null-values.
     * @see TextField#getNullRepresentation()
     */
    public void setNullSettingAllowed(boolean nullSettingAllowed) {
        this.nullSettingAllowed = nullSettingAllowed;
        markAsDirty();
    }

    @Override
    public boolean isEmpty() {
        return super.isEmpty() || getValue().isEmpty();
    }

    /**
     * Returns the maximum number of characters in the field. Value -1 is
     * considered unlimited. Terminal may however have some technical limits.
     *
     * @return the maxLength
     */
    public int getMaxLength() {
        return getState(false).maxLength;
    }

    /**
     * Sets the maximum number of characters in the field. Value -1 is
     * considered unlimited. Terminal may however have some technical limits.
     *
     * @param maxLength
     *            the maxLength to set
     */
    public void setMaxLength(int maxLength) {
        getState().maxLength = maxLength;
    }

    /**
     * Gets the number of columns in the editor. If the number of columns is set
     * 0, the actual number of displayed columns is determined implicitly by the
     * adapter.
     *
     * @return the number of columns in the editor.
     */
    public int getColumns() {
        return getState(false).columns;
    }

    /**
     * Sets the number of columns in the editor. If the number of columns is set
     * 0, the actual number of displayed columns is determined implicitly by the
     * adapter.
     *
     * @param columns
     *            the number of columns to set.
     */
    public void setColumns(int columns) {
        if (columns < 0) {
            columns = 0;
        }
        getState().columns = columns;
    }

    /**
     * Gets the current input prompt.
     *
     * @see #setInputPrompt(String)
     * @return the current input prompt, or null if not enabled
     */
    public String getInputPrompt() {
        return getState(false).inputPrompt;
    }

    /**
     * Sets the input prompt - a textual prompt that is displayed when the field
     * would otherwise be empty, to prompt the user for input.
     *
     * @param inputPrompt
     */
    public void setInputPrompt(String inputPrompt) {
        getState().inputPrompt = inputPrompt;
    }

    /* ** Text Change Events ** */

    private void firePendingTextChangeEvent() {
        if (textChangeEventPending && !isFiringTextChangeEvent) {
            isFiringTextChangeEvent = true;
            textChangeEventPending = false;
            try {
                fireEvent(new TextChangeEventImpl(this));
            } finally {
                isFiringTextChangeEvent = false;
            }
        }
    }

    @Override
    protected void setInternalValue(String newValue) {
        if (changingVariables && !textChangeEventPending) {

            /*
             * TODO check for possible (minor?) issue (not tested)
             *
             * -field with e.g. PropertyFormatter.
             *
             * -TextChangeListener and it changes value.
             *
             * -if formatter again changes the value, do we get an extra
             * simulated text change event ?
             */

            /*
             * Fire a "simulated" text change event before value change event if
             * change is coming from the client side.
             *
             * If there are both value change and textChangeEvent in same
             * variable burst, it is a text field in non immediate mode and the
             * text change event "flushed" queued value change event. In this
             * case textChangeEventPending flag is already on and text change
             * event will be fired after the value change event.
             */
            if (newValue == null && lastKnownTextContent != null
                    && !lastKnownTextContent.equals(getNullRepresentation())) {
                // Value was changed from something to null representation
                lastKnownTextContent = getNullRepresentation();
                textChangeEventPending = true;
            } else if (newValue != null
                    && !newValue.equals(lastKnownTextContent)) {
                // Value was changed to something else than null representation
                lastKnownTextContent = newValue;
                textChangeEventPending = true;
            }
            firePendingTextChangeEvent();
        }

        super.setInternalValue(newValue);
    }

    @Override
    public void setValue(String newValue) throws ReadOnlyException {
        super.setValue(newValue);
        /*
         * Make sure w reset lastKnownTextContent field on value change. The
         * clearing must happen here as well because TextChangeListener can
         * revert the original value. Client must respect the value in this
         * case. AbstractField optimizes value change if the existing value is
         * reset. Also we need to force repaint if the flag is on.
         */
        if (lastKnownTextContent != null) {
            lastKnownTextContent = null;
            markAsDirty();
        }
    }

    private void handleInputEventTextChange(Map<String, Object> variables) {
        /*
         * TODO we could vastly optimize the communication of values by using
         * some sort of diffs instead of always sending the whole text content.
         * Also on value change events we could use the mechanism.
         */
        String object = (String) variables.get(TextFieldConstants.VAR_CUR_TEXT);
        lastKnownTextContent = object;
        textChangeEventPending = true;
    }

    /**
     * Sets the mode how the TextField triggers {@link TextChangeEvent}s.
     *
     * @param inputEventMode
     *            the new mode
     *
     * @see TextChangeEventMode
     */
    public void setTextChangeEventMode(TextChangeEventMode inputEventMode) {
        textChangeEventMode = inputEventMode;
        markAsDirty();
    }

    /**
     * @return the mode used to trigger {@link TextChangeEvent}s.
     */
    public TextChangeEventMode getTextChangeEventMode() {
        return textChangeEventMode;
    }

    /**
     * Different modes how the TextField can trigger {@link TextChangeEvent}s.
     */
    @Deprecated
    public enum TextChangeEventMode {

        /**
         * An event is triggered on each text content change, most commonly key
         * press events.
         */
        EAGER,
        /**
         * Each text change event in the UI causes the event to be communicated
         * to the application after a timeout. The length of the timeout can be
         * controlled with {@link TextField#setTextChangeTimeout(int)}. Only the
         * last input event is reported to the server side if several text
         * change events happen during the timeout.
         * <p>
         * In case of a {@link ValueChangeEvent} the schedule is not kept
         * strictly. Before a {@link ValueChangeEvent} a {@link TextChangeEvent}
         * is triggered if the text content has changed since the previous
         * TextChangeEvent regardless of the schedule.
         */
        TIMEOUT,
        /**
         * An event is triggered when there is a pause of text modifications.
         * The length of the pause can be modified with
         * {@link TextField#setTextChangeTimeout(int)}. Like with the
         * {@link #TIMEOUT} mode, an event is forced before
         * {@link ValueChangeEvent}s, even if the user did not keep a pause
         * while entering the text.
         * <p>
         * This is the default mode.
         */
        LAZY
    }

    @Override
    public void addTextChangeListener(TextChangeListener listener) {
        addListener(TextChangeListener.EVENT_ID, TextChangeEvent.class,
                listener, TextChangeListener.EVENT_METHOD);
    }

    /**
     * @deprecated As of 7.0, replaced by
     *             {@link #addTextChangeListener(TextChangeListener)}
     */
    @Deprecated
    public void addListener(TextChangeListener listener) {
        addTextChangeListener(listener);
    }

    @Override
    public void removeTextChangeListener(TextChangeListener listener) {
        removeListener(TextChangeListener.EVENT_ID, TextChangeEvent.class,
                listener);
    }

    /**
     * @deprecated As of 7.0, replaced by
     *             {@link #removeTextChangeListener(TextChangeListener)}
     */
    @Deprecated
    public void removeListener(TextChangeListener listener) {
        removeTextChangeListener(listener);
    }

    /**
     * The text change timeout modifies how often text change events are
     * communicated to the application when {@link #getTextChangeEventMode()} is
     * {@link TextChangeEventMode#LAZY} or {@link TextChangeEventMode#TIMEOUT}.
     *
     *
     * @see #getTextChangeEventMode()
     *
     * @param timeout
     *            the timeout in milliseconds
     */
    public void setTextChangeTimeout(int timeout) {
        textChangeEventTimeout = timeout;
        markAsDirty();
    }

    /**
     * Gets the timeout used to fire {@link TextChangeEvent}s when the
     * {@link #getTextChangeEventMode()} is {@link TextChangeEventMode#LAZY} or
     * {@link TextChangeEventMode#TIMEOUT}.
     *
     * @return the timeout value in milliseconds
     */
    public int getTextChangeTimeout() {
        return textChangeEventTimeout;
    }

    @Deprecated
    public static class TextChangeEventImpl extends TextChangeEvent {
        private String curText;
        private int cursorPosition;

        private TextChangeEventImpl(final AbstractTextField tf) {
            super(tf);
            curText = tf.getCurrentTextContent();
            cursorPosition = tf.getCursorPosition();
        }

        @Override
        public AbstractTextField getComponent() {
            return (AbstractTextField) super.getComponent();
        }

        @Override
        public String getText() {
            return curText;
        }

        @Override
        public int getCursorPosition() {
            return cursorPosition;
        }

    }

    /**
     * Gets the current (or the last known) text content in the field.
     * <p>
     * Note the text returned by this method is not necessary the same that is
     * returned by the {@link #getValue()} method. The value is updated when the
     * terminal fires a value change event via e.g. blurring the field or by
     * pressing enter. The value returned by this method is updated also on
     * {@link TextChangeEvent}s. Due to this high dependency to the terminal
     * implementation this method is (at least at this point) not published.
     *
     * @return the text which is currently displayed in the field.
     */
    private String getCurrentTextContent() {
        if (lastKnownTextContent != null) {
            return lastKnownTextContent;
        } else {
            Object text = getValue();
            if (text == null) {
                return getNullRepresentation();
            }
            return text.toString();
        }
    }

    /**
     * Selects all text in the field.
     *
     * @since 6.4
     */
    public void selectAll() {
        String text = getValue() == null ? "" : getValue();
        setSelectionRange(0, text.length());
    }

    /**
     * Sets the range of text to be selected.
     *
     * As a side effect the field will become focused.
     *
     * @since 6.4
     *
     * @param pos
     *            the position of the first character to be selected
     * @param length
     *            the number of characters to be selected
     */
    public void setSelectionRange(int pos, int length) {
        selectionPosition = pos;
        selectionLength = length;
        focus();
        markAsDirty();
    }

    /**
     * Sets the cursor position in the field. As a side effect the field will
     * become focused.
     *
     * @since 6.4
     *
     * @param pos
     *            the position for the cursor
     */
    public void setCursorPosition(int pos) {
        setSelectionRange(pos, 0);
        lastKnownCursorPosition = pos;
    }

    /**
     * Returns the last known cursor position of the field.
     *
     * <p>
     * Note that due to the client server nature or the GWT terminal, Vaadin
     * cannot provide the exact value of the cursor position in most situations.
     * The value is updated only when the client side terminal communicates to
     * TextField, like on {@link ValueChangeEvent}s and {@link TextChangeEvent}
     * s. This may change later if a deep push integration is built to Vaadin.
     *
     * @return the cursor position
     */
    public int getCursorPosition() {
        return lastKnownCursorPosition;
    }

    @Override
    public void addFocusListener(FocusListener listener) {
        addListener(FocusEvent.EVENT_ID, FocusEvent.class, listener,
                FocusListener.focusMethod);
    }

    /**
     * @deprecated As of 7.0, replaced by
     *             {@link #addFocusListener(FocusListener)}
     */
    @Deprecated
    public void addListener(FocusListener listener) {
        addFocusListener(listener);
    }

    @Override
    public void removeFocusListener(FocusListener listener) {
        removeListener(FocusEvent.EVENT_ID, FocusEvent.class, listener);
    }

    /**
     * @deprecated As of 7.0, replaced by
     *             {@link #removeFocusListener(FocusListener)}
     */
    @Deprecated
    public void removeListener(FocusListener listener) {
        removeFocusListener(listener);
    }

    @Override
    public void addBlurListener(BlurListener listener) {
        addListener(BlurEvent.EVENT_ID, BlurEvent.class, listener,
                BlurListener.blurMethod);
    }

    /**
     * @deprecated As of 7.0, replaced by {@link #addBlurListener(BlurListener)}
     */
    @Deprecated
    public void addListener(BlurListener listener) {
        addBlurListener(listener);
    }

    @Override
    public void removeBlurListener(BlurListener listener) {
        removeListener(BlurEvent.EVENT_ID, BlurEvent.class, listener);
    }

    /**
     * @deprecated As of 7.0, replaced by
     *             {@link #removeBlurListener(BlurListener)}
     */
    @Deprecated
    public void removeListener(BlurListener listener) {
        removeBlurListener(listener);
    }

    /*
     * (non-Javadoc)
     *
     * @see com.vaadin.ui.AbstractField#readDesign(org.jsoup.nodes.Element ,
     * com.vaadin.ui.declarative.DesignContext)
     */
    @Override
    public void readDesign(Element design, DesignContext designContext) {
        super.readDesign(design, designContext);
        Attributes attr = design.attributes();
        if (attr.hasKey("maxlength")) {
            setMaxLength(DesignAttributeHandler.readAttribute("maxlength", attr,
                    Integer.class));
        }
    }

    /*
     * (non-Javadoc)
     *
     * @see com.vaadin.ui.AbstractField#getCustomAttributes()
     */
    @Override
    protected Collection<String> getCustomAttributes() {
        Collection<String> customAttributes = super.getCustomAttributes();
        customAttributes.add("maxlength");

        // prevent this from appearing in output
        customAttributes.add("max-length");
        customAttributes.add("cursor-position");
        return customAttributes;
    }

    /*
     * (non-Javadoc)
     *
     * @see com.vaadin.ui.AbstractField#writeDesign(org.jsoup.nodes.Element,
     * com.vaadin.ui.declarative.DesignContext)
     */
    @Override
    public void writeDesign(Element design, DesignContext designContext) {
        super.writeDesign(design, designContext);
        AbstractTextField def = (AbstractTextField) designContext
                .getDefaultInstance(this);
        Attributes attr = design.attributes();
        DesignAttributeHandler.writeAttribute("maxlength", attr, getMaxLength(),
                def.getMaxLength(), Integer.class, designContext);
    }

}
	Commit message (Collapse)	Author	Age	Files	Lines
*	Core: Use named exports in `src/`	Michał Gołębiowski-Owczarek	2023-09-12	1	-2/+2
\| \| \| \| \| \| \| \| \|	The `default` export is treated differently across tooling when transpiled to CommonJS - tools differ on whether `module.exports` represents the full module object or just its default export. Switch `src/` modules to named exports for tooling consistency. Fixes gh-5262 Closes gh-5292
*	Core: Migrate from AMD to ES modules 🎉	Michał Gołębiowski-Owczarek	2019-11-18	1	-6/+2
\| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \| \|	Migrate all source AMD modules to ECMAScript modules. The final bundle is compiled by a custom build process that uses Rollup under the hood. Test files themselves are still loaded via RequireJS as that has to work in IE 11. Tests can now be run in "Load as modules" mode which replaces the previous "Load with AMD" option. That option of running tests doesn't work in IE and Edge as it requires support for dynamic imports. Some of the changes required by the migration: * check `typeof` of `noGlobal` instead of using the variable directly as it's not available when modules are used * change the nonce module to be an object as ECMASscript module exports are immutable * remove some unused exports * import `./core/parseHTML.js` directly in `jquery.js` so that it's not being cut out when the `ajax` module is excluded in a custom compilation Closes gh-4541
*	Build: Put all AMD modules in "src/" in strict mode	Michał Gołębiowski	2016-04-25	1	-0/+2
\| \| \| \|	Fixes gh-3073
*	Build: Update jscs and lint files	Oleg Gaidarenko	2015-09-07	1	-2/+2
\| \| \| \|	Fixes gh-2056
*	Build: update grunt-jscs-checker and pass with the new rules	Timmy Willison	2014-07-17	1	-0/+5