Accessors for class IliTableGadget

Properties

Methods

Callbacks

Description

The IliTableGadget class defines gadgets that can edit and display tables. The dataSourceName property lets you specify which table the table gadget will display. The end user will then be able to inspect and to modify the table's data through the table gadget. In addition, if the showInsertRow property is set to true, the user will also be able to append new rows at the end of existing rows.

Column Geometry

By default, the table gadget shows the columns in the same order and with the same width as they are defined in the underlying table object. Consequently, if you connect two table gadgets to the same data source, each time the user resizes a column in one table gadget, the same column is resized in the other. This is not necessarily desirable, especially if auto fit mode is enabled.
By setting the columnGeometryLocal property to true, you can have the table gadget itself manage columns visibility, widths, and ordering. In this way, it is possible to have more than one table gadget showing different views (in terms of columns) of the same data source.
Here is an example:
     var tgLeft = Application.MyPanel.LeftTG;
     tgLeft.dataSourceName = "EMP"; 
     tgLeft.columnGeometryLocal = true;
     tgLeft.ID.visible = false;

     var tgRight = Application.MyPanel.RightTG;
     tgRight.dataSourceName = "EMP"; 
     tgLeft.columnGeometryLocal = true;
     tgLeft.ID.visible = true;

     // now, the "ID" column is visible in one
     // table-gadget but not in the other.

Current Row

By default, a table gadget has the same current row as the data source to which it is connected. When you move to another row through the data source, the table gadget's current row changes accordingly and vice-versa. Also, if you start editing the current row through the data source, you see your changes in the table gadget even before the changes are validated, and vice-versa.
By setting the boundToDataSource property to false, you can have the table gadget manage its own notion of the current row, independently of its data source.

Selection

The selection of a table gadget designates the parts of the table that are highlighted. The selection should not be confused with the select method of the underlying table. It can be one of the following:
The selection table gadget property lets you manipulate the selection. For more information, see the description of the IliTableSelection class.
To provide shortcuts for manipulating the selection, the table gadget has some additional properties and methods that are handy in the most common situations:

Table Properties

The IliTableGadget can use table properties to configure certain graphical aspects. Currently, the following properties are supported:

Property Name  

Value  

background  
 Color name  
foreground  
 Color name  
font  
 Font name  
readOnly  
 1 or 0  
format  
 format name or specification  
mask  
 mask name or specification  


The properties can be attached to individual cells, whole rows, whole columns, or the table as a whole.
Note that contrary to other property-aware gadgets, the table gadget is not sensitive to the useTableProperties and tablePropertyManagerName properties of its data source.

Callbacks

There are many callbacks that you can use to customize a table gadget. Be aware that these callbacks are called in very specific contexts that are elaborated in the description for each callback.
Consequently, great care should be taken not to call directly or indirectly methods that would completely change the context in which the callback was called. For instance, you should not call the selectCell method from inside a FetchRow callback since this callback can be called asynchronously.
Many of these callbacks exist also on the IliDataSource class. If the table gadget is bound to its data source, it is the callbacks that are defined on the data source that are called and not those of the table gadget.
If, on the contrary, the table gadget is not bound to its data source, the callbacks that are defined on the table gadget will be called when the event originates from the table gadget and those defined on the data source will be called when the event originates from the data source.
The description for each callback below explains whether the callback depends in this way on the boundToDataSource property.

TypeNameDescriptionNotes
BooleanallowColumnMoveThis property is true if the end user can change the order of the columns.
BooleanallowColumnResizeThis property is true if the end user can change the size of the columns.
BooleanallowRowMoveThis property is true if the end user can change the order of the rows.
BooleanallowRowResizeThis property is true if the end user can change the size of the rows.
BooleanalwaysShowSelectionThis property is true if the selection of the table gadget is always highlighted even if the table gadget has lost the focus.
IliValueTableFittingModeautoFitContains the auto-fitting mode. This mode determines how the table gadget recalculates its column widths when the gadget itself is resized. The possible string values are:
  • IliFitNone

  • IliFitProportional

  • IliFitLast

