We’ve taken a look over the last few posts at some of the new features we’ve added to EditLine controls, but before we leave them we’ll mention a few miscellaneous new properties that you might find useful:

• AUTOSELECT
• CUEBANNER
• EXITCHARS
• VALIDCHARS

AUTOSELECT Property

This is a simple boolean property.  When set to TRUE all text in the control will be selected when the EditLine is given focus.

CUEBANNER Property

This is a string property that contains the text to display when an EditLine has no data.  The text is normally displayed in a faded style to differentiate it from “real” text.  It is intended primarily to give the user a simple hint on the purpose of the EditLine, or on the format of the data it should contain.

EXITCHARS property

This property allows you to specify one or more characters as “Exit” characters, which means that if a user types any of them into the control the focus is automatically moved to the next control in tab-order as though they had hit the Tab key. This property is a simple string containing the Exit characters.

// Move to the next control if the user enters a "." or a space
exitChars = ". "
call set_Property( @window : ".EDL_IP1", "EXITCHARS", exitChars )

Note this property does not work if the PASSWORDSTYLE property is TRUE.

VALIDCHARS Property

This property allows you to specify one or more characters that are “Valid” characters, which means that the user can only enter these characters into the control. This property is a simple string containing the characters that are allowed.

// Only allow numeric characters in EDL_NUMBER
validChars = "0123456789"
call set_Property( @window : ".EDL_NUMBER", "VALIDCHARS", validChars )

Note this property does not work if the EDITMASK property is set or the PASSWORDSTYLE property is TRUE.

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

The ability to apply VALID and CONV properties to an EditLine control is a very powerful way to validate and format data entered in your applications, but this commonly relies on the user knowing how the data should be input without any visual clues being provided by the UI. Some formats like dates are fairly obvious, but others are not, and this can lead to user frustration when they are presented with a message box containing some cryptic and obscure error text from the depths of a custom Iconv() routine like this:

Cryptic IConv Message

In order to improve this situation the EditLine control now supports a new property called EDITMASK, which allows you to specify the input format of the data in a visual manner, along with the type of character that may be entered at each character position, thus reducing the probability of typing errors and thereby leading to a smoother user experience.  For example here are two EditLine controls with an EDITMASK set for a phone number and a date respectively:

EDITMASK Phone and Date example

EDITMASK Property

This property is a dynamic array composed of three fields:

<1> The Input Mask
<2> The Format Mask
<3> The Default Character

The Input Mask is what the user sees in the control when no data has been entered.  The characters that they may edit are denoted by the “_” character, which is used as a placeholder. So, for a date the input mask could be “__/__/____”, meaning that they are allowed to edit the first two characters, the fourth and fifth character, and the last four characters. They will not be able to change either of the “\” characters.

The Format Mask controls the type of character that may be entered at each position where there is a placeholder “_” in the Input Mask. There should be one type specifier for each “_” character in the Input Mask, and a space character for the non-editable characters. The type specifiers are:

• “D” – A digit
• “d” – A digit or a space
• “C” – An alpha character
• “c” – An alpha character or space
• “A” – an alphanumeric character
• “a” – an alphanumeric character or space
• “X” – a hexadecimal character
• “x” – a hexadecimal character or space
• “*” – any printable character
• “+” – a “+” character, a “-” character, or space

So, for our date example we could have “dd dd dddd”. Note that the Format Mask must always be the same length as the Input Mask, otherwise the EDITMASK property will not work.

The Default Character is the character used for each invalid character in the user input. This defaults to an underscore (“_”).

To create the phone and date examples shown above you would set the following EDITMASK properties like so:

phoneMask =       " ddd ddd dddd"    |
          : @fm : "(___) ___-____"   |
          : @fm : "_"

dateMask  =       "Dd Dd dddd"        |
          : @fm : "__/__/____"        |
          : @fm : "_"

objxArray =        @window : ".EDL_PHONE"
propArray =        "EDITMASK"
dataArray =        phoneMask

objxArray := @rm : @window : ".EDL_DATE"
propArray := @rm : "EDITMASK"
dataArray := @rm : dateMask

call set_Property( objxArray, propArray, dataArray )

There are also some other supporting properties that can be used with the EDITMASK property:

• GETMASKEDCHARSONLY
• SETMASKEDCHARSONLY
• MASKEDTEXT

GETMASKEDCHARSONLY property

This is a boolean property that affects how the TEXT property works when an EDITMASK property is applied.  When set to TRUE getting the TEXT property only returns the characters that can be entered by the user, ignoring any of the non-placeholder characters in the Format Mask.  By default this property is FALSE.

SETMASKEDCHARSONLY property

This is a boolean property that affects how the TEXT property works when an EDITMASK property is applied.  When set to TRUE setting the TEXT property only updates the characters that can be entered by the user, ignoring any of the non-placeholder characters in the Format Mask.  By default this property is FALSE.

MASKEDTEXT property

This property is essentially a wrapper around the normal TEXT property, behaves as if both GETMASKEDCHARSONLY and SETMASKEDCHARSONLY were set to TRUE, so in effect it is a “shorthand” way of accessing and updating the text that can be edited.

In the example below the EditLines on the right contain the MASKEDTEXT property of the EditLines on the left:

MASKEDTEXT example

(EDIT: 21 Aug 15 – Corrected EDITMASK member positions)

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

One of the new capabilities we’ve added to Editline controls in OpenInsight 10 is Autocompletion.  This is a common feature found in many modern programs where the system attempts to predict a word or sentence that the user is entering without actually typing it in completely.

To enable this the Editline control now supports the following new properties:

• AUTOCOMPLETEMODE
• AUTOCOMPLETESOURCE
• AUTOCOMPLETELIST

AUTOCOMPLETEMODE property

This property specifies if Autocomplete is active, and if so how the suggested string is displayed. It can be one of the following values:

• “0” – Autocomplete is disabled
• “1” – Autocomplete is enabled and in “append” mode: the remainder of the suggested string is added to the end of the characters the user has typed in and highlighted.
• “2” – Autocomplete is enabled and in “suggest” mode:  the system displays a drop-down list of possible matches to what the user is typing.
• “3” – Autocomplete is enabled and in “suggest-append” mode. This is combination of the previous two modes.

AUTOCOMPLETESOURCE property

This property specifies where the list of possible suggested strings is obtained from.  It can be one of the following values:

• “0” – Custom List: a list set via the AUTOCOMPLETELIST property
• “1” – File List: a list of matching file and directory names supplied by Windows
• “2” – Directory List: a list of matching directory names supplied by Windows
• “3” – History List: a list of matches against the user’s URL history list
• “4” – MRU List: a list of matches against the user’s MRU list
• “5” – Shell List: a list of matches against all objects in the Windows Shell Namespace

AUTOCOMPLETELIST property

This property specifies an @fm-delimited list of suggested strings to use when the AUTOCOMPLETESOURCE property is “0”

Examples:

AUTOCOMPLETESOURCE 0, AUTOCOMPLETEMODE 2

AUTOCOMPLETESOURCE 1, AUTOCOMPLETEMODE 3

AUTOCOMPLETESOURCE 3, AUTOCOMPLETEMODE 1

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).