Consultor Eletrônico

Text Formatting Changes Between Apptivity 3.0.1 and 3.1

KnowledgeBase number: 19028
This document applies to: Apptivity Developer and Runtime
Version and Release Number: 3.1 and above


Overview:

Apptivity 3.0 supported simple masks for user input and evaluates each
character as it was input from the keyboard for the text field control
and for grid cells. If the input character was not valid for the given
data type associated with the input field, the character was ignored.
For example, if the data type was date, only numeric characters were
accepted. If a mask was associated with the input field, the cursor
position was automatically adjusted to skip over explicit mask
characters, e.g., the '/' separator for a date mask. Only one mask was
available for both the editing and display of the data.

Apptivity 3.1 provides greater control of user input by supporting
internationalization in format masks, more formatting mask characters,
and separate edit and display masks. In order to provide internationalization
support, the user input is evaluated upon completion instead of as each
character is input.


API Changes:

Changes to abTextField.setText() method

One method change for 3.1 requires project source code modification
and recompilation. The method public void setText(String text) from
the progress.apptivity.igui package now specifies in its method signature
that an Exception is thrown. The method sets the specified string
to a text field, and the string is parsed according to the existing
masking, if any, and an internal object is created corresponding to
its native data type. In Apptivity 3.0, if setText() failed due to an
invalid string, the content of the text field was either set to blank
or it was reset to its previous valid content without any notification
to the user. In Apptivity 3.1, throwing an Exception object allows the
developer to provide custom error handling inside a try() catch() block.

It is possible for an existing Apptivity 3.0 project that uses
abTextField.setText() to be run under Apptivity 3.1 runtime without
any modification. If an exception is thrown by setText(), the Java
client will emit an exception stack trace but will continue to run;
the IFC framework will catch all exceptions. The internal state
of the application, however, will be compromised. Since users will
make input mistakes, it is highly recommended that the source code be
modified to handle any exception thrown by setText().

If this method call was not used in a project, no source code modification
is necessary. This situation is possible if getValue() and setValue()
methods were used to obtain and manipulate the object encapsulating
the native data type and instead of its string representation. Rebuilding
a project from the Developer will report all the use of setText().

NOTE: The method public void setText(int i) does NOT throw any exception.


Compatibility for setMask() method

The method public void abTextField.setMask(String mask, int type)
maintains compatibility with Apptivity 3.0 masks for DATE and TIME
types. In Apptivity 3.0, the Date and Time mask characters were
case-insensitive. In Apptivity 3.1, the meaning of the mask characters
has changed significantly, and mask characters specify different
information depending on their case. (See Table 1 and Table 2,below).
The setMask() method, if used only with Apptivity 3.0 mask characters,
internally maps the given mask to a correct Apptivity 3.1 mask.

Since setMask() method is now marked as deprecated, it is highly
recommended that an appropriate setFormat() method be used instead.
The appropriate setFormat() method will be generated automatically if
Apptivity 3.1 Developer is used to specify the Format property of a
text field control or a column of a grid.

Apptivity 3.0 h:m and h:m:s time masks compatibility is also provided.

Table 1: Apptivity 3.0 Date and Time Mask Characters

Symbol Meaning Presentation Example
------ -----