HOWTO: Using ComplexLists

ComplexLists are multi-column, multi-select list boxes, such as the one below:

To program a ComplexList, you need to:

  1. Set up the columns
  2. Insert data
  3. Retrieve the selection

1. Setting up the Columns

The following code declares the columns for the example ComplexList above.

		
        private ComplexColumn lstFlightDetailColumns [] =
          {
          new ComplexColumn(ComplexItem.StringType, "Flight No", 80, ComplexList.LEFT),
          new ComplexColumn(ComplexItem.StringType, "Departs ", 70, ComplexList.RIGHT) ,
          new ComplexColumn(ComplexItem.StringType, "Seats Booked ", 90, ComplexList.RIGHT) ,
          new ComplexColumn(ComplexItem.StringType, "Seats Free ", 80, ComplexList.RIGHT)
          } ;		
		

The parameters to the ComplexColumn constructor are as follows:

1 Column Type

ComplexItem.StringType or ComplexItem.ImageType

String type columns display text. Image type columns display image files.
2 Description String The text which will appear in the column heading
3 Column Width int Width in pixels of the column
4 Alignment

ComplexList.LEFT or
ComplexList.CENTER or
ComplexList.RIGHT

Alignment of the column (optional, defaults to LEFT)

To tell the ComplexList to use these columns, call setColumns (generally in defineComponents()), like so:

          lstFlightDetail.setColumns(lstFlightDetailColumns) ;
When creating a ComplexList, you may optionally allow multi-select behaviour. You can set mult-select on or off by calling complexList.setMultipleMode(). Note that the ComplexList multiple selection behaviour is different to that you may be used to in Windows. In a ComplexList, clicking on a row toggles the selection on or off - shift-clicking and control-clicking do not work as they do in Windows.

2. Filling the List

To remove all elements currently in the list, call complexList.removeAllItems() ;

To fill the list, you add ComplexLine objects one by one. ComplexLines contain "columns" (of type ComplexItem), which holds the data displayed in the column. Optionally, ComplexLines can contain a "line object", which is any object you may find useful to associate with this particular line.

An example of filling the complexList:

		  lstFlightDetail.removeAll();
			  
		  while (condition == true)
			{
			  ComplexLine cl = new ComplexLine() ;
				
			  cl.addColumn(new ComplexItem(ComplexItem.StringType, "column 1 goes here")); 
			  cl.addColumn(new ComplexItem(ComplexItem.StringType, "column 2 goes here")); 
			  cl.addColumn(new ComplexItem(ComplexItem.StringType, "column 3 goes here")); 
			  cl.addColumn(new ComplexItem(ComplexItem.StringType, "column 4 goes here")); 
					
			  cl.setLineObject(new MyHelpfulObject()) ;
					
			  complexList.add(complexLine) ;
			}

The parameters to the ComplexItem constructor are as follows:

1 Column Type

ComplexItem.StringType or ComplexItem.ImageType

String type columns display text. Image type columns display image files.
2 Data String The text which will appear in the column, if this is a StringType column. Otherwise, the URL of the image file that will be displayed in the column, if this is an ImageType column.

3. Getting the selection

How you do this depends on whether you have multi-select mode on or off.

For ComplexLists where multi-select is off:

  1. Calling complexList.getSelectedIndex() returns the integer index of the currently selected row. If no row is selected, returns -1
  2. Calling complexList.getSelectedItem() returns a ComplexLine object. With this ComplexLine, you can call getLineObject() on each one to get the the line objects, if you associated line objects with the rows. If no row is selected, the function returns null

For ComplexLists where multi-select is on:

  1. Calling complexList.getSelectedIndexes() returns an integer array containing the indices of the currently selected rows. If no row is selected, returns null.
  2. Calling complexList.getSelectedItems() returns an array of ComplexLine objects.