Hello,
I would like to start some discussion about formatted text field API. The related JIRA issues are RT-14000 (formatted text field) and RT-30881 (content filter).

The RT-30881 defines a content filter for all text input controls (in TextInputControl class), like TextField and TextArea. This was originally implemented by Richard Bair and briefly discussed here: http://mail.openjdk.java.net/pipermail/openjfx-dev/2012-December/004687.html. I've tried to build formatted text field on top of that (and made some changes to the API) since content filtering is something most formatted text fields will use.

First, the TextInputControl additions:

* contentFilter property of type ObjectProperty<ContentFilter>

So let's look at the content filter and content change (both nested classes of TextInputControl):

  /**
* Content Filter specifies the filter to be used with {@link TextInputControl#contentFilterProperty()}. * It allow user to intercept and modify any change done to the text content. * To avoid content that's not valid for the filter, it's possible to assign a default value supplier for the filter.
     * <p>
* The filter itself is an {@code UnaryOperator} that accepts {@link javafx.scene.control.TextInputControl.ContentChange} object. * It should return a {@link javafx.scene.control.TextInputControl.ContentChange} object that contains the actual (filtered)
     * change. Returning null rejects the change.
     * <p>
* If default value supplier is provided, it is used when the {@code ContentFilter} is assigned to a {@code TextInputControl} * and it's current text is invalid. It is expected that the provided default value is accepted by the filtering operator.
     */
    public static class ContentFilter {

        /**
         * Creates a new filter with the providing filtering operator.
         * @param filter the filtering operator
         *
         * @throws java.lang.NullPointerException if filter is null
         */
        public ContentFilter(UnaryOperator<ContentChange> filter) {}

        /**
* Creates a new filter with the providing filtering operator and default value supplier.
         * @param filter the filtering operator
         * @param defaultValue the default value or null
         *
         * @throws java.lang.NullPointerException if filter is null
         */
public ContentFilter(UnaryOperator<ContentChange> filter, Supplier<String> defaultValue) {}

        /**
         * The filtering operator of this filter.
         * @return the operator
         */
        public UnaryOperator<ContentChange> getFilter() {}

        /**
         * The default value provider of this filter
         * @return the default value provider or null
         */
        public Supplier<String> getDefaultValue() {}

        /**
* Chains this filter with a filtering operator. The other filtering operator is used only if this * filter's operator rejects the operation. The default value of the new {@code ContentFilter} is the same
         * as of this filter.
         * @param other the filtering operator to chain
         * @return a new ContentFilter as described above
         */
        public ContentFilter orApply(UnaryOperator<ContentChange> other) {}

        /**
* Chains this filter with a filtering operator of another {@code ContentFilter}. The other filtering operator is used only if this * filter's operator rejects the operation. The default value of the new {@code ContentFilter} is the same
         * as of this filter.
         * @param other the filter to chain
         * @return a new ContentFilter as described above
         */
        public ContentFilter orApply(ContentFilter other) {}

    }

