ObjectComboBox Component

Overview

Purpose

The ObjectComboBox suite consists of one bean - the ObjectComboBox Bean.

This bean presents a graphical interface to the user and allows the user to select or edit the items in a list. The ObjectComboBox is a text field with an attached drop-down list box. It can add not only string items but also object items of any kind into the list directly. It may be editable and/or searchable. Editable means the user can enter any desired text into the text field and searchable means ObjectComboBox will highlight an item if the name of item matches the string that the user has typed in.

Audience

This document is intended to be used by application builders who would like to build Java applications which provide ObjectComboBox functionality.

The application developer is expected to be familiar with the Java language and the JavaBeans architecture. The developer should be familiar with building applications by linking beans in an application builder tool. Familiarity with the functionality of ObjectComboBox would be advantageous, though not mandatory if the developer does not intend to extend the functionality provided by the bean.

How to Use This Guide

Guide Conventions

Typographical Conventions

Conventions	Description	Example
Text in bold	buttons and field names of dialog boxes	OK, Cancel, Port, Socks Server, etc.
Text in italics	names of dialog boxes, figures, reference to chapters and other sections, task name etc.	Confirm dialog, Figure 1, Overview, etc.
Round bullets	list of points	ObjectComboBox Bean
Numbered list 1, 2, 3, ....	sequential steps	After downloading ObjectComboBox .
Text in *Bold and Italics*	name of the file	ObjectComboBox *.zip, readme.html*
Text in Courier font	names of classes, methods, events, part of code included in the document, etc.	ActionPerformed

Mouse Conventions

Conventions	Description	Example
Select	Click the left mouse button	Select the File menu.

Keyboard Conventions

Keys	Represented
Control	Ctrl

Images

Image	Used to
	navigate to the previous sub-heading
	navigate to the previous main heading
	return to the Table of Contents
	represent a Note information

Guide Organization

Overview - introduces the user to the ObjectComboBox bean. Provides information like intended audience, guide organization and copyrights.

Component Description - describes the ObjectComboBox component in general. Gives information on domain concepts, list of bean in the suite and deployment scenarios.

Installation Instructions - describes the hardware and software required for installing and using the ObjectComboBox component, and also describes how to install the bean and prepare it for use.

Usage Instructions - provides information on bean usage, wiring scenarios and serialization.

Alternating Wiring Scenarios - describes special wiring scenarios that may involve beans within and outside the component suite.

Individual Bean Documentation - provides links to individual bean documentation which describes each bean in the suite with respect to its events, properties, methods etc.

User Interface - describes the various user interface components like menus, dialog boxes etc. of the ObjectComboBox component.

Error Messages - lists the various error messages that may appear when using the bean.

Demo Application - describes the demo application and provides instructions on how to run the demo application.

References - provides links to internet sites which give substantial reference documentation.

Glossary - gives a brief explanation of some of the technical terms used in the document.

Copyrights And Trademarks

IBM and VisualAge are trademarks of International Business Machines in the United States and/or other countries.

* Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc, in the U.S. and other countries.

Component Description

Domain Concepts

The ObjectComboBox is a graphical interface to the user and allows the user to select or edit the items in a list.

General Description

List of Beans

The ObjectComboBox suite consists of :

ObjectComboBox Bean

Deployment Scenarios

The ObjectComboBox can be used to select or edit the items in a list. For example: Programmer creates a demo application that demonstrates how the ObjectComboBox bean will work. If user adds items or selects items in run time mode, the text area will display the corresponding messages.

see Demo Application

Installation Instructions

Hardware Requirements

This bean is designed to be compliant with 100% Pure Java requirements, and can therefore be executed on any hardware platform that supports the Java Environment.

36 KB(48 KB for Visual Cafe 2.0) of disk space is required to install the ObjectComboBox Bean Jar files. Additional hard disk space would be required to install the Java Development Kit, Bean Development Kit or any Java Application Builder Tool which may be used to build / compile applications using this bean.

Software Requirements

The ObjectComboBox bean is designed to work with Java Development Kit Version 1.1 and above.

This bean may be linked to other beans and tested in the BeanBox testing tool from JavaSoft.

Any Java Application Builder (e.g., VisualAge for Java from IBM Corp, VisualCafé from Symantec Corp., Java Workshop from SunSoft) with JavaBeans support may be used to develop applications using this bean.

Installation

