Item Class and Its Sub Classes

The Item Class - A derivative of Form Class

The Item class is a sub class of Form Class and has derivative classes such as TextField, Image, ImageItem, DataField etc. that can be placed on the form.

A Form can hold any number of objects of type Item that include StringItem, TextField, and ChoiceGroup. Item objects can be added to a Form using the append()method.

The Item class itself is an abstract base class that cannot be instantiated. It provides a label that is a common property of all subclasses.
The label of an Item object can be set and queried using the setLabel()and getLabel()methods, respectively. The label is optional, and a null value indicates that the item does not have a label.

The user interacts with a mobile application by changing the status of instances of derived classes of Item class, except for instances of ImageItem and StringItem classes.

Sub Classes of Item Class

The table given below shows all the derived classes of Item base class.

An instance of the ImageItem class causes an image to appear on the form
An instance of the StringItem class causes text to be displayed on the form

String Item Class:

Object of StringItem class is used to display a message on the screen.
The text displayed by the StringItem object cannot be modified or deleted by the user of the MIDlet
A StringItem class does not recognize events, i.e., an instance of a StringItem class can never cause an event because the user cannot modify the text of the string item
Create an instance of a StringItem class can be done by passing the StringItem class constructor two parameters. The first parameter is a string representing the label of the instance. The other parameter is a string of text that will appear on the screen.

The following code snippet is used for creating and displaying a static text having the caption "Version" and the content "1.0". After creation, the label is added to the main form in the constructor of the HelloMidp application:

public HelloMidp () {
  mainForm = new Form ("HelloMidp");
  StringItem versionItem = new StringItem ("Version: ", "1.0");
  mainForm.append (versionItem);
}

The label of the StringItem can be manipulated using the methods - setLabel() and getLabel() inherited from Item class.
To manipulate the content of the StringItem object, we can use the methods setText() and getText() of StringItem class.

ImageItem Class:

Graphical images are displayed using an instance of the ImageItem class, which inherits from the Item class. The images displayed by an ImageItem object are called immutable images.
An immutable image is loaded from a file or other resource and cannot be modified once the image is displayed. For instance, icons associated with MIDlets are immutable images.

The steps to create and display an immutable image are as follows:

Create an instance of the Image class by calling the createImage() method. The createImage() method requires one parameter that contains the name of the file holding the image. Make sure that you include the full path to the file in the parameter.
Create an instance of the ImageItem class. The constructor of the ImageItem class requires four parameters. They are:

The first is a string that becomes the label for the image.
The second parameter is a reference to the instance of the Image class created in step one.
The third parameter is the layout directive. The layout directive is a request to the device’s application manager to position the image at a particular location on the screen.
The table given below lists the constants used for specifying the layout directives. The bitwise OR operator combines layout directives (|).

The last parameter is a string referred to as alternate text that is displayed in place of the image if for some reason the image cannot be displayed by the device.

The methods given below allow the programmer to modify the properties of the image object such as image layout, label and alternate text, after the image has been displayed on the screen:

getLayout() method returns the current layout directive of an instance of an ImageItem.
setLayout() method replaces the current layout with a new layout whose directive is passed as a parameter to the setLayout() method
getLabel() and setLabel() are used to retrieve and modify the label associated with the image
getAltText() and setAltText() are used to access and update the alternate text associated with the image

The following code snippet shows how a center aligned ImageItem is added to the HelloMidp sample MIDlet:

public HelloMidp () {
  display = Display.getDisplay (this);
  mainForm = new Form ("HelloMidp");
   try {

    Image img = Image.createImage ("/mcp.png");
    ImageItem logo = new ImageItem 
      ("Copyright: ", img, ImageItem.LAYOUT_CENTER | ImageItem.LAYOUT_NEWLINE_BEFORE 
       | ImageItem.LAYOUT_NEWLINE_AFTER, "Macmillian USA");

    mainForm.append (logo);
  }
  catch (IOException e) {
    mainForm.append (new StringItem 
      ("Copyright", "Sams Publishing; Image not available:" + e));
  }

By introducing a new line before (using the constant ImageItem.LAYOUT_NEWLINE_BEFORE) and after the image (using the constant ImageItem.LAYOUT_NEWLINE_AFTER) , we ensure that the image is centered in its own line.

The below figure shows the output produced by the MIDlet coded above. If the image cannot be loaded and an exception is thrown, a simple StringItem is appended to the form instead of the image.

Handling Textual Input in TextFields:

The TextField class is used to capture one line or multiple lines of text entered by the user.
The number of lines of a text field depends on the maximum size of the text field which is determined when we create an instance of the TextField class
The constructor of the TextField takes four parameters for the creation of TextField object.

The first parameter is the label that appears when the instance is displayed on the screen.
The second parameter is a string that will appear as the default text for the instance, which the user can edit.
The third parameter is an integer that determines the maximum number of characters that can be held by the instance
The last parameter passed to the constructor of the TextField class is the constraint (if any) that is used to restrict the type of characters that the user can enter into the text field.
The table given below lists the constraints recognized by the TextField class.

The instance of the TextField class accepts any character if the ANY constraint is set.
We can restrict entry to numeric characters by passing the NUMERIC constraint to the constructor. All non-numeric characters are excluded from the text field.

Given below is a line of code that creates an instance of a TextField object:

textfield = new TextField("First Name:", "", 30, TextField.ANY);

The above line of code creates a text field object named textfield with the caption "First Name:" without any text displayed in it. The maximum number of characters allowed to be entered in it are 30. Moreover it allows the user to type any character in it.

The methods of TextField objects as as follows:

getMaxSize() method determines the actual character size of a text box
Change the maximum size by calling the setMaxSize() method. The setMaxSize() method requires one parameter, which is the new value for the maximum size of the text field.
To know the the number of characters existing in the text field, call the size() method , which returns an integer representing the value.
getString() method returns the content of the text field as a string, where as getChars() method returns the text field content as a character array. In order to return the content of the text field as a character array, getChars() method requires the programmer to pass a character array as a parameter.
We can change the content of the text field object by calling either the setString() method or the setChars() method.
The setString() method requires one parameter, which is the string containing text that should appear in the text field.
The setChars() method requires three parameters. The first is the character array whose data will populate the text field. The second is the position of the first character within the array that will be placed into the text field. The last parameter is the length of characters of the character array that will be placed into the text field. Characters in the character array will replace the entire content of the text field.

Selecting Elements Using ChoiceGroups

The ChoiceGroup is an MIDP UI widget enabling the user to choose between different elements in a Form.
Choice elements consist of simple Strings, but can display an optional image per element as well.
ChoiceGroups can be of two different types - Exclusive (Single Selection) and Multiple (Multi Selection). The type constants are defined in the Choice interface.

The ChoiceGroup constructor requires at least a label and a type value. Additionally, a String array and an Image array containing the elements can be passed to the constructor.
Elements can also be added dynamically using the append() method. The append() method has two parameters, a String for the label and an Image.
In both cases, the image parameter may be null if no images are desired. The last parameter of the constructor is set to null if we do not want Images to be displayed at this time.

Here is a line of code that creates a ChoiceGroup Object for displaying a group of currencies:

ChoiceGroup currency = new ChoiceGroup ("Currency", Choice.EXCLUSIVE, new String[] {"USD", "EUR", "JPY"}, null);

mainForm.append (currency);

The below figure shows the UI created using ChoiceGroup class to display a group of currencies on a form:

Here is a link to know more about Item Objects.

Search This Blog