3
Programming JClass LiveTable Pro

Row and Column Labels · Table Titles · Row Height and Column Width

Cell and Label Margins · Foreground, Background and Shadow Colors

Cell and Label Text Alignment · Cell and Label Fonts

Border Types and Sides · Images · Text and Image Clipping

Cell and Label Spanning · User Data

Property Summary

Each of these properties have two accessor methods: set and get. Methods are instantiated using set(PropertyName), and you can retrieve the current value of any property using the property's get method.

Number of Rows/Columns

These properties are independent of the Cells structure that stores the cell values. NumRows/NumColumns can be smaller or larger than the number of rows/columns in the table's cell values structure, as shown in the following figure.

For example, you could temporarily "delete" rows from the bottom of the table by reducing the value of NumRows. The rows could be restored later by increasing NumRows.

The number of rows/columns must be greater than the number of frozen rows/columns. For more information on frozen rows/columns, see Frozen Rows and Columns.

Visible Rows/Columns

These properties are dynamically updated as other table properties change and when a user interacts with the component.

You can force the table to display a particular number of rows or columns by setting these properties. Setting visible rows/columns always causes the table to attempt to resize itself, overriding the resize policy set by AllowResize.

You cannot set the number of visible rows or columns to greater than the corresponding NumRows and NumColumns properties.

Displaying the Entire Table

Frozen Rows and Columns

Frozen rows/columns always start from the beginning of the table. They are still editable and traversable unless set otherwise. The following figure shows an example of frozen rows.

Use frozen rows/columns to hold important information (such as totals at the bottom of the table) on the screen as a user scrolls through the table. Another use is as additional rows/columns that act like labels.

Freezing Rows and Columns

For example, the following code moves row 5 to the beginning of the table, and then freezes it:

 
     table.moveRows(4, 1, 0);
     table.setFrozenRows(1);

Frozen Row/Column Placement

To change the placement of the frozen rows, set FrozenRowPlacement to either PLACE_TOP or PLACE_BOTTOM.

To change the placement of all frozen columns, set FrozenColumnPlacement to either PLACE_LEFT or PLACE_RIGHT.

Row and Column Labels

Note that setColumnLabels() and setRowLabels() does not affect the number of rows and columns a table displays.

Setting and Retrieving Label Values

Setting All Labels

     String clabels[] = { "Name", "Address",
"Phone Number", "Position", "Salary" };
...
     table.setColumnLabels(clabels);

Setting Individual Label Values

  
     setColumnLabel (3, 56, Color.red)

