Table Class

A Table control enables you to display entries in a table using rows and columns. As the Table class is a subclass of the Control class, it inherits all of the properties and methods defined in the Control and Window classes.

The table control also enables you to have many different sheets in the table, of which only one is visible at any time. The heading for each sheet is displayed in a selectable tab at the top of the control. When the user clicks on that tab, the corresponding sheet of the table is displayed (that is, both the click and the sheetChg events occur).

The number of rows and columns on a sheet is controlled by the rows and columns properties. Changing the value of the column or row property does not cause the table to be repainted. Table control subclasses do not reference mousePointer in a mouseDown event to determine if the mouse is in the resize position (that is, positioned over the dividing lines between fixed columns or rows).

Use the allowResize property to specify whether users can resize the rows and columns of a table. (The resizeColumn and resizeRow event methods are called when a resize operation has been performed using the mouse on a table column or row, respectively.)

The Table control class has the following behavior.

• Clicking on an enabled fixed row or column cell draws the cell in a slightly darker background color. When the mouse is released, the original background color is restored.

  This gives the user a visual indication that the cell was clicked.

• Clicking on a disabled cell generates table mouseDown and mouseUp events, but does not generate a click event after the mouse is released.

• Resizing a row or column generates table mouseDown, mouseUp, and resizeRow or resizeColumn events, but does not generate a click event after the mouse is released.

  Resizing a row or column does not resort the row or column.

• Moving a row or column generates table mouseDown, mouseUp, and queryRowMove or queryColumnMove events, but does not generate a click event after the mouse is released.

  Moving a row or column does not resort the row or column.

Table cells on a form defined as a Web page can contain pictures and labels only.

The table enables you to control the background color, text color, alignment, and picture displayed for each cell. Each cell can also be input-capable.

Although the table control can display a maximum of 63 sheets, the resulting size of the tabs prevents this limit being a reasonable option. Each sheet can have a maximum of 16,000 columns and 32,000 rows. These maximum limits cannot be achieved, however, as too much memory is required to be able to be run the application effectively.

The table can also be defined with fixed rows and columns. Fixed columns are usually the headings for each row and column. These rows and columns are always displayed, and do not scroll with the rest of the table.

Set the dropDown property to enable the table to fold up when focus is lost, showing only the current row.

Each sheet can be sorted by using the contents of one through six columns. Rows and columns on a sheet can be hidden.

By default, a table has one defined sheet. Use the sheets property to control the number of sheets in the table. The current sheet that is being accessed by logic is defined by the sheet property. The current sheet that is displayed is defined by the topSheet property.

The rows and columns properties control the number of rows and columns in each sheet. Rows can also be added to the table by using the addItem and addItemAt methods. If you add rows by using either of these methods, the text for each cell should be concatenated into one string, with the text of each cell separated by a tab character.

Use the text property to access the text for each cell. The current sheet, row, and column are then used to access the text in that cell. When setting the text property, the current cell in the current row is filled with the text that is passed. If the text contains tab characters, this character is assumed to be the end of the text for a cell, and the next cell is then filled with the remainder of the text, and so on. If all cells in the row are filled and there is more text, the remainder is ignored.

As table controls do not support a row height larger than the table, only the visible part of the row is displayed.

Move around the cells of a table by using the mouse, arrow keys, or Home, End, Page Up, or Page Down keys. Tables are scrolled by rows, not by pixels. When an input-capable cell has the focus, it may be necessary to also press the Alt key, as navigation keys may also have meaning to the text or combo boxes in these cells.

Press Ctrl+Home to move a table with an associated collection to the first entry in the collection. Conversely, press Ctrl+End to move the display to the last entry in the collection.

You can set the width of a column to a percentage of the client width of a table. For details, see the widthPercent property of the JadeTableColumn class. To control how any columns percentages set on the table sheet using the widthPercent property are interpreted, use the widthPercentStyle property of the JadeTableSheet class.

When writing your logic to handle Table controls, you can:

• Set object references on sheets, rows, columns, and cells by using the accessSheet, accessRow, accessColumn, and accessCell methods to set the respective accessedSheet, accessedRow, accessedColumn, and accessedCell properties.

The accessMode property provides multiple meanings for the alignment, backColor, comboIndex, foreColor, fontName, fontSize, fontBold, fontItalic, fontUnderline, fontStrikethru, inputType, maxLength, partialTextIndication, and wordWrap properties of Table controls.

• Search the itemObject property values of rows, columns, and cells for an object reference.

• Select or deselect an entire sheet, row, or column by using the selectMode property.

• Sort columns based on the type of cell data (that is, alphanumeric, numeric, date, time, or timestamp), by using the sortType property.

• Control automatic row and column sizing based on the text content of cells, by using the autoSize property.

  Text in table cells wraps only when the value of the autoSize property is set to AutoSize_Row (1).

• Control vertical or horizontal alignment within a cell, by using Table class constant values for the alignment property; for example, Alignment_Center_Bottom.

• Control tabbing within a table, by using the tabKey property.

• Specify a numeric input type allowing decimals and negative values, by using the decimals property and Table class constant values for the inputType property; for example, InputType_SignedNumeric.

• Handle user-created controls for input, by using the cellControl and userInputEnabled properties and the cellInputReady event method. Alternatively, you can use the Control class automaticCellControl property to control table cells (for example, when running in JADE thin client mode over a slow link).

• Optionally allow automatic dragging and dropping of a column or row, by using the allowDrag property.

• Provide the displayCollection method to invoke the displayRow event that automatically attaches a collection to the current sheet of a table and displays it.

  For details about dragging the scroll bar thumb of tables when an Array, Dictionary, or Set collection is attached to the table, see the displayCollection method.

• Retrieve the cell that corresponds to a position on the table, by using the positionLeft and positionTop methods.

• Control the optional display of the points of ellipsis symbol (…) on the end of the visible text when the column is not wide enough to show all the text, by using the partialTextIndication property.

• Use the foreColor property of a sheet to display the caption of a sheet in a table.

• Enable or disable all set inputType or cellControl properties, by using the userInputEnabled property.

• Control what automatic selections are made when the user clicks the table or uses the Shift key or the Ctrl key, by using the selectMode property.

• Specify whether the picture or text is truncated when there is insufficient room to display both in a cell, by using Table class constant values for the stretch property; for example, Stretch_Cell_Picture_First.

When a collection is attached to a table and the current row is scrolled so that it will be discarded (outside of the displayed virtual window over the collection), the queryRowColChg and rowColumnChg event methods are called. If the queryRowColChg event is rejected, the scroll action is discarded. (Note that the queryRowColChg event passes the current row and column values as parameters, because the actual current row number remains unchanged after scrolling.)

For an example and details about merging cells in a table, see the JadeTableCell class mergeCells property and getCellWidth method. For details about the support of mouse wheel requests to scroll up, down, or across a table control, see "Window Class", earlier in this document.

For an overview of directly accessing properties and methods in a table element (for example, a cell or a row) without using the accessMode property, see "Directly Accessing Table Elements". For a summary of the constants, properties, methods, and events defined in the Table class, see "Table Class Constants", "Table Properties", "Table Methods", and "Table Events", in the following subsections.