<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you 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.
-->

<document id="text">
    <properties>
        <title>Text</title>
    </properties>

    <body>
        <p>
            Text input components in Pivot include <tt>TextInput</tt> and <tt>TextArea</tt>.
            <tt>TextInput</tt> allows a user to enter a single line of unformatted text; the text
            may be presented in the clear or may be masked for use as a "password" field.
            <tt>TextArea</tt> multi-line text component and is discussed in the next section.
        </p>

        <p>
            The following example application demonstrates use of the <tt>TextInput</tt> component:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="240" height="40">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/text/text_inputs.bxml</src>
            </startup-properties>
        </application>

        <p>
            The example helps simplify the task of entering the name of a U.S. state. As soon as
            enough characters are entered to uniquely identify a state's name, the application
            automatically populates the component with the full name of the state. Some states,
            such as Florida, can be identified by a single character. Others, such as Washington,
            Wisconsin, and Wyoming, require two; Alaska and Alabama require 4.
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/text/text_inputs.bxml">
            <![CDATA[
            <text:TextInputs title="Text Inputs" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:text="org.apache.pivot.tutorials.text"
                xmlns="org.apache.pivot.wtk">
                <BoxPane styles="{padding:4, verticalAlignment:'center'}">
                    <Label text="State:"/>
                    <TextInput bxml:id="stateTextInput"/>
                </BoxPane>
            </text:TextInputs>
            ]]>
        </source>

        <p>
            The BXML source for this example is quite short, consisting of only a <tt>BoxPane</tt>,
            <tt>Label</tt>, and <tt>TextInput</tt>. Most of the demo's functionality is defined in
            the Java source, shown below. The application's constructor first establishes a sorted
            list of state names. In <tt>initialize()</tt>, the application attaches a
            <tt>TextInputCharacterListener</tt> to the text input. In the listener's
            <tt>charactersInserted()</tt> method, the handler attempts to identify the state whose
            name matches the entered text. If found, it is set as the text property of the text
            input.
        </p>

        <source type="java" location="org/apache/pivot/tutorials/text/TextInputs.java">
            <![CDATA[
            package org.apache.pivot.tutorials.text;

            import java.net.URL;

            import org.apache.pivot.beans.Bindable;
            import org.apache.pivot.collections.ArrayList;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.util.Resources;
            import org.apache.pivot.wtk.Display;
            import org.apache.pivot.wtk.TextInput;
            import org.apache.pivot.wtk.TextInputContentListener;
            import org.apache.pivot.wtk.Window;

            public class TextInputs extends Window implements Bindable {
                private TextInput stateTextInput = null;

                private ArrayList<String> states;

                public TextInputs() {
                    // Populate the lookup values, ensuring that they are sorted
                    states = new ArrayList<String>();
                    states.setComparator(String.CASE_INSENSITIVE_ORDER);

                    states.add("Alabama");
                    states.add("Alaska");
                    states.add("Arizona");
                    states.add("Arkansas");
                    states.add("California");
                    states.add("Colorado");
                    states.add("Connecticut");
                    states.add("Delaware");
                    states.add("District of Columbia");
                    states.add("Florida");
                    states.add("Georgia");
                    states.add("Hawaii");
                    states.add("Idaho");
                    states.add("Illinois");
                    states.add("Indiana");
                    states.add("Iowa");
                    states.add("Kansas");
                    states.add("Kentucky");
                    states.add("Louisiana");
                    states.add("Maine");
                    states.add("Maryland");
                    states.add("Massachusetts");
                    states.add("Michigan");
                    states.add("Minnesota");
                    states.add("Mississippi");
                    states.add("Missouri");
                    states.add("Montana");
                    states.add("Nebraska");
                    states.add("Nevada");
                    states.add("New Hampshire");
                    states.add("New Jersey");
                    states.add("New Mexico");
                    states.add("New York");
                    states.add("North Carolina");
                    states.add("North Dakota");
                    states.add("Ohio");
                    states.add("Oklahoma");
                    states.add("Oregon");
                    states.add("Pennsylvania");
                    states.add("Rhode Island");
                    states.add("South Carolina");
                    states.add("South Dakota");
                    states.add("Tennessee");
                    states.add("Texas");
                    states.add("Utah");
                    states.add("Vermont");
                    states.add("Virginia");
                    states.add("Washington");
                    states.add("West Virginia");
                    states.add("Wisconsin");
                    states.add("Wyoming");
                }

                @Override
                public void initialize(Map<String, Object> namespace, URL location, Resources resources) {
                    stateTextInput = (TextInput)namespace.get("stateTextInput");
                    stateTextInput.getTextInputContentListeners().add(new TextInputContentListener.Adapter() {
                        @Override
                        public void textInserted(final TextInput textInput, int index, int count) {
                            String text = textInput.getText();

                            int i = ArrayList.binarySearch(states, text,
                                states.getComparator());

                            if (i < 0) {
                                i = -(i + 1);
                                int n = states.getLength();

                                if (i < n) {
                                    text = text.toLowerCase();
                                    final String state = states.get(i);

                                    if (state.toLowerCase().startsWith(text)) {
                                        String nextState = (i == n - 1) ?
                                            null : states.get(i + 1);

                                        if (nextState == null
                                            || !nextState.toLowerCase().startsWith(text)) {
                                            textInput.setText(state);

                                            int selectionStart = text.length();
                                            int selectionLength = state.length() - selectionStart;
                                            textInput.setSelection(selectionStart, selectionLength);
                                        }
                                    }
                                }
                            }
                        }
                    });
                }

                @Override
                public void open(Display display, Window owner) {
                    super.open(display, owner);
                    stateTextInput.requestFocus();
                }
            }
            ]]>
        </source>
    </body>
</document>