BooleanautoFittingPullDownThe value of this property is assigned to the the autoFitting property of any table combo box contained in the table gadget. See the description of IliTableComboBox::autoFitting for more information. Initially, this property is false.
BooleanboundToDataSourceThis property is true if the table gadget is bound to its data source. In this situation, the current row of the table gadget is synchronized with the current row of the data source.
ColorcellBackgroundContains the default background color used to draw the cells. See the GetCellPalette callback for how to change the background on a cell by cell basis.
FontcellFontContains the default font used to draw the cells. See the GetCellPalette callback for how to change the font on a cell by cell basis.
ColorcellForegroundContains the default foreground color used to draw the cells. See the GetCellPalette callback for how to change the foreground on a cell by cell basis.
IliCellPaletteStructcellPaletteStructContains the description of the cell that is currently being drawn, along with other useful information. This property should be only used during the execution of the GetCellPalette table gadget callback.read-only
BooleancolumnGeometryLocalThis property is true if the table gadget manages column width, visibility, and ordering independently of the underlying table. Otherwise, column geometry is synchronized with the underlying table.
IntcolumnsCountContains the number of columns in the underlying table.read-only
BooleanconfirmDeletesThis property is true if the user is prompted for a confirmation before deleting a row.
IntcurrentColumnContains the index of the current column or -1 if there is no current column.read-only
IntcurrentRowContains the index of the current row or -1 if there is no current row.read-only
IliDataSourcedataSourceContains the data source object. This property cannot be written to if the dataSourceName property is not empty. In other words, the data source can be specified either literally through the dataSource property or by name through the dataSourceName property, but not both.
StringdataSourceNameContains the data source name.
BooleandeleteKeyThis property is true if the user can use the delete key to delete the current row.
IntdeletedRowContains the row position that is to be deleted.read-only
IntfetchedRowContains the row position that is fetched.read-only
IntfirstColumnContains the position of the first column shown. When the value of this property is changed, the table gadget is scrolled horizontally so that the first visible column (not counting any fixed columns) will become the one whose index is contained in this property.
IntfirstRowContains the position of the first row shown. When the value of this property is changed, the table gadget is scrolled vertically so that the first visible row will become the one whose index is contained in this property.
IntfixedColumnsContains the number of columns that do not scroll. These are the left-most columns.
IntheaderHeightContains the height, in pixels, of the column headers.
IliValueShowModehorizontalScrollContains the show mode of the horizontal scroll bar. The possible values are the following strings:
  • IliShowNever

  • IliShowAsNeeded

  • IliShowAlways

BooleaninputModifiedContains true if the table gadget's current row is being modified awaiting validation.read-only
IntmarkerWidthContains the width, in pixels, of the row markers.
BooleanmultiSelectionEnabledThis property is true if the multiselection is enabled.
BooleanreadOnlyThis property is true if the gadget is read only.
BooleanrefreshKeyThis property is true if the user can call the IliTable::select member function on the underlying table with the refresh key (F9).
IntrowHeightContains the height, in pixels, of the rows in the table gadget. Note that all rows have the same height.
BooleanrowSelectEnabledThis property is true if the row selection is enabled. If it is enabled, the user cannot select individual cells. Instead, when the cell is selected, the whole row containing the cell is selected.
IliTableSelectionselectionContains the description of the selection.
BooleanshowCellEditorThis property is true if the cell editor is shown in the selected cell when the cell is read only.
BooleanshowGridThis property is true if the grid is shown.
BooleanshowHeadersThis property is true if the headers are shown.
BooleanshowInsertRowThis property is true if the inserted row is shown. Note that if the table gadget is bound to its data source and this property is false, the data source's insertEnabled should also be false.
BooleanshowMarkersThis property is true if the markers are shown.
BooleansortEnabledThis property is true if the end user can sort rows by clicking on the column headers.
IliTabletableContains the underlying table of the table gadget. If the dataSource property is not null, the value of this property is the same as that of the data source. If the dataSource property is null, a table can be explicitly assigned to this property.
StringtablePropertyManagerNameContains the name of the table property manager being used or null if the default property manager is used.
BooleanuseReliefThis property is true if the table gadget is drawn with a relief border.
BooleanuseTablePropertiesContains true if the table gadget is sensitive to table properties. Initially, this property is false.
IliValueShowModeverticalScrollContains the show mode of the vertical scroll bar. The possible values are the following strings:
  • IliShowNever

  • IliShowAsNeeded

  • IliShowAlways