/**
     * Contains the state representing a change in the content for a
     * TextInputControl. This object is passed to any registered
     * {@code contentFilter} on the TextInputControl whenever the text
     * for the TextInputControl is modified.
     * <p>
* This class contains state and convenience methods for determining what
     *     change occurred on the control. It also has a reference to the
* TextInputControl itself so that the developer may query any other * state on the control. Note that you should never modify the state
     *     of the control directly from within the contentFilter handler.
     * </p>
     * <p>
* The ContentChange is mutable, but not observable. It should be used
     *     only for the life of a single change. It is intended that the
     *     ContentChange will be modified from within the contentFilter.
     * </p>
     */
    public static final class ContentChange implements Cloneable{

        /**
         * Gets the control associated with this change.
* @return The control associated with this change. This will never be null.
         */
        public final TextInputControl getControl() {}

        /**
* Gets the start index into the {@link javafx.scene.control.TextInputControl#getText()}
         * for the modification. This will always be a value &gt; 0 and
         * &lt;= {@link javafx.scene.control.TextInputControl#getLength()}.
         *
         * @return The start index
         */
        public final int getStart() {}

        /**
* Sets the start index for the range to be modified. This value must * always be a value &gt; 0 and &lt;= {@link javafx.scene.control.TextInputControl#getLength()}
         * <p>
* <b>Note</b> that setting start before the current end will also change end to the same value.
         *
         * @param value the new start index
         */
        public final void setStart(int value) {}

        /**
* Gets the end index into the {@link javafx.scene.control.TextInputControl#getText()} * for the modification. This will always be a value &gt; {@link #getStart()} and
         * &lt;= {@link javafx.scene.control.TextInputControl#getLength()}.
         *
         * @return The end index
         */
        public final int getEnd() {}

        /**
         * Sets the end index for the range to be modified. This value must
* always be a value &gt; {@link #getStart()} and &lt;= {@link javafx.scene.control.TextInputControl#getLength()}. * Note that there is an order dependency between modifying the start * and end values. They must always be modified in order such that they
         * do not violate their constraints.
         *
         * @param value The new end index
         */
        public final void setEnd(int value) {}

        /**
         * A convenience method returning an IndexRange representing the
         * start and end values.
         *
* @return a non-null IndexRange representing the range from start to end.
         */
        public final IndexRange getRange() {}

        /**
         * A convenience method assigning both the start and end values
* together, in such a way as to ensure they are valid with respect to * each other. One way to use this method is to set the range like this:
         * {@code
         *     change.setRange(IndexRange.normalize(newStart, newEnd));
         * }
         *
         * @param value The new range. Cannot be null.
         */
        public final void setRange(IndexRange value) {}

        /**
         * A convenience method assigning both the start and end values
* together, in such a way as to ensure they are valid with respect to
         * each other. The start must be less than or equal to the end.
         *
         * @param start The new start value. Must be a valid start value
         * @param end The new end value. Must be a valid end value
         */
        public final void setRange(int start, int end) {}

        /**
         * Gets the new anchor. This value will always be &gt; 0 and
         * &lt;= {@link #getProposedControlText()}{@code}.getLength()}
         *
         * @return The new anchor position
         */
        public final int getNewAnchor() {}

        /**
         * Sets the new anchor. This value must be &gt; 0 and
* &lt;= {@link #getProposedControlText()}{@code}.getLength()}. Note that there
         * is an order dependence here, in that the anchor should be
         * specified after the new text has been specified.
         *
         * @param value The new anchor position
         */
        public final void setNewAnchor(int value) {}

        /**
* Gets the new caret position. This value will always be &gt; 0 and
         * &lt;= {@link #getProposedControlText()}{@code}.getLength()}
         *
         * @return The new caret position
         */
        public final int getNewCaretPosition() {}

        /**
         * Sets the new caret position. This value must be &gt; 0 and
* &lt;= {@link #getProposedControlText()}{@code}.getLength()}. Note that there * is an order dependence here, in that the caret position should be
         * specified after the new text has been specified.
         *
         * @param value The new caret position
         */
        public final void setNewCaretPosition(int value) {}

        /**
         * Gets the text used in this change. For example, this may be new
* text being added, or text which is replacing all the control's text * within the range of start and end. Typically it is an empty string
         * only for cases where the range is being deleted.
         *
* @return The text involved in this change. This will never be null.
         */
        public final String getText() {}

        /**
         * Sets the text to use in this change. This is used to replace the
* range from start to end, if such a range exists, or to insert text
         * at the position represented by start == end.
         *
         * @param value The text. This cannot be null.
         */
        public final void setText(String value) {}

        /**
* Gets the complete new text which will be used on the control after * this change. Note that some controls (such as TextField) may do further * filtering after the change is made (such as stripping out newlines) * such that you cannot assume that the newText will be exactly the same * as what is finally set as the content on the control, however it is * correct to assume that this is the case for the purpose of computing * the new caret position and new anchor position (as those values supplied
         * will be modified as necessary after the control has stripped any
         * additional characters that the control might strip).
         *
* @return The controls proposed new text at the time of this call, according * to the state set for start, end, and text properties on this ContentChange object.
         */
        public final String getProposedControlText() {}

        /**
* Gets whether this change was in response to text being added. Note that * after the ContentChange object is modified by the contentFilter (by one * of the setters) the return value of this method is not altered. It answers * as to whether this change was fired as a result of text being added,
         * not whether text will end up being added in the end.
         *
         * <p>
* Text may have been added either cause it was {@link #isInserted()},
         * {@link #isAppended()}, or {@link #isPrepended()}.
         * </p>
         *
         * @return true if text was being added
         */
        public final boolean isAdded() {}

        /**
* Gets whether this change was in response to text being deleted. Note that * after the ContentChange object is modified by the contentFilter (by one * of the setters) the return value of this method is not altered. It answers * as to whether this change was fired as a result of text being deleted,
         * not whether text will end up being deleted in the end.
         *
         * @return true if text was being deleted
         */
        public final boolean isDeleted() {}

        /**
* Gets whether this change was in response to text being added, and in * particular, inserted into the midst of the control text. If this is
         * true, then {@link #isAdded()} will return true.
         *
         * @return true if text was being inserted
         */
        public final boolean isInserted() {}

        /**
* Gets whether this change was in response to text being added, and in
         * particular, appended to the end of the control text. If this is
         * true, then {@link #isAdded()} will return true.
         *
         * @return true if text was being appended
         */
        public final boolean isAppended() {}

        /**
* Gets whether this change was in response to text being added, and in * particular, prepended at the start of the control text. If this is
         * true, then {@link #isAdded()} will return true.
         *
         * @return true if text was being prepended
         */
        public final boolean isPrepended() {}

        /**
* Gets whether this change was in response to text being replaced. Note that * after the ContentChange object is modified by the contentFilter (by one * of the setters) the return value of this method is not altered. It answers * as to whether this change was fired as a result of text being replaced,
         * not whether text will end up being replaced in the end.
         *
         * @return true if text was being replaced
         */
        public final boolean isReplaced() {}

        @Override
        public ContentChange clone() {}
}



