Scrolling List Boxes

Applications such as the iTunes¨ browser present lists of items in (multiple) scrolling boxes.  When the user selects an item in a scrolling list box, information might then be updated in other areas of the window, and the user can select a command to remove or rename the selected item, among other things.

The window of a demo program that manages a list of employees is shown below. Each employee has information of the sort seen in earlier examples. 

 

 

The information about the employees is displayed in two areas. On the left, in a scrolling list box, appears a list of employees' names. On the right, in a text area, appears the detailed information of the employee selected in the list box. A drop-down menu includes commands to add a new employee, or to modify or delete a selected employee.

When the user selects Add or Modify, a dialog like the one used in the dialog demo pops up to receive information. In addition, when the user double-clicks on a name in the list box, a dialog pops up to edit the selected employee's information.

Although the userÕs interactions with this application are fairly simple, the code that supports it is rather complicated.  Therefore, the programÕs functions are best discussed in small pieces.  The code for the main window is in EmployeeSystem.java, while the rest of the system is as it was in the dialog demo.

The program begins by adding the window components to the window and creating the data model. The data model consists of two objects: a list of employee objects and a reference to a selected employee object. The list is an initially empty instance of java.util.ArrayList, and the selected employee is null at program startup. Note that the scrolling list box is added with the method addList, and occuppies the same number of rows as the text area.

 

/* EmployeeSystem.java

1) This program maintains a list of employees and displays their names

   in a scrolling list control.

 

2) Single clicking on a name displays the employee's information.

 

3) Double clicking on a name allows the employee's information to be

   changed.

 

4) Other operations are supported by means of an Edit menu with the options:

 

   Add    -- adds a new employee to the end of the list and selects the

             name in the scrolling list

 

   Modify -- modifies the selected employee

 

   Delete -- deletes the selected employee

 

5) The selected employee is the one corresponding to the highlighted

   name in the scrolling list control.

*/

 

import javax.swing.*;

import java.util.*;

import BreezySwing.*;

 

public class EmployeeSystem extends GBFrame{

 

   // Window objects

   JLabel namesLB              = addLabel ("Names"               ,1,1,1,1);

   JLabel detailedInfoLB       = addLabel ("Detailed Information",1,2,1,1);

 

   JList nameList              = addList (                        2,1,1,5);

   JTextArea detailedInfoField = addTextArea (""                 ,2,2,1,5);

 

   JMenuItem addMenuItem    = addMenuItem ("Edit", "Add");

   JMenuItem modifyMenuItem = addMenuItem ("Edit", "Modify");

   JMenuItem deleteMenuItem = addMenuItem ("Edit", "Delete");

 

   // Instance variables

   private java.util.List<Employee> employeeList; // List of employee objects

   private Employee selectedEmployee;             // Selected employee if there is one

 

   public EmployeeSystem(){

   // Constructor

   //  Preconditions  -- none

   //  Postconditions -- title of window set

   //                 -- instance variables initialized

 

      employeeList = new ArrayList<Employee>();  // Instantiate a new list

      selectedEmployee = null;                   // No employee is selected

   }

 

The rest of the program is structured in terms of a set of event handler methods and associated helper methods. We discuss a few of these here, and refer the reader to the file EmployeeSystem.java for the complete program details.

When a list box is added to the window with BreezySwing, the programmer can supply two event handler methods, named listItemSelected and listDoubleClicked.  The first method is triggered when the user selects an item in a list box or the user double-clicks on an item.  The second method is triggered only on a double-click on a list item. Here is the code for these two methods in the example program:

 

   public void listItemSelected (JList listObj){

   // Displays the information for the employee whose name is selected.

   //  Preconditions  -- a name in the name list is single clicked

   //  Postconditions -- the employee corresponding to the name

   //                    is selected and her info is displayed

 

      int index = nameList.getSelectedIndex();

      selectedEmployee = employeeList.get(index);

      displaySelectedEmployee();

   }

 

   public void listDoubleClicked (JList listObj, String itemClicked){

   // Opens a modify dialog on the employee whose name is selected.

   // Note: double clicking on a name automatically triggers the single click

   //      event first.

   //  Preconditions  -- a name in the list is double clicked

   //  Postconditions -- see the modifySelectedEmployee method  

 

      modifySelectedEmployee();

   }

 

The listItemSelected method gets the index of the selected item in the list box, sets the selected employee to the employee at that position in the list of employee objects, and calls the method displaySelectedEmployee (to be defined later) to display its detailed information.

The listDoubleClicked method simply calls the method modifyEmployee (to be defined later) to pop up an edit dialog. Recall that the listItemSelected method has already been triggered by a double-click, so the selected employee object and the text area have already been updated.

Here is the code for the method displaySelectedEmployee, which updates the text area with the selected employee's information is there is one:

   private void displaySelectedEmployee(){

   // Displays the selected employee's info in the info area

   //  Preconditions  -- none

   //  Postconditions -- if there is no selected employee, then no change

   //                 -- else the selected employee's info is displayed

 

      String str = "";

      if (selectedEmployee != null)

         str = selectedEmployee.toString();

      detailedInfoField.setText (str);

   }

 

The method addNewEmployee creates a new instance of the Employee class and sends it to an edit dialog. If the user quits the dialog with "OK," the method updates the data model, by adding the employee to the list of employees and establishing it as the selected employee. The method then updates the view, by adding the employee's name to the list box's model, setting the list box's selected index to the employee's index in the list of employees, and updating the text area with the selected employee's information. Here is the code for this method:

   private void addNewEmployee(){

   // Adds a new employee.

   //  Preconditions  -- none

   //  Postconditions -- if the user cancels the dialog, then no change

   //                 -- else the new employee is selected

   //                      she is added to the end of the employee list

   //                      her name is added to the end of the name list

   //                      her info is displayed

   //                      she becomes the selected item in both lists  

 

      int index;

 

      Employee tempEmp = new Employee();

      EmployeeDialog employeeDialog

                     = new EmployeeDialog (this, tempEmp);

      employeeDialog.setVisible (true);

 

      if (employeeDialog.getDlgCloseIndicator().equals ("OK")){

         selectedEmployee = tempEmp;

         employeeList.add (selectedEmployee);

         DefaultListModel model = (DefaultListModel) nameList.getModel();

         model.addElement (selectedEmployee.getName());

         index = employeeList.size() - 1;

         nameList.setSelectedIndex (index);

         displaySelectedEmployee();

      }

   }

 

The method modifyEmployee is similar in structure to addNewEmployee, but passes the selected employee as an argument to the edit dialog. If changes occur in the dialog, the method does not have to update the model, but it must replace the name currenly selected in the list box with the name in the edited employee object, which may have changed. We omit the code for this method and for the methods deleteSelectedEmployee and menuItemSelected, which appear in the file EmployeeSystem.java.

The scrolling list box is a powerfull and complex window component, and you are encouraged to explore the Javadoc for further details on its attributes and behavior.

 

Back to tutorial Next topic: Check boxes, radio buttons, and combo boxes