Edit Boxes

Edit boxes allow the user to input text into a UJML application.

Edit boxes are visual elements which allow for user text entry. See Visual Elements, Variables. There are two kinds of edit box elements. The edit tag specifies a single-line edit box and the multi-edit tag specifies a multi-line edit box. See edit, multi-edit.

Variable binding

UJML automatically binds a string variable to the edit box. See Variables. This means you do not have to do anything to set the value into the edit box before editing starts or to get the value out when editing is completed. Instead, you specify the variable with a var attribute containing the variable name.

Note: The name of the variable to edit may not be changed at run time.

When the edit box is displayed, UJML gets the current value of the bound variable and puts it into the edit box. When the edit box is hidden, UJML updates the bound variable with the new value. You display an edit box by putting it inside of a state transition and setting the associated state variable to the appropriate state. See State Variables, State Transitions. You then hide the edit box by either setting the state variable to a different value or clearing the state variable by calling the _clear_state() function.

Note: Edit boxes must always be inside of a state transition.

Device-dependence issues

Many devices support in-place editing, where the edit box displays in the same view as the other visual elements. In this case the x, y, and width child elements determine the size and position of the edit box and the x-caption child element is ignored. Other devices do modal editing in a separate view; usually filling the entire screen of the device.

Note: Because different devices handle user input differently, only one edit box is allowed on screen at a time.

When a device does modal editing, the position elements are ignored and the x-caption child element specifies a string caption which appears near the full-screen edit box. You can determine if a device uses modal editing by calling the _isSupported() function with the &_X_MODAL_EDIT; entity as a parameter. See Determining Device Context.

Depending on device support, the edit box may respond to the stylus and/or another pointing device. Which keys are used for text input, and how those keys work, is also device dependent. In most cases, the edit box will capture all key input except F1, F2, and FIRE. See Function Keys, fn. For this reason you should use one of those keys to allow the user to signal when editing is complete. The settings.ujml sample has a complete example of using the edit box along with an associated caption and function key support.

The following images show an edit box displayed by the settings.ujml sample.

Device supports in-place editing	Device supports modal editing

The following images show a multi-edit box displayed by the settings.ujml sample.

Device supports in-place editing	Device supports modal editing

Function key issues

As stated above, in most cases the edit box will capture all key input except F1, F2, and FIRE. This means you should catch one of those keys to end the edit session, but it also means that other event handlers need to do the right thing if an edit session is in progress when they are triggered. For example, let us suppose you are using FIRE to signal the end of an edit session and F2 to advance to the next page of your application. In this case, you will want to make certain that F2 is disabled or hides the edit box itself, as appropriate.

Experiment on different devices

Because device support for text editing varies so much from device to device, edit boxes can be difficult to implement in a way that looks nice and meshes well with the rest of your application. The edit.ujml sample allows you to try edit boxes on a variety of different devices and see the results.

Example

The following example shows how to use state transitions to display both an edit box and a multi-edit box. Functions keys are used to capture when editing is complete and move the application to the next transition. Other transitions show the results of each edit with a short delay. It is part of the edit.ujml sample.

Copy Code

<ujml>
    <application>
        <state-variables>
            <state-var name="sInput" type="int"/>
        </state-variables>
        <variables>
            <var name="mText" type="string"/>
        </variables>
        <script>
            // Set the initial text value.
            mText = "&SALUTATION;";

            // Go.
            sInput = 0;
        </script>

        ...

        <states>
            <state var="sInput">
                <!-- Show the edit box. -->
                <transition value="0">
                    <display>
                        <edit var="mText">
                            <width><eval>_getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;)</eval></width>
                            <x-caption>Enter text and press F2.</x-caption>
                        </edit>
                        <fn>
                            <text>Done</text>
                            <event name="onSelect">
                                <accelerators><key>F2</key></accelerators>
                                <script>
                                    // Advance to next state.
                                    sInput = 1;
                                </script>
                            </event>
                        </fn>
                    </display>
                </transition>
                <!-- Hide the edit box and show the edited text for a period of time. -->
                <transition value="1">
                    <display>
                        <label>
                           <text><eval>_strcat("You entered '", mText, "'")</eval></text>
                           <fg>&_COLOR_YELLOW;</fg>
                        </label>
                    </display>
                    <delay>&DELAY_MSEC;</delay>
                    <script>
                         // Advance to next state.
                        sInput = 2;
                    </script>
                </transition>
                <!-- Show the multi-edit box. -->
                <transition value="2">
                    <display>
                        <multi-edit var="mText">
                            <width><eval>_getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;)</eval></width>
                            <height><eval>_getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;)</eval></height>
                            <x-caption>Enter text and press F2.</x-caption>
                        </multi-edit>
                        <fn>
                            <text>Done</text>
                            <event name="onSelect">
                                <accelerators><key>F2</key></accelerators>
                                <script>
                                    // Advance to next state.
                                    sInput = 3;
                                </script>
                            </event>
                        </fn>
                    </display>
                </transition>
                <!-- Hide the edit box and show the edited text for a period of time. -->
                <transition value="3">
                    <display>
                        <multi-label>
                            <text><eval>_strcat("You entered '", mText, "'")</eval></text>
                            <width><eval>_getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;)</eval></width>
                            <height><eval>_getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;)</eval></height>
                            <fg>&_COLOR_LIME;</fg>
                        </multi-label>
                    </display>
                    <delay>&DELAY_MSEC;</delay>
                    <script>
                         // Advance to next state.
                        sInput = 0;
                    </script>
                </transition>
            </state>
        </states>
    </application>