After downloading ObjectComboBox .zip, unzip it. It will automatically create a new directory called ObjectComboBox and extract files into it.
To use the components in the BeanBox, copy (using the relevant copy command on the operating system) the jar file for the required component (available in the lib directory) to the BeanBox's jars directory.
To use any component in any of the IDEs, import the corresponding .jar file.
Note : Please refer to the User's Guide of your IDE on how to import a bean into the IDE.
To run the demo application provided with this package, see Demo Application.

Platform Dependencies

There are no platform-specific issues for the ObjectComboBox suite. Any operating system that supports Java can be used.

Usage Instructions

Bean Usage

The jar files of the ObjectComboBox bean should be added to the jars directory of the BeanBox. To use any component in other IDEs, import the corresponding .jar file. The wiring scenarios are described below.

Wiring Scenario

No special procedure is involved in integrating all the beans in the suite, because this suite has just one bean.

Serialization

The ObjectComboBox bean is serializable.

Alternate Wiring Scenarios

In this scenario, application builder would use the ObjectComboBox bean in the application(in VisualAge for Java 1.0).

Wiring the ObjectComboBox requires the following events:

The ComboBoxListEvent invokes the ComboBoxListListener's "itemSelected" event .

1. Application Design Time:

Scenario 1.1: Creates an ObjectComboBox and a TextArea in the application builder.

Assumptions:

An application frame already exists in IDE.
Programmer selects an ObjectComboBox and puts it into the frame.
Programmer selects a TextArea and puts it into the frame

Outcomes:

The ObjectComboxBox and the TextArea appear.

Scenario 1.2: Adds list items to ObjectComboBox.

Assumptions:

The ObjectComboBox exists.
Programmer selects "ListItems" property.

Programmer inputs items "Jimmy", "Ronald","George", "Bill" and "Monica".

Outcomes:

Items have been inserted to the ObjectComboBox.

Scenario 1.3: Sets selected index of the ObjectComboBox.

Assumptions:

The ObjectComboBox exists.
Programmer selects "SelectedIndex" property, and sets it to 0.

Outcomes:

Selected Item displays in the ObjectComboBox.

Scenario 1.4: Wires ObjectComboBox with a TextArea.

Assumptions:

The ObjectComboBox and the TextArea exist.
Programmer selects the ObjectComboBox, and clicks right mouse button on it. After selecting Connect -> All Features... , a connection dialog appears. Programmer selects the "itemSelected" event .

Programmer drags the wiring line to the TextArea, and clicks left mouse button. After selecting Connect -> All Features... , a connection dialog appears. Programmer selects the "append" method.

Outcomes:

A link has been created between the "itemSelected" event and the "append" method.

Scenario 1.5: Sets the parameter of the "append" method.

Assumptions:

The ObjectComboBox and TextArea exist.
Programmer selects the ObjectComboBox, and clicks right mouse button on it. After selecting Connect -> All Features... , a connection dialog appears. Programmer selects the "getSelectedDisplayName" method.

Programmer drags the new link to the link between the "itemSelected" event and the "append" method, clicks left mouse button and selects "str" parameter.

Outcomes:

The selected name is applied to the "append" method as the parameter.

Scenario 1.6: Calls "append" method in order to display the newly added items in different lines.

Assumptions:

A link has been created between the "itemSelected" event and the "append" method, just as mentioned in Scenario 1.5.
Programmer double-clicks the link , a connection dialog appears. Programmer pushes the "Set parameter" button, a setting dialog appears. The string parameter "\n" is applied to the "append" method.

Outcomes:

A new link has been created between the "itemSelected" event and the "append" method.

2.Run Time:

The user runs the application.

Scenaro 1: Selects an item from the list portion in ObjectComboBox.

Assumptions:

User drops down the list by clicking the arrow button.
User selects an item named "George" from the list portion.

Outcomes:

The text portion is set to "George", and the TextArea is set to "George".

Individual Bean Documentation

ObjectComboBox Bean

User Interface

This section describes the user interface of the ObjectComboBox bean.

As shown in Figure 1, the ObjectComboBox bean is rather a simple bean, just like the ComboBox in Windows system.

Figure 1 - ObjectComboBox