The new FormattedTextField class relies on the content filtering and adds a concept of values convertible to/from a text:

**
* FormattedTextField is a special kind of TextField that handles conversion between a value of type {@code T} and
 * a text of this TextField.
 * <p>
 * There are two types of converters:
 * <ul>
* <li>{@link #valueConverterProperty()} represents the default converter between the text and values</li> * <li>{@link #editConverterProperty()} is a special converter that takes precedence when the textfield is being edited. * This allows to have a edit-friendly format and a nice display format for the value</li>
 * </ul>
 *
 * <p>
* When editing the text field, the value is not updated until either {@code ENTER} key is pressed or focus is lost.
 * If the conversion fail, the last known valid value is used instead.
 *
 * @param <T> the value type
 */
public final class FormattedTextField<T> extends TextField{

    /**
* Creates a formatted text field with the specified converter and a null value.
     * @param valueConverter the value converter
     */
    public FormattedTextField(StringConverter<T> valueConverter) {}

    /**
* Creates a formatted text field with the specified converter and a value
     * @param valueConverter the value converter
     * @param value the initial value
     */
public FormattedTextField(StringConverter<T> valueConverter, T value) {}

    /**
* This represents the current value of the formatted text field. If a {@link #valueConverterProperty()} is provided, * and the text field is not being edited, the value is a representation of the text in the text field.
     */
    public final ReadOnlyObjectProperty<T> valueProperty() {}
    public final void setValue(T value) {}
    public final T getValue() {}

    /**
     * The default converter between the values and text.
* Note that changing the converter might lead to a change of value, but only if the text can be converted by the new * converter. Otherwise, the current value is converted to a text, which is set to the field.
     * @see #editConverterProperty()
     */
public final ObjectProperty<StringConverter<T>> valueConverterProperty() {}
    public final void setValueConverter(StringConverter<T> converter) {}
    public final StringConverter<T> getValueConverter() {}

    /**
     * Converter between values and text when the field is being edited.
     * @see #valueConverterProperty()
     */
public final ObjectProperty<StringConverter<T>> editConverterProperty() {}
    public final void setEditConverter(StringConverter<T> converter) {}
    public final StringConverter<T> getEditConverter() {}

}

You can find the whole patch here: https://javafx-jira.kenai.com/secure/attachment/44678/rt-30881_14000_proposal.patch There are some examples for content filtering in RT-30881. I'll attach some formatted text field samples soon.

Thanks,
-Martin

Reply via email to