4
JClass LiveTable Pro Data

The Cells Vector · Getting Data into a Table

This chapter describes the Cells Vector in detail and describes how to allocate and manipulate the Vector.

The Cells Vector

Cell values are stored internally as a Vector of Vectors (i.e. a Vector which contains a Vector of cell values). Each element of the Vector may be an instance of a String, JCString, Image, Component or other Object. If a cell contains an Object, the instance's toString() method is used to present a text display. To clear all values, call this method with a null argument, for example:

	setCells((JCVector)null);

When JClass LiveTable Pro draws or redraws each cell,¹ it retrieves the cell value from the Cells Vector pointed to by getCells() (this pointer and the Vector it points to should be considered read-only). If there is no Vector, or no value exists in the Vector for the cell, JClass LiveTable Pro draws a blank cell. ²

As a program or a user enters cell values, JClass LiveTable Pro automatically updates and maintains its Cells Vector.

This Vector is not tied to the table's attributes. Cells can be set to display Cells Vectors without affecting the attributes displayed (such as cell background colors and fonts). The next figure illustrates the separation of cell values from the table.

Relationship of Cells Vector to Table Attributes

Convenience Procedures

There are a number of procedures and methods that manipulate Cells Vectors. These are fully described in the following table.

addColumns(), addRows()	Inserts new rows/columns into the table's `Cells` `Vector` and increases `NumRows` and `NumColumns`. Keeps the attributes of existing rows/columns with their cell values.
deleteColumns(), deleteRows()	Removes rows/columns and their attributes from the table's `Cells` `Vector`. Decreases `NumRows` and `NumColumns`.
moveColumns(), moveRows()	Moves rows or columns within the table's `Cells` `Vector`. Keeps the attributes of existing rows/columns with their cell values.
sortbyColumn()	Sorts rows in the table `Cells` `Vector;` the String equivalents of any class based on Numeric cell values. Calling this method has no effect on the spanned ranges, cell properties or selected cells of the table, as only the values stored in the table are changed. After the table has been sorted, `SORT` is called.

Getting Data into a Table

There are cases when it is necessary to retrieve the data for a table from an external source. The JCFile class can retrieve data from a Universal Resource Locator (URL). The JCURLDirectory class can retrieve directory information from a base URL.

Information can also be retrieved by using a separate, non-HTML data file. This topic is covered in Chapter 6.

Data from a File

If the data can be formatted in a file, use JCFile.read to create a Cells Vector to read the values into it. This method reads data and parses it into separate cells based on a pre-defined delimiter, then converts it into cell values and returns it in a JCVector of JCVectors. This method can be used to retrieve data from a static source (i.e. a file), or from a dynamic data source (i.e. a CGI script). It uses the following prototype:

public static JCVector read(Component comp,
					 String file,
					 char delim,
					 boolean convert)

Its parameters include:

comp - the parent component, used to convert images. If an applet is available, pass it. Otherwise, pass the table itself
file - the URL that is to be read
delim - the delimiter used for parsing values, e.g. "," or "`"
convert - if true, convert the data. This assumes that the data in each cell is a JCString that could contain image references, text and hypertext links. If false, the file data is loaded "as is".

Note: You should set NumRows and NumColumns to the size of the cell values Vector when using readParseData() because the cell values Vector is independent of the number of rows/columns in the table. The following code shows how to do this:

	JCVector cells = JCFile.read(this, URL, ',', true, true);
	table.setCells(cells);
	// Set number of rows and columns
	int last_column = 0;
	for (int i = 0; i < cells.size(); i++) {
		JCVector row = (JCVector)cells.elementAt(i);
		if (row == null) continue;
		last_column = Math.max(last_column, row.size());
	}
	table.setNumColumns(last_column);
	System.out.println("# rows = " + cells.size());
	table.setNumRows(cells.size());
	table.setPixelWidth(JCTblEnum.ALL, JCTblEnum.ALL, JCTblEnum.VARIABLE);
	table.setPixelHeight(JCTblEnum.ALL, JCTblEnum.ALL, JCTblEnum.VARIABLE);

The last two lines in the previous example set the cell sizes to the size required by the data in the cell. This guarantees that the data will be visible.

JCFile provides other methods for loading data into a String (readLines()) or an array of Strings (read()). JCURLDirectory provides a method to retrieve a listing of URLs contained in a directory (getFileList()).

Manipulating Table Data

This section discusses manipulating data within a Cells Vector pointed to by getCells().

Setting and Retrieving Cell Values

User Editing

When a user edits a cell value, that value replaces the previous cell value. Unless you disable cell editing, users can change any cell values set by the application. See Chapter 5 for information on controlling interactive editing.

Retrieving Cell Values

There are two ways to retrieve cell values from a table:

Use getCells() to get the value of a single cell from the Vector of Vectors of Cells. For example:

	JCVector tempcells = table.getCells();
	if (tempcells.size() < 2) {
		System.out.println("No value at (2,3) - row missing");
	}
	else {
		JCVector row = (JCVector)tempcells.elementAt(1);
		if (row.size() < 3) {
			System.out.println("No value at (2,3) - column missing");
		}
		else {
			System.out.println("Value at (2,3) is " + 
				row.elementAt(2).toString());
		}
	}

Use getCells() to get the value of a cell at a particular location, for example:
```
     Object obj = table.getCell(1, 2);
     System.out.println("Value at (2,3) is " + obj.toString());
```
Use getCell() for retrieving individual cell values. Use getCells() if the Vector of Vectors of cells is going to be used in other ways (for example, to modify cell values).
By default, cell values are retrieved as an Object. Use Java's built-in run-time type-checking mechanism to convert to a more appropriate type. For example:
```
     Object obj=table.getCell(1, 2)
     if(obj instanceofJCString);
     JCString j=(JCString)obj;
```