The ObjectComboBox contains a Text Field and a Drop-down List. Whenever the Enter key is pressed, the record in the Text Field is added to the Drop-down list as the last item. Note that when the user attempts to add the same record twice, the ObjectComboBox ignores the latter. If the record entered to the Text Field is a part of one of the items in the list, the ObjectComboBox highlights the item in the Text Field.

Error Messages

No special error messages might occur while using the ObjectComboBox bean.

Demo Application

The demo directory contains all the necessary files for running the demo. The main demo file is Demo.class. This demo application demonstrates how the ObjectComboBox component works.

To run the demo application provided with this package, follow the steps given below :

Make sure that the java executable is in the PATH and also the CLASSPATH variable points to the classes.zip in the JDK's lib directory.
Set the CLASSPATH environment variable according to the instructions given under the sub-heading Setting the CLASSPATH below.
Type java Demo in the command prompt. All the screens that come up in the demo application are explained in the section User Interface.

Setting the CLASSPATH

WINDOWS CLASSPATH

After installing the software, update the CLASSPATH environment variable as follows :

For WINDOWS NT :
Start the Control Panel, select System, then edit the CLASSPATH environment variable.

Set the CLASSPATH to point to
.;ObjectComboBox\lib\objectcombobox.jar

For WINDOWS 95 :

To change the CLASSPATH, open the AUTOEXEC.BAT file and make the change to the CLASSPATH statement. (Be sure to make a backup of the AUTOEXEC.BAT before making any changes).

Set the CLASSPATH to point to
.;ObjectComboBox\lib\objectcombobox.jar

For example, if objectcombobox is installed under C:\ then set CLASSPATH as (add the following line to the end of the AUTOEXEC.BAT file.)

.;c:\ObjectComboBox\lib\objectcombobox.jar;%CLASSPATH%

Reboot the machine for the changes to take effect.

AIX CLASSPATH

After installing the software, update the CLASSPATH environment variable as follows :

Open the .profile file and set the CLASSPATH environment variable. (Be sure to make a backup of the .profile before making any changes.)

Set the CLASSPATH to point to
.:ObjectComboBox\lib\objectcombobox.jar

For example, if objectcombobox is installed under the home directory then set CLASSPATH as - (add the following line to the end of the .profile file.)

export CLASSPATH = .:ObjectComboBox\lib\objectcombobox.jar:$CLASSPATH

Type . .profile on the command line for the changes to take effect.

OS/2 CLASSPATH

After installing the software, update the CLASSPATH environment variable as follows :

Open the CONFIG.SYS file and change the CLASSPATH statement. (Be sure to make a backup of the CONFIG.SYS before making any changes.)

Set the CLASSPATH to point to
ObjectComboBox\lib\objectcombobox.jar

For example, if objectcombobox is installed under C:\ then set CLASSPATH as (append the following to the CLASSPATH environment variable of the CONFIG.SYS file.)

.;c:\ObjectComboBox\lib\objectcombobox.jar;%CLASSPATH%

Reboot the machine for the changes to take effect

Running the demo application

The whole source code is Demo.java.

This demo application demonstrates how the ObjectComboBox component works. If the user adds items or selects items at run time, the text area will display the corresponding messages.

The Main Screen :

References

Java Programming Language

Java Beans Specifications

Glossary of Terms

A | B | C | J | O |

A
API	Application Programming Interface.
Application (or Applet)	A software product that uses (includes) the ObjectComboBox component.
B
Bean	A bean is a JavaBeans component. It is an independent, reusable software module. Beans may be visible objects, like AWT components, or invisible objects, like queues and stacks. A builder / integration tool manipulates beans to create applets and applications.
C
Component	A piece of software isolated into a discrete, easily reusable structure.
J
Java	An object-oriented programming language developed by Sun Microsystems. Java programs are compiled into class files that can run on any computer platform that has a Java Virtual Machine.
JavaBeans	A portable, platform-independent component model, based on Java. The model allows creation of small, reusable software components. A visual builder program combines components from different sources to create applications quickly and easily.
O
ObjectComboBox	The ObjectComboBox presents a graphical interface to the user and allows the user to select or edit the items in a list. The ObjectComboBox is a text field with an attached drop-down list box. It can add not only string items but also object items of any kind into the list directly. It may be user-editable and/or searchable. User-editable means ObjectComboBox allows the user to enter any desired text into the text field and searchable means ObjectComboBox highlights an item if the name of item matches the string that the user has typed in.

This document is last updated in v1.0 on 04/06/1998