VoidaddError(String message)Forwards an application error message to all the error sinks that have been added with the addErrorSink function.
VoidaddErrorMessage(IliErrorMessage message)Forwards an application error message to all the error sinks that have been added with the addErrorSink function.
VoidaddErrorSink(Object sink)Adds an error sink to the table gadget. When an error occurs, it will be forwarded to this error sink.
The sink parameter can be one of the following:
  • An IliErrorList object 

         var errList = new IliErrorList
     tg.addErrorSink(errList);

  • An IliObserver object whose func property contains a Rogue Wave Views Script function having the following signature: fct(IliErrorMessage msg) 

         function OnError(errorMsg) {
        writeln(errorMsg.prettyMessage);
     }
     tg.addErrorSink(new IliObserver(OnError));
Voidcancel()Cancels any user input awaiting validation.
VoiddontDeleteRow()Called from the PrepareDeleteRow callback. This function stops the deletion of the row whose position is given by the deletedRow property. The addError method should be called to provide the user with a descriptive error message.
VoiddontValidateCell()Called from the ValidateCell callback. This function stops the validation of the current cell from proceeding. The addError method should be called to provide the user with a descriptive error message.
VoiddontValidateRow()Called from either the ValidateRow, PrepareUpdate or PrepareInsert callback. This function stops the row validation from proceeding. The addError method should be called to provide the user with a descriptive error message.
IliTableGadgetColumngetColumn(String colname)Returns the description of the column named colname. Note that the columns become properties of the table gadget so that the following are equivalent:
     tg.getColumn("NAME")
     tg.NAME
IliTableGadgetColumngetColumnAt(Int colno)Returns the description of the column positioned at colno.
BooleanisOnInsertRow()Returns true if the current row is the insert row.
CallbackremoveErrorSink(Object sink)Removes an error sink.
VoidreportErrors(IliErrorList list)Reports the errors that are in the error list.
BooleanselectAll()Attempts to select all rows and all columns and returns true if successful.
BooleanselectCell(Int rowno, Int colno)Attempts to select the cell positioned at row rowno and at column colno and returns true if successful.
BooleanselectColumn(Int colno)Attempts to select the column positioned at colno and returns true if successful.
BooleanselectNone()Attempts to deselect the current selection and returns true if successful.
BooleanselectRow(Int rowno)Attempts to select the row positioned at rowno and returns true if successful.
VoidusePictureAt(Int colno)Sets the editor used for the column positioned at colno to an IliDbPicture gadget. This is useful if the column has a String type and if the values in the column designate image files (those found in the Rogue Wave Views path).
VoiduseToggleAt(Int colno)Sets the editor used for the column positioned at colno to an IliDbToggle gadget. This is useful if the column has a Boolean type.
Booleanvalidate()Validates the current row. Returns true if successful. A dialog box displays an error message in case of failure.
BooleanvalidateSilently()Validates the current row. Returns true if successful. In case of failure, no error message is displayed.
CallbackCancelEditsThis callback is only available if boundToDataSource is false. Called just after the edits in the current row have been cancelled.
CallbackDeleteRowCalled just before a row in the underlying table is deleted. The index of the row that is to be deleted can be obtained by looking at the deletedRow property.
CallbackDoubleClickCalled when the user double-clicks on the table gadget.
CallbackEnterCellCalled just after a new cell is entered.
CallbackEnterInsertModeOnly available if boundToDataSource is false. Called just after the current row buffer becomes modified when the current row is the insert row.
CallbackEnterRowCalled just after a new row is entered.
CallbackEnterUpdateModeOnly available if boundToDataSource is false. Called just after the current row buffer becomes modified when the current row is not the insert row.
CallbackFetchRowCalled just after a new row has been retrieved from a remote database and cached in the underlying table. The index of the row that has just been fetched can be obtained by looking at the fetchedRow property.
Here is an example of a FetchRow callback:
     var counter = 0;
     function OnFetchRow(tg) {
        var column = tg.COUNTER.tableColumn;
        column.setInCache(tg.fetchedRow, 
                          ++counter);
     }