Searching for Strings

There is no built-in search mechanism in JClass LiveTable Pro to search for strings, but it is easy to to implement a custom search method. The following is a short example of such a method:

	public boolean SearchTable(String find_it) {
		int row = getNumRows();
		int col = getNumColumns();
		for (int cnt = 0; cnt < row; cnt++)
			for (int cnt2 = 0; cnt2 < col; cnt2++)
				if (find_it.equals(getCell(cnt,cnt2))) {
					System.out.println("Found it!!");
					return true;
}
				return false;
	}

Call this function with a statement like:

     Table.SearchTable(new String("Find me"));

Adding Rows and Columns

addColumns() and addRows() insert new rows and columns into the table, optionally filling the new cells with values. addColumns() shifts existing cell values and attributes (such as, for example, background color) to the right. addRows() shifts existing cell values and attributes down. You can specify whether to shift existing labels along with the rows or columns shifted. NumRows or NumColumns is updated to reflect the insertion.

When using addColumns() and addRows(), note the following:

If you do not supply values for the new cells within the method, they are blank. Values for the new row or column labels must be specified separately. The starting row or column cannot be greater than NumRows or NumColumns.
When no values are specified for a new row or column having a variable height/width, the row/column does not appear--the row/column is hidden. For more information on variable rows/columns, see Row Height and Column Width.
If the current cell is at or below the starting row/column, any cell editing is cancelled, and the Text component is unmapped.
Values are specified as an array of Objects.

The prototype for the addColumns() instance method is as follows:

	public boolean addColumn(int position,
					Object label,
					Vector values)

The position parameter is the initial column index, and new columns are added prior to this position. If this is set to JCTblEnum.MAXINT, the column is added after the final column. The label parameter refers to the column label, and values to the array of objects to be inserted. Both the labels and values parameters can be set to null. addColumn() returns false if any of the arguments are invalid.

The following example inserts five columns before column zero, with the first column populated with three values:

	String va[] = { new String("a"), new String("b"), new String("c") };
	JCVector values = new JCVector(va);
	// Add first column with values
	table.addColumn(0, null, values);
	// Add other four columns
	table.addColumn(1, null, null);
	table.addColumn(1, null, null);
	table.addColumn(1, null, null);
	table.addColumn(1, null, null);

Deleting Rows and Columns

deleteColumns() and deleteRows() delete rows and columns from the table. deleteColumns() shifts existing cell values and attributes to the left. deleteRows() shifts existing cell values and attributes up. You can specify whether to shift existing labels along with the shifted rows or columns. NumRows or NumColumns is updated to reflect the deletion.

When using deleteColumns() and deleteRows(), note the following:

The starting row or column cannot be greater than NumRows or NumColumns.
If the current cell is at or below the starting row or column, any cell editing is cancelled, and the Text component is unmapped.
Decreasing NumRows or NumColumns does not delete rows or columns from the table; it only decreases the scrollable region.

The prototype for the deleteColumns() instance method is as follows:

public boolean deleteColumns(int pos,
					int num_columns)

Its parameters include pos, which designates the first column number to be deleted, and num_columns, which is the number of columns to be deleted. deleteColumns() returns false if any of the arguments are invalid.

The following call deletes columns 2 through 5, and shifts the column labels up along with the columns:

     table.deleteColumns(1, 4);

Moving Rows and Columns

moveColumns() and moveRows() moves rows and columns (and optionally the labels) within the table. moveColumns() and moveRows() shift existing cell values and attributes (such as background color) affected by the move. You can specify whether to move existing labels along with the rows or columns moved.

The source or destination row or column cannot be greater than the corresponding NumRows or NumColumns value.

If the current cell is at or below any affected row or column, any cell editing is cancelled, and the Text component is unmapped.

The prototype of the moveColumns() instance method is as follows:

public boolean moveColumns(int source,
					int num_columns,
					int destination)

Its parameters include source, which is the first column in the range, num_columns, which is the number of columns to move, and destination, the column number the moved columns are placed immediately before (i.e. this column number minus one column is where the moved columns are placed). moveColumns() returns false if any of the arguments are invalid.

The following call moves rows 4 through 6 to start before the first row, without shifting the labels:

     table.moveRows(3, 3, 0);

Clearing Cell Values

You can easily clear the cell values for cells, rows, columns, or the entire table by setting Cells to null for that context. The visual attributes of the cells do not change.

You can clear individual cell values using setCell(). The following example clears the cell at row 5, column 2:

	setCell(4, 1, null);

To clear a range of cells, try something similar to the code below, which clears a block from row 4 to row 6, from column 2 to column 4:

     JCVector cells = table.getCells();
     for (int row = 3; row < 6; row++) {
     for (int col = 1; col < 4; col++) {
		((JCVector)cells.elementAt(row)).setElementAt(col, null);
	}
}
table.setCells(cells);

Alternatively, setRepaint() can also be used to minimize any repaints that may occur when using setCell():

table.setRepaint(false);
for (int row = 3; row < 6; row++) {
	for (int col = 1; col < 4; col++) {
		table.setCell(row, col, null);
	}
}
table.setRepaint(true);

Clearing the Entire Table

To clear the table of all cell values, set clearCells(). The NumRows and NumColumns properties do not change, and any attributes defined for the table remain in effect.

¹ JClass LiveTable Pro draws cells as a result of scrolling or other expose events.

² If a cell value method has been defined, the table calls that method for the value to display for blank cells.

4 JClass LiveTable Pro Data