How do I use Native Text Controls on iOS

The UITextField class within iOS provides a one line editable text field. This text field can be used to collect small amounts of data from users. In addition to basic text editing, the UITextField supports a range of text formatting and keyboard types.
This lesson shows you how to interact with the the UITextField class from within your LiveCode application and demonstrates some of the features that are available. You should review the Release Notes that accompany your release of LiveCode with iOS support in order to get updates on the features covered here.

The interface shown in this step provides a number of option menus that allow you to set properties that control how you interact with the native text field. You can control font size, border style, auto correction type, keyboard type, content type, text color, text align, auto capitalization, keyboard style, return key type and receive the editing, text changed and return key messages. This list is only a subset of the native text field control features that are available in LiveCode. Refer to the relevant LiveCode with iOS support product documentation for more information on what additional features are supported.

The option menus do not contain any LiveCode script and are processed purely on the content of their names and labels. A generic message handler probes the content of these values for each option menu and applies the value using the command iphoneControlSet.

The stack in this lesson has three buttons: The Reset Text Changed button, the Create button and the Delete button. Each of these buttons executes a small script. These scripts are listed in this step.

The Reset Text Changed button changes label "Text Changed: true" to "Text Changed: false"

on mouseUp
put "Text Changed: false" into field "textChanged"
end mouseUp

The Create button creates an instance of a text field.

on mouseUp
    inputCreate
end mouseUp

The Delete button deletes an instance of a text field.

on mouseUp
    inputDelete
end mouseUp

The card stack contains a number of message handlers that are responsible for a number of control aspects within the application. The comments in the following message event handler scripts provide details of what each script does.

on closeCard
    # handle the close card event
    inputDelete
end closeCard

on inputCreate
    # handle the input creation event
    if "testinput" is among the lines of iphoneControls() then
        # ensure that only one native text input is open
        inputDelete
    end if
    iphoneControlCreate "input", "testinput"
    # set the native text input field to the size and position of the graphic input rectangle
    iphoneControlSet "testinput", "rect", the rect of graphic "InputRect"
    iphoneControlSet "testinput", "visible", true
    # make sure the selected option menu options are applied to the native text input
    updateFieldProps
end inputCreate

on inputDelete
    # delete the native text input
    iphoneControlDelete "testinput"
end inputDelete

on inputFocus
    # set the focus to the native text input
    iphoneControlDo "testinput", "focus"
end inputFocus

on mouseUp
    # handle any mouseUp here that is not handled explicitly by a control
    if word 1 of the name of the target is "button" then
        updateFieldProps
    end if
end mouseUp

on inputBeginEditing
    # handle the inputBeingEdited message
    # this updates a label field on the interface
    put "Editing: true" into field "editing"
end inputBeginEditing

on inputEndEditing
    # handle the inputEndEdited message
    # this updates a label field on the interface
    put "Editing: false" into field "editing"
end inputEndEditing

on inputTextChanged
    # handle the inputTextChanged message
    # this updates a label field on the interface
    put "Text Changed: true" into field "textChanged"
end inputTextChanged

on inputReturnKey
    # handle the inputReturnKey message
    # this raises a dialog box, indicating that the return key was pressed
    # and focus was removed from the text field
    answer "The return key was pressed" with "Okay"
end inputReturnKey

As discussed earlier in this lesson, the option menu items do not have LiveCode associated with them. Rather, they are processed using a generic message handler that uses the name and the label of the option menus to set up the respective control that has been changed. updateFieldProps is stored on the stack script and implements this generic process.

on updateFieldProps
    local tX
    # ensure that we are handling messages from our native text input
    if "testinput" is not among the lines of iphoneControls() then
        exit updateFieldProps
    end if
    # loop through each control on the card
    repeat with tX = 1 to the number of controls
        # if the control name does not start with "property" then go to the next item
        if word 1 of the short name of control tX is not "property" then
            next repeat
        end if
        # set the native control property using the value of the current card control
        iphoneControlSet "testinput", word 2 of the short name of control tX, the label of control tX
    end repeat
end updateFieldProps

Note: Using a generic process to apply any option menu selection allows you as a developer to add or remove option menus, knowing that any further LiveCode changes are minimal or not needed at all.

Once you raise your application on the iOS device of choice, you should be presented with the following or similar display. You have to select the button Create before you can start entering text. Once text has been entered (see next example), you should see how the label content of Text Changed and Editing changes. You can reset the Text Changed label by selecting the Reset Text Changed button. Selecting the option menus and altering their content should have an immediate impact on the content that is displayed in the text field.

You can enter text by selecting the text input area. This raises the keyboard you specified under the Keyboard Style option menu. Type in the text as required and complete editing with the return key.

You can also create native multiline text input controls on iOS. The multiline input control allows the editing of multiple lines of text, with the 'return' key ending each line.

The process is exactly as described about but you create a control of type 'multiline' in the inputCreate handler.

on inputCreate
    # handle the input creation event
    if "testinput" is among the lines of iphoneControls() then
        # ensure that only one native text input is open
        inputDelete
    end if
    iphoneControlCreate "multiline", "testinput"
    # set the native text input field to the size and position of the graphic input rectangle
    iphoneControlSet "testinput", "rect", the rect of graphic "InputRect"
    iphoneControlSet "testinput", "visible", true
    # make sure the selected option menu options are applied to the native text input
    updateFieldProps
end inputCreate