[ Overview ] [ User's Guide ] [ Tutorial ] [ Samples ] [ Requirements ] [ Limitations ] [ API Documentation ]
The following sample applet uses the MaskedTextField Bean to display a text field with a series of custom mask characters. The source code for this example is included as an introduction to using the MaskedTextField Bean. It is not meant to cover every possible way that the Bean can be used. Refer to the API Documentation for a complete list of available methods.
Note: Currently, no commercial web browsers support JDK 1.1. Therefore, this Bean will not work in Netscape Navigator, Internet Explorer, and other web browsers. If you are using Sun's new HotJava browser or the JDK 1.1 AppletViewer, use the URL link of the image below.
To create a MaskedTextField, simply instantiate a new object and add it to a Container in your applet or application. For example, the following code is an applet that displays a MaskedTextField and a java.awt.TextField.
import java.awt.*; import COM.taligent.widget.*; public class SampleMaskedTextField extends java.applet.Applet { // // GUI Components // private MaskedTextField mask; private TextField text; // setup applet public void init() { setBackground(Color.lightGray); setLayout(new GridLayout(2, 1, 2, 2)); // create and init masked text field mask = new MaskedTextField(); // create and init text field text = new TextField(); text.setBackground(Color.lightGray); text.setEditable(false); // set display attributes Font font = new Font("Courier", Font.PLAIN, 12); mask.setFont(font); text.setFont(font); // add components to panel add(mask); add(text); setSize(300, 55); setVisible(true); } }
The lines marked in bold show the only code necessary to create a MaskedTextField. In order to effectively use the text field, however, additional code is required. The following section describes how to create custom mask characters and how to use these mask characters to set the mask of the MaskedTextField.
The MaskedTextField uses a small set of pre-defined mask characters by default. Refer to the User's Guide page for a complete list. This small set of mask characters are only useful if you are making simple masks to denote telephone or Social Security numbers. For example, "(###) ###-####" and "###-##-####", respectively.
The mask used by the MaskedTextField is a Java String. The characters of this string specify the allowed input. For example, By setting the mask to "###" the text field will only allow the user to enter 3 individual numbers with no spaces. This works because the MaskedTextField knows that the character '#' corresponds to the allowed characters '0' through '9' and no others.
When the mask is set, the MaskedTextField scans the mask string and determines which characters are mask characters and which characters are literals. A literal character is a letter, number, or symbol that is copied directly to the display and is not editable by the user (i.e. a character constant). All characters that are not mask characters are considered literals. In order to user a mask character as a literal, prepend the character in the mask string with a backslash (\). Note: because the backslash is also used as an escape character in Java strings, you must insert the backslash in the mask string as a double backslash (\\) as in "\\# ###".
There are two ways to set the mask for a MaskedTextField. The first is to pass the mask String as a parameter when the text field is instantiated:
MaskedTextField textfield = new MaskedTextField("###");
The other way to set the mask is to call the setMask() method:
MaskedTextField textfield = new MaskedTextField(); textfield.setMask("###");
To take full advantage of the MaskedTextField Bean, most programmers will define their own mask characters for use with the text field. The following section describes in detail how to create new mask characters.
Most of the time, the programmer will create his or her own custom mask characters for use with the MaskedTextField. For our example applet, the pre-defined mask characters are not sufficient so we are going to define new ones. Before we set the mask characters for the MaskedTextField, however, let's talk about how to create new mask characters.
To create a new mask character, you need to decide which character to use in the mask string and what are the valid input characters for that character. The constructor of MaskCharacter takes the following parameters:
The last parameter, the translation string, is optional. This string allows the accepted input to be translated as it is typed. The lowercase letters could automatically be converted to uppercase as they are entered.
As an example, let's redefine the numeric mask character we've been using. In this case, the maskchar will be '#' and the validchars will be "0-9". Both the validchars and the translation strings follow a specific format. These strings can contain any of the following:
The following code creates a MaskCharacter that allows only numeric input:
MaskCharacter maskchar = new MaskCharacter('#', "0-9");
It is important to remember that the translation string should contain the same number of single characters or character ranges as the the validchars string. For example, to create a mask that accepts either upper or lowercase letters and converts the input to uppercase, do the following:
MaskCharacter maskchar = new MaskCharacter('>', "A-Za-z", "A-ZA-Z");
Add the following constant and code to the SampleMaskedTextField applet:
private static final MaskCharacter MASKCHARS[] = { MaskCharacter.UPPERCASE, // only uppercase letters MaskCharacter.LOWERCASE, // only lowercase letters MaskCharacter.DIGITS, // only numbers new MaskCharacter('>', "a-zA-Z", "A-ZA-Z"), // to uppercase new MaskCharacter('<', "a-za-z", "a-za-z"), // to lowercase new maskcharacter('.', "\u0000-\uffff") // any unicode char }; // setup the applet public void init() { // set background and layout manager // create and init masked text field mask = new MaskedTextField(); mask.setMaskCharacters(MASKCHARS); mask.setMask("\\A: AA, \\a: aa, \\#: ##, \\>: >>, \\<: <<, \\.: .."); // resize and show applet }
You can compile and test the code at this point or continue to the next section where we add simple event handling to the applet.
The MaskedTextField Bean passes three types of events to registered listeners:
In order to receive events from the text field, simply register the applet or application as a listener. We are going to register our sample applet with the MaskedTextField as an ActionListener by adding the following code:
import java.awt.event.*; public class SampleMaskedTextField extends java.applet.Applet implements ActionListener { // setup applet public void init() { // initialize components // add listeners mask.addActionListener(this); // resize and show applet } // action performed public void actionPerformed(ActionEvent evt) { Object source = evt.getSource(); if (source == mask) { text.setText(mask.getText()); } } }
When the user presses Enter when entering text in the MaskedTextField, the text will be copied into the java.awt.TextField in the applet. Now compile the completed code and you will have the applet that appears at the top of this page.
The MaskedTextField Bean has all of the standard TextField editing capabilities. The user can move the cursor, select text with the mouse, and move text between the text field and the host system's clipboard.
Clipboard interaction is initiated by pressing the cut, copy, or paste keys. The following table shows the default values of these keys:
cut | Control X |
copy | Control C |
paste | Control V |
The key bindings for cut, copy, and paste operations can be set and queried using methods in the class COM.taligent.widget.TextClipboardComponent.
Copyright Taligent,
Inc. 1996 - 1997.
Copyright © IBM Corporation 1996 - 1997.
All Rights Reserved