Note how it uses the setInCache method of class IliTableColumn to store a value in the local row cache of the table object.
CallbackGetCellPaletteCalled when the text and fill palettes of a cell are required, either to draw the cell or to configure the cell editor. The cell for which the palettes are required is described, along with other useful information, in the object obtained by looking at the cellPaletteStruct property.
CallbackPrepareDeleteRowThis callback is only available if boundToDataSource is false. Called when the user attempts to delete a row through this table gadget. The index of the row that is to be deleted can be obtained by looking at the deletedRow property.
The row deletion can be prevented by calling the dontDeleteRow method. In addition, the addErrorMessage member function may be called to describe the reason of the failure.
Here is an example of a PrepareDeleteRow callback:
     function OnPrepareDeleteRow(tg) {
        if (tg.deletedRow == 0) {
         tg.dontDeleteRow();
         tg.addError("Leaf node cannot be deleted.");
        }
     }
CallbackPrepareInsertOnly available if boundToDataSource is false. Called when an attempt is made to validate the current row when the current row is the insert row. This callback is called in addition to the ValidateRow callback. The row validation can be prevented by calling the dontValidateRow method. In this case, the addErrorMessage method should also be called to provide an error message to the user. Alternatively, it is possible to change some of the values in the current row before it is inserted in the underlying table.
CallbackPrepareUpdateOnly available if boundToDataSource is false. Called when an attempt is made to validate the current row when the current row is not the insert row. This callback is called in addition to the ValidateRow callback. The row validation can be prevented by calling the dontValidateRow method. In this case, the addErrorMessage method should also be called to provide an error message to the user. Alternatively, it is possible to change some of the values in the current row before it is updated in the underlying table.
CallbackQuitCellCalled just before the selection moves out of a cell.
CallbackQuitInsertModeThis callback is only available if boundToDataSource is false. Called just after the current row has been successfully validated when the current row is the insert row.
CallbackQuitRowCalled just before the selection moves out of a row.
CallbackQuitUpdateModeOnly available if boundToDataSource is false. Called just after the current row has been successfully validated when the current is not the insert row.
CallbackSelectionChangeCalled just after the selection has changed (whatever the change).
CallbackValidateCellCalled when an attempt is made to move the selection out of a cell. The cell validation can be prevented by calling the dontValidateCell method. In this case, the addErrorMessage method should also be called to provide an error message to the user.
CallbackValidateRowOnly available if boundToDataSource is false. Called when an attempt is made to validate the current row. The row validation can be prevented by calling the dontValidateRow method. In this case, the addErrorMessage method should also be called to provide an error message to the user. Alternatively, it is possible to change some of the values in the current row before it is transmitted to the underlying table. This callback is called when an existing row is being updated or when a new row is being inserted.
Here is an example of a ValidateRow callback:
     function OnValidateRow(tg) {
        var capacity = tg.CAPACITY.value;
        var volume = tg.VOLUME.value;
        if (volume > capacity) {
           tg.dontValidateRow();
           tg.addError("Volume must be less than Capacity");
        }
        else {
           tg.LASTMODIF.value = new Date();
        }
     }