</ujml>

The following example shows how to display an edit box in a well-formatted user interface consisting of a box with a label to show a caption for devices that support in-place editing and a function key event that hides the multi-edit box when the user is done. It is part of the settings.ujml sample.

Copy Code

<display>
    <box>
        <x><eval>mRectX</eval></x>
        <y><eval>mRectY</eval></y>
        <width><eval>mRectWidth</eval></width>
        <height><eval>(mRectHeight / 3) - &MIN_SPACING;</eval></height>
        <fg>&_COLOR_BLUE;</fg>
        <bg>&_COLOR_SILVER;</bg>
        <x-clip>true</x-clip>
        <multi-label>
            <text><eval>mLabelEditCaptionText</eval></text>
            <x>&MIN_SPACING;</x>
            <y>&MIN_SPACING;</y>
            <width><eval>mRectWidth - (&MIN_SPACING; * 2)</eval></width>
            <height><eval>(mRectHeight / 3) - (&MIN_SPACING; * 3)</eval></height>
            <fg>&_COLOR_BLACK;</fg>
            <size>&_FONT_SIZE_SMALL;</size>
            <style>&_FONT_STYLE_PLAIN;</style>
            <face>&_FONT_FACE_SYSTEM;</face>
        </multi-label>
    </box>
    <edit var="mSingleLineText">
        <x><eval>mRectX</eval></x>
        <y><eval>mRectY + (mRectHeight / 3)</eval></y>
        <width><eval>mRectWidth</eval></width>
        <x-caption><eval>mLabelEditCaptionText</eval></x-caption>
    </edit>
    <fn>
        <text>Done</text>
        <event name="onSelect">
            <accelerators>
                <key>FIRE</key>
            </accelerators>
            <script>sEditCaptionText = false;</script>
        </event>
    </fn>
</display>

The following example shows how to display a multi-edit box in a well-formatted user interface consisting of a box with a label to show a caption for devices that support in-place editing and a function key event that hides the multi-edit box when the user is done. It is part of the settings.ujml sample.

Copy Code

<display>
    <box>
        <x><eval>mRectX</eval></x>
        <y><eval>mRectY</eval></y>
        <width><eval>mRectWidth</eval></width>
        <height><eval>(mRectHeight / 3) - &MIN_SPACING;</eval></height>
        <fg>&_COLOR_BLUE;</fg>
        <bg>&_COLOR_SILVER;</bg>
        <x-clip>true</x-clip>
        <multi-label>
            <text><eval>mMultiLabelEditCaptionText</eval></text>
            <x>&MIN_SPACING;</x>
            <y>&MIN_SPACING;</y>
            <width><eval>mRectWidth - (&MIN_SPACING; * 2)</eval></width>
            <height><eval>(mRectHeight / 3) - (&MIN_SPACING; * 3)</eval></height>
            <fg>&_COLOR_BLACK;</fg>
            <size>&_FONT_SIZE_SMALL;</size>
            <style>&_FONT_STYLE_PLAIN;</style>
            <face>&_FONT_FACE_SYSTEM;</face>
        </multi-label>
    </box>
    <multi-edit var="mMultiLineText">
        <x><eval>mRectX</eval></x>
        <y><eval>mRectY + (mRectHeight / 3)</eval></y>
        <width><eval>mRectWidth</eval></width>
        <height><eval>mRectHeight - (mRectHeight / 3)</eval></height>
        <x-caption><eval>mMultiLabelEditCaptionText</eval></x-caption>
    </multi-edit>
    <fn>
        <text>Done</text>
        <event name="onSelect">
            <accelerators>
                <key>FIRE</key>
            </accelerators>
            <script>sEditMultilineCaptionText = false;</script>
        </event>
    </fn>
</display>