Retrieving a Label

 
     Vector v2 = table.getColumnLabels();
     for (int i = 0; i < v2.size(); i++) {
          Object o = v2.elementAt(i);
               System.out.println(     }

Label Placement and Spacing

Label Placement

• PLACE_TOP - label displayed at top of table
• PLACE_BOTTOM - label displayed at bottom of table
• PLACE_LEFT - label displayed to left of table
• PLACE_RIGHT - label displayed to right of table

Label Spacing

Table Titles

Adding a Title

     JCTitleLayout jct = new JCTitleLayout();
     setLayout(jct);
     Label label = new Label("Employee Listing");
     // Make the label stick out so we can see the offsets
     label.setBackground(Color.cyan);
     label.setForeground(Color.black);
     label.setFont(new Font("TimesRoman", Font.BOLD, 20));
     add("Top", label);

Positioning a Title

     Label label2 = new Label("(0, -15, 0, 20)");
     // Make the label stick out so we can see the offsets
     label2.setBackground(Color.cyan);
     label2.setForeground(Color.black);
     add("Bottom", label2);
     jct.setOffsets("Bottom", new Insets(0, -15, 0, 20));

The following example adds another title, offset 20 pixels to the top, 0 pixels at left, -15 at bottom and 0 to the right:

     Label label3 = new Label("(20, 0, -15, 0)");
     // Make the label stick out so we can see the offsets
     label3.setBackground(Color.cyan);
     label3.setForeground(Color.black);
     add("Left", label3);
     jct.setOffsets("Left", new Insets(20, 0, -15, 0));

These properties specify the space around the title. The previous figure shows how the offsets are measured when the title is on each side of the table. Offsets can be positive, negative, or JCTblEnum.NOVALUE.

Positive values add space between the title and the table. Negative values remove space between the title and the table. Setting an offset to zero causes the title to touch the cells/labels or the edge of the table component.

JCTblEnum.NOVALUE specifies a floating, unanchored offset; the actual positioning depends on the setting of the opposite offset property. For example, if LeftOffset and RightOffset are set to JCTblEnum.NOVALUE, JClass LiveTable Pro centers the title horizontally. If the opposite offset property is set to an explicit pixel value, the title is anchored at that value.

Resize Handling

Row Height and Column Width

JClass LiveTable Pro provides two different ways to specify row height and column width: character and pixel. Character specification determines the height/width by the number of characters or lines that the row/column can display. Pixel specification determines the height/width by the explicit number of pixels.

Only one method can be used for a row or column. Pixel specification overrides character specification.

Note: When users interactively resize rows/columns, the row height/column width is specified by pixel regardless of how your application specified it. You can be notified and optionally change user resizing by using RESIZE_CELL.

Character Height and Width

Character specification is convenient when you know how many characters you want a row/column to display. It works best with non-proportional² fonts because JClass LiveTable Pro uses the widest character along with the largest ascender/descender to guarantee that the specified number of characters will fit in the cell or label.

The following example sets the width of the third column to 15 characters:

	table.setCharWidth(2, 15);

To determine the pixel dimensions of a row or column whose height/width was set by CharWidth or CharHeight, use getPosition().

Pixel Height and Width

Unless set to JCTblEnum.NOVALUE (default), these properties override the CharWidth and CharHeight properties. The next illustration shows setting PixelHeight to a pixel value.

The following code sets the width of the second column to 120 pixels:

     table.setPixelWidth(1, 120);
     // Wraps the text
     table.setMultiline(JCTblEnum.ALLCELLS, 1, true);

Variable Height and Width

When a cell contains a component, JClass LiveTable Pro sizes the cell to fit the component's preferred size.

Note: Once a user has resized a row or column, variable row/column resizing ends because the row/column size is specified by an explicit number of pixels. User cell editing does not automatically change the size of rows/columns.

If your application is making a lot of changes to a table, turn repainting off by setting Repaint to false, make the changes, and then turn repainting on to update the table display.

To determine the pixel dimensions of a row or column with variable height or width, use getPosition().

Hiding Rows and Columns

The current cell should not be in the hidden row/column.

To reveal a hidden row/column, set the pixel height or width to a pixel value or JCTblEnum.NOVALUE (to use the character specification defined for the row/column).

Cell and Label Margins

The margin properties cannot be smaller than the value of FrameShadowThickness.

Foreground, Background and Shadow Colors

Specifying Colors

     table.setBackground(JCTblEnum.ALL, 1, Color.blue);
     table.setForeground(0, 3, Color.white);

Selected Cells

When SelectedBackground is set to null, selected cells look identical to unselected cells--the background and foreground colors are the same as the colors defined for the cells.

Repeating Colors

     Color[] c1 = { Color.orange, Color.green, Color.magenta };
     table.setRepeatBackgroundColors(c1);
     table.setBackground(JCTblEnum.ALLCELLS, JCTblEnum.ALLCELLS, JCTblEnum.REPEAT_COLUMN);

You can define as many repeating colors as you like. The colors are always selected in the order listed.

JCTblEnum.REPEAT_ROW repeats colors in row order, whereas JCTblEnum.REPEAT_COLUMN repeats colors in column order. The following illustration displays the effect of each setting.

To set the foreground colors for the current context to a repeating color list defined by RepeatForegroundColors, set ForegroundContext to JCTblEnum.REPEAT_ROW or JCTblEnum.REPEAT_COLUMN.

Cell and Label Text Alignment

• JCTblEnum.TOPLEFT
• JCTblEnum.TOPCENTER
• JCTblEnum.TOPRIGHT
• JCTblEnum.MIDDLELEFT
• JCTblEnum.MIDDLECENTER
• JCTblEnum.MIDDLERIGHT
• JCTblEnum.BOTTOMLEFT
• JCTblEnum.BOTTOMCENTER
• JCTblEnum.BOTTOMRIGHT

Cell and Label Fonts

     table.setFont(JCTblEnum.LABEL, JCTblEnum.ALL, 
     new Font("TimesRoman", Font.ITALIC, 20));

Border Types and Sides

In addition, the table frame, which encloses the cells and labels, can have the visual look of its border customized.

Cell and Label Border Types

The following example sets a blank border for a row:

     table.setBorderType(2, JCTblEnum.ALLCELLS, 
     JCTblEnum.BORDER_NONE);

Cell and Label Border Thickness

Cell and Label Border Sides

The valid values for BorderSides are:

• BORDERSIDE_LEFT
• BORDERSIDE_RIGHT
• BORDERSIDE_TOP
• BORDERSIDE_BOTTOM
• BORDERSIDE_ALL
• BORDERSIDE_NONE

	table.setBorderSides(JCTblEnum.ALL, 0, JCTblEnum.BORDERSIDE_LEFT | JCTblEnum.BORDERSIDE_TOP | JCTblEnum.BORDERSIDE_BOTTOM);

Frame Border Attributes

The FrameShadowThickness property specifies the thickness of the frame shadows surrounding the cell and label areas. Its default value is 0 (no frame shadows).

Shadow colors are calculated using the table's background color.

Images

Image Format

Specifying an Image

The easiest way to specify an image stored in a file is to use the Java property converter to convert the filename string to the image data type that JCConverter() requires, as shown below:

     Image im = JCUtilConverter.toImage(this, "astronaut.gif");
     if (im != null) {
          JCString js = new JCString();
          js.add(im);
          table.setCell(3, 0, js);
}

Removing an Image

Image Layout

Text and Image Clipping

Clipping

Cell and Label Spanning

When you create a spanned range, the top-left cell in the range is extended over the entire range. The top-left cell is the source cell, and its value and attributes apply over the entire span, covering any values or attributes set for the other cells/labels in the range. Spanned ranges must begin at the top-left corner of the range. A span cannot contain both cells and labels. There must also be more than one cell/label in a spanned range; when a single-cell range is specified, it is removed from the list. The next figure shows an example of a table containing spanned ranges.

Spans is used to set a Vector of ranges of cells or labels. Each element of the Vector is an instance of a JCCellRange. A spanned range is a range of cells or labels that appear joined and can be treated as one cell. The top-left cell (specified by the start_row and start_column members) is the source cell for the spanned range. The cell/label value and attributes of the source cell are displayed in the spanned cell. Attributes for the spanned range must be set on the source cell.

Each item in a span list is an instance of a JCCellRange. A JCCellRange object defines the start and end columns/rows for the specified range.

The following example defines a cell that spans two columns:

     Vector spans = new Vector();
     JCCellRange r = new JCCellRange();
     r.reshape(0, 1, 0, 2);
     spans.addElement(r);
     table.setSpans(spans);

User Data

¹ Rows/columns that are only partially visible are also included in the value of these properties.

² All of the characters in a fixed-width font have the same width.

³ When width are height are set to zero, the row/column becomes hidden.

⁴ Users cannot interactively hide or reveal rows/columns.

⁵ The current cell never displays clipping arrows because it is an Text component.