Rogue Wave Views
Data Access Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Static Public Member Functions | Friends
IliDataSource Class Reference

Gadget class. More...

#include <ilviews/dataccess/gadgets/datasrc.h>

Inheritance diagram for IliDataSource:
IliDataGem IlvGadget IlvSimpleGraphic IlvStylable IlvGraphic IlvValueInterface IliMemoryDataSource IliSQLDataSource

Public Member Functions

 IliDataSource (IlvDisplay *display, const IlvPoint &at, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 The constructor initializes a data source. More...
 
void addErrorMessage (const IliErrorMessage &msg)
 Forwards an error message to all the error sinks. More...
 
void addErrorMessage (const char *msg)
 Forwards an application error message to all the error sinks. More...
 
void addErrorSink (IliErrorSink *sink)
 Adds an error sink. More...
 
IlBoolean applyQueryMode (IlBoolean interactive=IlFalse)
 Applies the query that the user specified while in query mode. More...
 
void applyToFields (IliDataSourceFieldCallback cb, IlAny arg)
 Calls the callback function for each field managed by the data source. More...
 
void cancel ()
 Cancels any user input awaiting validation. More...
 
void cancelQueryMode ()
 Cancels query mode by restoring the original data source table.
 
void clear ()
 Calls the IliTable::clearRows() member function on the table of the data source. More...
 
IlBoolean deleteCurrentRow ()
 Deletes the current row of the data source (as long as the current row is an actual row). More...
 
void dontDeleteRow ()
 Call this member function from the onPrepareDeleteRow() virtual member function, or from the corresponding callback to cancel the row deletion.
 
void dontValidateRow ()
 Call this member function from one of the onValidateRow(), onPrepareInsert(), or onPrepareUpdate() virtual member functions, or from one of their corresponding callbacks.
 
void enableAutoRowLocking (IlBoolean f)
 Specifies whether auto-row-locking mode is enabled for the data source. More...
 
void enableAutoSelect (IlBoolean autoSelect)
 Specifies whether auto-select mode is enabled for the data source. More...
 
void enableInsert (IlBoolean enable)
 Specifies whether insertion is allowed. More...
 
virtual IlvBitmapgetBitmap () const
 Returns the bitmap that is displayed during the design phase in Rogue Wave Views Data Access. More...
 
IlInt getColumnsCount () const
 Returns the number of columns in the table. More...
 
IlInt getCurrentRow () const
 Returns the position of the current row. More...
 
IlInt getDeletedRow () const
 Returns the position of the row that is currently being deleted if called from the onDeleteRow() member function, or returns the position of the row that is to be deleted if called from the onPrepareDeleteRow() member function (or from the corresponding callback). More...
 
const IliTablePropertyManagergetEffectiveTablePropertyManager () const
 Returns the effective table property manager used by the data source. More...
 
IliTablePropertyManagergetEffectiveTablePropertyManager ()
 Returns the effective table property manager used by the data source. More...
 
IliErrorReportergetErrorReporter () const
 Returns the error reporter that is used by the reportErrors() member functions. More...
 
IlInt getFetchedRow () const
 Returns the position of the row that is currently being fetched. More...
 
IlInt getRowsCount () const
 Returns the number of rows in the table. More...
 
const IliTablegetTable () const
 Returns the table of the data source. More...
 
IliTablegetTable ()
 Returns the table of the data source. More...
 
const char * getTablePropertyManagerName () const
 Returns the name of the table property manager used by the data source or 0 if the default table property manager is used. Initially, this property is 0. More...
 
const IliValuegetValue (IlInt colno) const
 Returns the current value of one column. More...
 
const IliValuegetValue (IliName colname) const
 Returns the current value of one column. More...
 
IlBoolean gotoFirst ()
 Changes the current row of the data source to the first row of the table after validating any pending user input. More...
 
IlBoolean gotoLast ()
 Changes the current row of the data source to the insert row, provided insertion is allowed, or to the last row if not. More...
 
IlBoolean gotoNext ()
 Changes the current row of the data source to the next row after validating any pending user input. More...
 
IlBoolean gotoPrevious ()
 Changes the current row of the data source to the previous row (as long as the current row is not the first row). More...
 
IlBoolean gotoRow (IlInt rowno)
 Changes the current row of the data source to a row. More...
 
IlBoolean isAutoRowLockingEnabled () const
 Returns IlTrue if the data source automatically calls refreshAndLockRow on the underlying table as soon as an attempt to modify an existing row is made. More...
 
IlBoolean isAutoSelectEnabled () const
 Returns IlTrue if auto-select mode is enabled for the data source. More...
 
IlBoolean isCurrentRowNull () const
 Returns IlTrue if all the columns of the current row have a null value. More...
 
IlBoolean isEditable () const
 Returns IlTrue if the data source is not read-only, and if it is currently positioned on a valid row or on the insert row. More...
 
IlBoolean isInputModified () const
 Returns IlTrue if the user has edited any of the fields managed by the data source. More...
 
IlBoolean isInQueryMode () const
 Returns IlTrue if the data source is currently in query mode. More...
 
IlBoolean isInsertEnabled () const
 Returns IlTrue if new rows can be inserted in the table through the data source. More...
 
IlBoolean isOnInsertRow () const
 Returns IlTrue if the current row is the insert row. More...
 
IlBoolean isQueryModeSupported () const
 Returns IlTrue if the query mode is supported. More...
 
IlBoolean isReadOnly () const
 Returns IlTrue if the data source is read-only. More...
 
IlBoolean isUsingTableProperties () const
 Returns IlTrue if the data source uses table properties. More...
 
virtual void onCancelEdits ()
 Called just after the current edits have been canceled. More...
 
virtual void onDeleteRow ()
 Called each time a row is about to be deleted from the data source table. More...
 
virtual void onEnterInsertMode ()
 Called when the data source enters insert mode. More...
 
virtual void onEnterModifiedState ()
 Called just after the data-source changes its state from "not-modified" to "modified". More...
 
virtual void onEnterRow ()
 Called whenever the data source enters a new row. More...
 
virtual void onEnterUpdateMode ()
 Called when the data source enters update mode. More...
 
virtual void onFetchRow ()
 Called when the data source table is a two-tier table, and each time a new row is fetched from the remote database and stored in the table cache. More...
 
virtual void onPrepareDeleteRow ()
 Called when the user attempts to delete a row through this data-source or when the deleteCurrentRow() member function is called. More...
 
virtual void onPrepareInsert ()
 Called just before a row is inserted into the data source table. More...
 
virtual void onPrepareUpdate ()
 Called just before a row is updated in the data source table. More...
 
virtual void onQuitInsertMode ()
 Called just after a row has been inserted in the data source table. More...
 
virtual void onQuitRow ()
 Called just before leaving a row. More...
 
virtual void onQuitUpdateMode ()
 Called just after a row has been updated in the data source table. More...
 
virtual void onValidateRow ()
 Called by the validate() member function before actually updating the data source table (for both update and insert rows). More...
 
IlBoolean refreshAndLockCurrentRow (IlBoolean keepChanges=IlFalse)
 Refreshes and lock current row. More...
 
IlBoolean refreshCurrentRow (IlBoolean keepChanges=IlFalse)
 Refreshes current row. More...
 
void removeErrorSink (IliErrorSink *sink)
 Removes an error sink from this data source. More...
 
void reportErrors (const IliErrorList &errorList) const
 Reports the errors that are contained in an error list. More...
 
IlBoolean select ()
 Calls the IliTable::select() member function on the table of the data source and then moves to the first row of the table. More...
 
void setErrorReporter (IliErrorReporter *reporter)
 Sets the error reporter. More...
 
virtual void setGlobalScope (IlBoolean)
 Specifies whether the scope of the name of the data gem is local to the container in which it is located or globally visible. More...
 
void setReadOnly (IlBoolean only)
 Specifies whether the data source is read-only. More...
 
virtual void setTable (IliTable *table, IlBoolean owner=IlTrue)
 Sets the table of the data source. More...
 
void setTablePropertyManagerName (const char *name)
 Sets the table property manager name. More...
 
IlBoolean setValue (IlInt colno, const IliValue &value)
 Sets the data source value of one column. More...
 
IlBoolean setValue (IliName colname, const IliValue &value)
 Sets the data source value of one column. More...
 
void setValueModified (IlInt colno, IlBoolean flag)
 Sets the modified attribute of a value of one column. More...
 
void setValueModified (IliName colname, IlBoolean flag)
 Changes the modified attribute of the value of one column. More...
 
IlBoolean startInsert ()
 Changes the current row of the data source to the insert row, provided insertion is allowed. More...
 
IlBoolean switchToQueryMode ()
 Switches to query mode. More...
 
void useTableProperties (IlBoolean flag)
 Enables/Disables use table properties. More...
 
IlBoolean validate (IlBoolean interactive=IlFalse)
 Validates the current row. More...
 
- Public Member Functions inherited from IliDataGem
IlBoolean hasGlobalScope () const
 Indicates the data source scope. More...
 
IlBoolean isSystemUsage () const
 Indicates the system usage flag. More...
 
virtual void usedBySystem (IlBoolean usage)
 Specifies if the object is a system object. More...
 

Static Public Member Functions

static IlvSymbolCancelEditsSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolDeleteRowSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolEnterInsertModeSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolEnterModifiedStateSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolEnterRowSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolEnterUpdateModeSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolFetchRowSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolPrepareDeleteRowSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolPrepareInsertSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolPrepareUpdateSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolQuitInsertModeSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolQuitRowSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolQuitUpdateModeSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 
static IlvSymbolValidateRowSymbol ()
 Returns the callback name which is called by the corresponding virtual member function. More...
 

Friends

class IliFieldItf
 

Additional Inherited Members

- Protected Member Functions inherited from IliDataGem
 IliDataGem (IlvDisplay *display, const IlvPoint &at, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 Initializes a new data gem. More...
 

Detailed Description

Gadget class.

Library: dbgadget

The IliDataSource class defines a gadget that holds an IliTable and that can manage a set of field gadgets located in one or more containers. Each of these field gadgets is connected to a column of the table. In addition, the data source acts like a cursor in the table, because at any point in time it is positioned on a particular row of the table. Member functions are provided that enable the data source to move to the next row, previous row, and so on. A data source is characterized by the following properties:

Each time the current row index of a data source is changed to a new value, the data source row buffer is updated with a copy of the designated table row. If the new current row does not designate a valid row in the table, the data source row buffer is updated with null values. The data source inputModified property is also cleared.

At this time, any fields that are connected to the data source are updated with a value from the row buffer. This value corresponds to the column which the field gadget is connected to. The user can then edit the values displayed in the fields or, alternatively, can call the setValue() member function. The data source inputModified property is set to IlTrue at this time. In addition, the data source calls either the onEnterInsertMode() or onEnterUpdateMode() virtual member functions, depending on whether the current row index points to the insert row or not. Any new values edited by the user in the field gadgets are copied to their corresponding position in the row buffer.

Later, the user can call the validate() member function. This will trigger some system-defined and some user-defined checks on the row buffer (see the onValidateRow(), onPrepareInsert(), and onPrepareUpdate() virtual member functions). If the checks succeed, either a new row is inserted into the table or the table row is updated from the data source row buffer (depending on whether the current row is the insert row or not). The inputmodified property of the data source is set to IlFalse.

As an alternative to the validate() method function, the user can call cancel(). In this case, the contents of the row buffer are dismissed, the row buffer is updated from the existing table row (or with null values if the current row does not designate a row in the table), and any field gadgets are updated with values from row buffer. The inputmodified property is set to IlFalse.

See also
IliErrorMessage, IliErrorReporter, IliErrorSink, IliRepository, IliValue, IliDataSourceFieldCallback.

Accessors

Accessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods IlvValueInterface::queryValue(), IlvValueInterface::queryValues(), IlvValueInterface::changeValue(), IlvValueInterface::changeValues(). This class inherits the accessors of its superclass IliDataGem and adds the following ones:

Data accessors

Name Type Equivalent methods
autoRowLockingEnabled Boolean isAutoRowLockingEnabled(), enableAutoRowLocking()
autoSelectEnabled Boolean isAutoSelectEnabled(), enableAutoSelect()
columnsCount Int getColumnsCount()
currentRow Int getCurrentRow(), gotoRow()
deletedRow Int getDeletedRow()
fetchedRow Int getFetchedRow()
inputModified Boolean isInputModified()
insertEnabled Boolean isInsertEnabled(), enableInsert()
readOnly Boolean isReadOnly(), setReadOnly()
rowsCount Int getRowsCount()
table IliTable getTable(), setTable()
useTableProperties Boolean isUsingTableProperties(), useTableProperties()
tablePropertyManagerName String getTablePropertyManagerName(), setTablePropertyManagerName()

Method accessors

Name Return type Equivalent methods
addError(String message) Void addErrorMessage(message)
addErrorMessage(IliErrorMessage message) Void addErrorMessage(message)
addErrorSink(Object sink) Void See [addErrorSink] below.
applyQueryMode() Boolean applyQueryMode(IlTrue)
applyQueryModeSilently() Boolean applyQueryMode(IlFalse)
cancel() Void cancel()
cancelQueryMode() Void cancelQueryMode()
clear() Void clear()
deleteCurrentRow() Boolean deleteCurrentRow()
dontDeleteRow() Void dontDeleteRow()
dontValidateRow() Void dontValidateRow()
getColumn(String colName) Object See [getColumn*] below.
getColumnAt(Int col) Object See [getColumn*] below.
gotoFirst() Boolean gotoFirst()
gotoLast() Boolean gotoLast()
gotoNext() Boolean gotoNext()
gotoPrevious() Boolean gotoPrevious()
gotoRow(Int row) Boolean gotoRow(row)
isCurrentRowNull() Boolean isCurrentRowNull()
isInQueryMode() Boolean isInQueryMode()
isOnInsertRow() Boolean isOnInsertRow()
isQueryModeSupported() Boolean isQueryModeSupported()
refreshCurrentRow(Boolean keepCurrentChanges) Boolean refreshCurrentRow(keepCurrentChanges)
refreshAndLockCurrentRow(Boolean keepCurrentChanges) Boolean refreshAndLockCurrentRow(keepCurrentChanges)
removeErrorSink(Object sink) Void See [addErrorSink] below.
reportErrors(IliErrorList errorList) Void reportErrors(errorList)
select() Boolean select()
startInsert() Boolean startInsert()
switchToQueryMode() Boolean switchToQueryMode()
validate() Boolean validate(IlTrue)
validateSilently() Boolean validate(IlFalse)

[addErrorSink] The sink parameter can be either:

[getColumn*] These methods return the description of a column identified by name or by index. Note that the columns become properties of the data source so that the following expressions are equivalent:

dataSource.getColumn("NAME")
dataSource.NAME
Note
The data source has a data source column for each table column of the managed table. These data source columns belong to class IliDataSourceColumn. They can be obtained by calling one of the getColumn() or getColumnAt() methods. They also become properties of the data source and can be directly accessed as such using the dot notation. Each data source column contains a value property that holds the row buffer's value for the corresponding table column. The following Rogue Wave Views Script example computes a total price and stores it in a data source's row buffer:
dataSource.gotoRow(0);
writeln(dataSource.inputModified); // prints "false"
var qty = dataSource.QTY.value;
var itemPrice = dataSource.ITEM_PRICE.value;
dataSource.TOTAL_PRICE.value = qty * itemPrice;
writeln(dataSource.inputModified); // prints "true"

Errors

There are many situations where you may want to manage errors in relation to a data source:

To generate errors, see the ValidateRow callback, the addError() method, and the addErrorMessage() method. Catching and reporting errors is done by standard Rogue Wave Views Data Access gadgets such as the IliDbNavigator or the IliTableGadget. For example, if you validate a data source by clicking on the Validate button in a DbNavigator, the DbNavigator gadget takes care of catching any errors and reporting them. The same is true if you edit the data through a table gadget. If you want to add a menu item that does some specific work with the data source, you need to use the addErrorSink(), removeErrorSink(), and reportErrors() methods if you want errors to be shown. As an example, assume you have a button in a panel and you need to code its callback so that it scans all rows in a data source and deletes rows having a negative balance. You want to catch any errors that may occur and display a dialog box showing these errors when you are finished. Here is how it can be done:

function RemoveSomeRows(btn) {
var ds = IliRepository.ACCOUNT_DS;
// install an error sink
var errors = new IliErrorList;
ds.addErrorSink(errors);
// do whatever needs to be done with the data-source
ds.gotoRow(0);
while (ds.currentRow < ds.rowsCount) {
if (ds.BALANCE.value < 0) {
ds.deleteCurrentRow();
}
}
// display errors if any
ds.removeErrorSink(errors);
ds.reportErrors(errors);
// we return true if there were no errors
return (errors.errorsCount == 0);
}

Callbacks

There are a number of callbacks that can be used to customize a data source. Be aware that these callbacks are called in very specific contexts that are explained 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, one should not call the gotoRow() method from inside a ValidateRow callback since it is assumed that the row validation is not yet finished at this stage. When the state of a data source can be changed in a particular way, the description of the callback mentions it. For instance, the ValidateRow callback may change values in the row buffer before the row is sent to the underlying table.

Name Notes
CancelEdits Called just after the edits in the current row have been cancelled.
DeleteRow Called 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.
EnterInsertMode Called just after the current row buffer becomes modified when the current row is the insert row.
EnterModifiedState Called just after the data source changes its state from "not-modified" to "modified". This typically happens when the end user starts modifying a field connected to the data source or when the setValue() member function is called.
This callback can be used to check that it is possible to enter the modified state at the present time. If not, it calls the cancel() method.
Note that it would not be possible to use the EnterUpdateMode or EnterInsertMode callbacks for this purpose since they are called before the state of the data source changes (and hence calling cancel() would not have any effect in this case).
EnterRow Called just after a new row is entered.
EnterUpdateMode Called just after the current row buffer becomes modified when the current row is not the insert row.
FetchRow Called 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. See [FetchRow] below.
PrepareDeleteRow Called when the user attempts to delete a row through the data source. 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() method may be called to describe the reason for the failure. See [PrepareDeleteRow] below.
PrepareInsert 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 inserted in the underlying table.
PrepareUpdate 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.
QuitInsertMode Called just after the current row has been successfully validated when the current row is the insert row.
QuitRow Called just before the selection moves out of a row.
QuitUpdateMode Called just after the current row has been successfully validated when the current row is not the insert row.
ValidateRow 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. See [ValidateRow] below.

[FetchRow] Here is an example of a FetchRow callback:

var counter = 0;
function OnFetchRow(ds) {
var column = ds.COUNTER.tableColumn;
column.setInCache(ds.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.

[PrepareDeleteRow] Here is an example of a PrepareDeleteRow callback:

function OnPrepareDeleteRow(ds) {
if (ds.deletedRow == 0) {
ds.dontDeleteRow();
ds.addError("Leaf node cannot be deleted.");
}
}

[ValidateRow] Here is an example of a ValidateRow callback:

function OnValidateRow(ds) {
var capacity = ds.CAPACITY.value;
var volume = ds.VOLUME.value;
if (volume > capacity) {
ds.dontValidateRow();
ds.addError("Volume must be less than Capacity");
}
else {
ds.LASTMODIF.value = new Date();
}
}

Constructor & Destructor Documentation

IliDataSource::IliDataSource ( IlvDisplay display,
const IlvPoint at,
IlUShort  thickness = IlvDefaultGadgetThickness,
IlvPalette palette = 0 
)

The constructor initializes a data source.

Parameters
displayThe display.
atThe location.
thicknessThe border thickness.
paletteThe palette.

Member Function Documentation

void IliDataSource::addErrorMessage ( const IliErrorMessage msg)

Forwards an error message to all the error sinks.

This member function may be called by one of the onValidateRow(), onPrepareInsert() or onPrepareUpdate() virtual member functions, or by the corresponding callbacks.

Parameters
msgThe message.
void IliDataSource::addErrorMessage ( const char *  msg)

Forwards an application error message to all the error sinks.

This member function may be called by one of the onValidateRow(), onPrepareInsert(), or onPrepareUpdate() virtual member functions, or by the corresponding callbacks.

Parameters
msgThe message.
void IliDataSource::addErrorSink ( IliErrorSink sink)

Adds an error sink.

All errors that occur on the data source table, and all errors that are thrown by one of the addErrorMessage() member functions, will be forwarded to this error sink. Note that the data source will not delete the error sink at destruction time, so the same error sink may be safely shared among many data sources.

Parameters
sinkThe error sink.
IlBoolean IliDataSource::applyQueryMode ( IlBoolean  interactive = IlFalse)

Applies the query that the user specified while in query mode.

The original data source table is restored and its select() member function is called. If the interactive parameter is IlTrue, any errors that occur will be reported to the user by calling the reportErrors() member function.

Parameters
interactiveThe interactive flag.
Returns
IlTrue if successful.
void IliDataSource::applyToFields ( IliDataSourceFieldCallback  cb,
IlAny  arg 
)

Calls the callback function for each field managed by the data source.

Repeatedly calls the callback function for each field managed by the data source using in the following:

callback(dataSource, field, colno, arg);

The callback takes as its parameters the data source itself, the field, the position of the column to which the field is connected, and the arg parameter. Some fields, such as table gadgets, are not connected to a particular column. In this case, the colno parameter will be -1.

Parameters
cbThe callback.
argThe user data.
See also
IliDataSourceFieldCallback.
void IliDataSource::cancel ( )

Cancels any user input awaiting validation.

The input-modified property of the data source is cleared. This member function calls the onCancelEdits() virtual member function.

static IlvSymbol* IliDataSource::CancelEditsSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
void IliDataSource::clear ( )

Calls the IliTable::clearRows() member function on the table of the data source.

If the table is a one-tier table, this deletes all rows. If the table is a two-tier table, the local row cache of the table is cleared. Any pending user input is canceled by this member function.

IlBoolean IliDataSource::deleteCurrentRow ( )

Deletes the current row of the data source (as long as the current row is an actual row).

Returns
IlTrue if successful.
static IlvSymbol* IliDataSource::DeleteRowSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
void IliDataSource::enableAutoRowLocking ( IlBoolean  f)

Specifies whether auto-row-locking mode is enabled for the data source.

Parameters
fThe auto-row-locking permission.
void IliDataSource::enableAutoSelect ( IlBoolean  autoSelect)

Specifies whether auto-select mode is enabled for the data source.

Parameters
autoSelectThe auto-select mode flag.
void IliDataSource::enableInsert ( IlBoolean  enable)

Specifies whether insertion is allowed.

Parameters
enableThe insertion flag.
static IlvSymbol* IliDataSource::EnterInsertModeSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::EnterModifiedStateSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::EnterRowSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::EnterUpdateModeSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::FetchRowSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
virtual IlvBitmap* IliDataSource::getBitmap ( ) const
virtual

Returns the bitmap that is displayed during the design phase in Rogue Wave Views Data Access.

Returns
The bitmap.

Reimplemented from IliDataGem.

Reimplemented in IliMemoryDataSource, and IliSQLDataSource.

IlInt IliDataSource::getColumnsCount ( ) const

Returns the number of columns in the table.

Returns
The number of columns.
IlInt IliDataSource::getCurrentRow ( ) const

Returns the position of the current row.

Returns
-1 if the data source is not positioned on a row or a value equal to getRowsCount() if the data source is positioned on the insert row.
IlInt IliDataSource::getDeletedRow ( ) const

Returns the position of the row that is currently being deleted if called from the onDeleteRow() member function, or returns the position of the row that is to be deleted if called from the onPrepareDeleteRow() member function (or from the corresponding callback).

Returns
The row position.
const IliTablePropertyManager* IliDataSource::getEffectiveTablePropertyManager ( ) const

Returns the effective table property manager used by the data source.

It is obtained as follows:

  • If the useTableProperties property is IlFalse, this member function returns 0.
  • Otherwise, if the tablePropertyManagerName property is not 0, the table property manager with that name is returned.
  • Otherwise, the default table property manager is returned.
Returns
The table property manager.
IliTablePropertyManager* IliDataSource::getEffectiveTablePropertyManager ( )

Returns the effective table property manager used by the data source.

Returns
The table property manager.
IliErrorReporter* IliDataSource::getErrorReporter ( ) const

Returns the error reporter that is used by the reportErrors() member functions.

When this property is 0 a default error reporter is used.

Initially this property is 0.

Returns
The error reporter.
IlInt IliDataSource::getFetchedRow ( ) const

Returns the position of the row that is currently being fetched.

This member function may be called from the onFetchRow() member function or from the corresponding callback.

Returns
The row position.
IlInt IliDataSource::getRowsCount ( ) const

Returns the number of rows in the table.

Returns
The number of rows.
const IliTable* IliDataSource::getTable ( ) const

Returns the table of the data source.

Returns
The table.
IliTable* IliDataSource::getTable ( )

Returns the table of the data source.

Returns
The table.
const char* IliDataSource::getTablePropertyManagerName ( ) const

Returns the name of the table property manager used by the data source or 0 if the default table property manager is used. Initially, this property is 0.

Returns
The name of the table property manager.
const IliValue& IliDataSource::getValue ( IlInt  colno) const

Returns the current value of one column.

Note that this is the data source value for the column, as opposed to the underlying table value.

Parameters
colnoThe column position.
Returns
The value.
const IliValue& IliDataSource::getValue ( IliName  colname) const

Returns the current value of one column.

Note that this is the data source value for the column, as opposed to the underlying table value.

Parameters
colnameThe column name.
Returns
The value.
IlBoolean IliDataSource::gotoFirst ( )

Changes the current row of the data source to the first row of the table after validating any pending user input.

Returns
IlTrue if successful.
IlBoolean IliDataSource::gotoLast ( )

Changes the current row of the data source to the insert row, provided insertion is allowed, or to the last row if not.

Any pending user input is first validated by this member function.

Returns
IlTrue if successful.
IlBoolean IliDataSource::gotoNext ( )

Changes the current row of the data source to the next row after validating any pending user input.

If the current row is the last row of the table and if insertion is allowed, the current row changes to the insert row.

Returns
IlTrue if successful.
IlBoolean IliDataSource::gotoPrevious ( )

Changes the current row of the data source to the previous row (as long as the current row is not the first row).

Any pending user input is first validated by this member function.

Returns
IlTrue if successful.
IlBoolean IliDataSource::gotoRow ( IlInt  rowno)

Changes the current row of the data source to a row.

Any pending user input is first validated by this member function.

Parameters
rownoThe row position. If rowno equals -1, the data source will not be positioned on any row. If rowno equals getRowsCount(), the current row will change to the insert row.
Returns
IlTrue if successful.
IlBoolean IliDataSource::isAutoRowLockingEnabled ( ) const

Returns IlTrue if the data source automatically calls refreshAndLockRow on the underlying table as soon as an attempt to modify an existing row is made.

This is useful when using IliSQLTable objects in order to implement the "pessimistic concurrency control policy". For more information, see the description of the IliSQLTable::getConcurrencyControl() member function. Initially, this property is set to IlFalse.

Returns
The auto row lock permission.
IlBoolean IliDataSource::isAutoSelectEnabled ( ) const

Returns IlTrue if auto-select mode is enabled for the data source.

When auto-select mode is enabled, the data source automatically calls the select() member function if an event occurs. The table of a data source may have parameters already defined. Some of these parameters may have been mapped onto other data sources. Therefore, we can say that a data source depends on another data source through its table parameters. Then, provided auto-select mode is enabled, the data source will call the select() member function whenever one of the data sources on which it depends undergoes a current row change. Initially, this property is set to IlFalse.

Returns
The auto-select mode flag.
IlBoolean IliDataSource::isCurrentRowNull ( ) const

Returns IlTrue if all the columns of the current row have a null value.

Returns
IlTrue if the current row is null.
IlBoolean IliDataSource::isEditable ( ) const

Returns IlTrue if the data source is not read-only, and if it is currently positioned on a valid row or on the insert row.

Returns
The editable flag.
IlBoolean IliDataSource::isInputModified ( ) const

Returns IlTrue if the user has edited any of the fields managed by the data source.

Returns
IlTrue if an editing has been done.
IlBoolean IliDataSource::isInQueryMode ( ) const

Returns IlTrue if the data source is currently in query mode.

Returns
The query mode state.
IlBoolean IliDataSource::isInsertEnabled ( ) const

Returns IlTrue if new rows can be inserted in the table through the data source.

Initially, this property is set to IlTrue.

Returns
The insert permission.
IlBoolean IliDataSource::isOnInsertRow ( ) const

Returns IlTrue if the current row is the insert row.

Returns
IlTrue if the data source is positioned on the insert row.
IlBoolean IliDataSource::isQueryModeSupported ( ) const

Returns IlTrue if the query mode is supported.

Returns
The query mode support flag.
IlBoolean IliDataSource::isReadOnly ( ) const

Returns IlTrue if the data source is read-only.

If the data source is read-only, the end-user cannot modify the table via the fields managed by the data source. Initially, this property is set to IlFalse.

Returns
The read-only flag.
IlBoolean IliDataSource::isUsingTableProperties ( ) const

Returns IlTrue if the data source uses table properties.

Initially, this property is IlTrue.

Returns
The table properties using flag.
virtual void IliDataSource::onCancelEdits ( )
virtual

Called just after the current edits have been canceled.

The default implementation of this virtual member function calls the CancelEdits callback.

virtual void IliDataSource::onDeleteRow ( )
virtual

Called each time a row is about to be deleted from the data source table.

The index of the row can be obtained by the getDeleteRow() member function. The default implementation of this virtual member function is to call the DeleteRow callback. The dontDeleteRow() member function can be used to cancel the row deletion.

virtual void IliDataSource::onEnterInsertMode ( )
virtual

Called when the data source enters insert mode.

The default implementation of this virtual member function calls the EnterInsertMode callback.

virtual void IliDataSource::onEnterModifiedState ( )
virtual

Called just after the data-source changes its state from "not-modified" to "modified".

This typically happens when the end user starts modifying a field connected to the data-source or when the setValue() member function is called. This virtual member function can be overridden to do the following : check that it is possible to enter the modified state at this time and, if not, then call the cancel() member function.

The default implementation of this virtual member function calls the EnterModifiedState callback.

Note
It is not possible to use the onEnterUpdateMode() or onEnterInsertMode() virtual member functions for this purpose since they are called before the state of the data-source changes (and hence calling cancel would not have any effect in this case).
virtual void IliDataSource::onEnterRow ( )
virtual

Called whenever the data source enters a new row.

The default implementation of this virtual member function calls the EnterRow callback.

virtual void IliDataSource::onEnterUpdateMode ( )
virtual

Called when the data source enters update mode.

The default implementation of this virtual member function calls the EnterUpdateMode callback.

virtual void IliDataSource::onFetchRow ( )
virtual

Called when the data source table is a two-tier table, and each time a new row is fetched from the remote database and stored in the table cache.

The index of the row that has been fetched can be obtained by the getFetchedRow() member function. The default implementation of this virtual member function calls the FetchRow callback.

virtual void IliDataSource::onPrepareDeleteRow ( )
virtual

Called when the user attempts to delete a row through this data-source or when the deleteCurrentRow() member function is called.

The index of the row which is to be deleted can be obtained by calling the getDeletedRow() member function. This virtual member function can be overridden to do the following:

  • Check any application defined constraints. If the constraints are not satisfied, the dontDeleteRow() should be called. In this case, deleteCurrentRow() will not delete the row. Instead, it will return a value of IlFalse.
  • In addition, the addErrorMessage() member function can be called to describe the reason of the failure.

The default implementation of this virtual member function calls the PrepareDeleteRow callback.

virtual void IliDataSource::onPrepareInsert ( )
virtual

Called just before a row is inserted into the data source table.

This virtual member function may check that the row is correct, and it may also alter the row prior to inserting the table. In addition, it may decide that the row is invalid, and reject the table insert by calling the dontValidateRow() member function. In this case, it may call the addErrorMessage() member function to provide the user with an error message. The default implementation of this virtual member function calls the PrepareInsert callback.

virtual void IliDataSource::onPrepareUpdate ( )
virtual

Called just before a row is updated in the data source table.

This virtual member function may check that the row is correct and it may also alter the row prior to updating the table. In addition, it may decide that the row is invalid and reject the table update, by calling the dontValidateRow() member function. In this case, it may call the addErrorMessage() member function to provide the user with an error message. The default implementation of this virtual member function calls the PrepareUpdate callback.

virtual void IliDataSource::onQuitInsertMode ( )
virtual

Called just after a row has been inserted in the data source table.

The default implementation of this virtual member function calls the QuitInsertMode callback.

virtual void IliDataSource::onQuitRow ( )
virtual

Called just before leaving a row.

The default implementation of this virtual member function calls the QuitRow callback.

virtual void IliDataSource::onQuitUpdateMode ( )
virtual

Called just after a row has been updated in the data source table.

The default implementation of this virtual member function calls the QuitUpdateMode callback.

virtual void IliDataSource::onValidateRow ( )
virtual

Called by the validate() member function before actually updating the data source table (for both update and insert rows).

This virtual member function can be overridden to do the following:

  • Check any application defined constraints. If the constraints are not satisfied, the dontValidateRow() member function should be called. In this case validate() will not update the table. Instead it will return a value of IlFalse and the data source will remain in the input-modified state.
  • In addition, the addErrorMessage() member function may be called to describe the reason for the failure.
  • Modify the data source values before the actual update of the table takes place.

The default implementation of this virtual member function calls the ValidateRow callback. For example, if you subclass the IliDataSource class, you can override the onValidateRow() virtual member function with the following:

class MyDataSource
: public IliDataSource {
...
virtual void onValidateRow() {
if (getValue("Qty") > 15) {
addErrorMessage("Invalid quantity");
}
}
}

or, alternatively, if you do not subclass the IliDataSource class, you may use a callback:

void MyValidateRowCallback(IlvGraphic* g, IlAny)
{
if (ds->getValue("Qty").asInteger() > 15) {
ds->addErrorMessage("Invalid quantity");
}
}
...
IliDataSource* ds = ...;
MyValidateRowCallback);
static IlvSymbol* IliDataSource::PrepareDeleteRowSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::PrepareInsertSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::PrepareUpdateSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::QuitInsertModeSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::QuitRowSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
static IlvSymbol* IliDataSource::QuitUpdateModeSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.
IlBoolean IliDataSource::refreshAndLockCurrentRow ( IlBoolean  keepChanges = IlFalse)

Refreshes and lock current row.

This member function does the same thing as the refreshCurrentRow() member function. In addition, if the remote database supports it, the remote row that corresponds to the current row is locked so that other users cannot modify or delete it as long as the lock is held. See the description of the IliTable::refreshAndLockRow() member function and the IliSQLTable class for more information on row locking.

Parameters
keepChangesThe "keepChanges" flag.
Returns
IlTrue if successful.
IlBoolean IliDataSource::refreshCurrentRow ( IlBoolean  keepChanges = IlFalse)

Refreshes current row.

If the underlying table is a two-tier table, this member function re-reads the current row values from the remote database. If the optional keepChanges parameter is IlTrue, any columns of the data source that contain changes awaiting validation will keep these changes pending. Only unchanged columns will be updated. If keepChanges is IlFalse, all columns are updated without regard to the "modified" state. With a one-tier table, this member function does nothing.

Parameters
keepChangesThe "keepChanges" flag.
Returns
IlTrue if successful.
void IliDataSource::removeErrorSink ( IliErrorSink sink)

Removes an error sink from this data source.

Parameters
sinkThe error sink.
void IliDataSource::reportErrors ( const IliErrorList errorList) const

Reports the errors that are contained in an error list.

This member function makes use of the error reporter returned by getErrorReporter if any, otherwise it uses a default error reporter.

Example

Here is an example that shows how errors can be trapped:

IliDataSource* ds = ...;
IliErrorList errors;
ds->addErrorSink(&errors);
ds->setValue("NAME", "Smith");
if (!ds->validate()) {
IlvPrint("First error: %s", errors.getErrorAt(0).getMessage());
...
}
ds->removeErrorSink(&errors);
Parameters
errorListThe error list.
IlBoolean IliDataSource::select ( )

Calls the IliTable::select() member function on the table of the data source and then moves to the first row of the table.

Any pending user input is canceled by this member function.

Returns
IlTrue if successful.
void IliDataSource::setErrorReporter ( IliErrorReporter reporter)

Sets the error reporter.

Note that the data source will not delete the error reporter at destruction time, so the same error reporter may be safely shared among many data sources.

Parameters
reporterThe error reporter.
virtual void IliDataSource::setGlobalScope ( IlBoolean  global)
virtual

Specifies whether the scope of the name of the data gem is local to the container in which it is located or globally visible.

Parameters
globalThe data source scope (IlTrue for global).

Reimplemented from IliDataGem.

void IliDataSource::setReadOnly ( IlBoolean  only)

Specifies whether the data source is read-only.

Parameters
onlyThe read only flag.
virtual void IliDataSource::setTable ( IliTable table,
IlBoolean  owner = IlTrue 
)
virtual

Sets the table of the data source.

Parameters
tableThe table.
ownerTo specify whether the data source becomes the owner of the table if IlTrue.
void IliDataSource::setTablePropertyManagerName ( const char *  name)

Sets the table property manager name.

Parameters
nameThe table property manager name. If 0 or an empty string, the default table property manager will be used.
IlBoolean IliDataSource::setValue ( IlInt  colno,
const IliValue value 
)

Sets the data source value of one column.

Consequently, all fields connected to the column are updated with the new value without the underlying table being affected. A side effect of calling this member function is that the data source input is modified.

Parameters
colnoThe column position.
valueThe value.
Returns
IlTrue if successful.
IlBoolean IliDataSource::setValue ( IliName  colname,
const IliValue value 
)

Sets the data source value of one column.

Consequently, all fields connected to the column are updated with the new value without the underlying table being affected. A side effect of calling this member function is that the data source input is modified.

Parameters
colnameThe column name.
valueThe value.
Returns
IlTrue if successful.
void IliDataSource::setValueModified ( IlInt  colno,
IlBoolean  flag 
)

Sets the modified attribute of a value of one column.

Normally, the value of a column is considered unmodified when it is set by the data source (such as when an EnterRow or CancelEdits event occurs). Then it may become modified if the user edits this value or if it is changed by the setValue() member function. With the setValueModified() member function, it is possible to fool the data source and let it believe that that a column value has not been modified.

Parameters
colnoThe column position.
flagThe modified flag.
void IliDataSource::setValueModified ( IliName  colname,
IlBoolean  flag 
)

Changes the modified attribute of the value of one column.

Parameters
colnameThe column name.
flagThe modified flag.
IlBoolean IliDataSource::startInsert ( )

Changes the current row of the data source to the insert row, provided insertion is allowed.

Any pending user input is first validated by this member function.

Returns
IlTrue if successful.
IlBoolean IliDataSource::switchToQueryMode ( )

Switches to query mode.

If query mode is supported, this member function changes the data source table to a special memory table dedicated to contain query conditions.

Returns
IlTrue if successful.
void IliDataSource::useTableProperties ( IlBoolean  flag)

Enables/Disables use table properties.

Parameters
flagIf IlTrue, the data source will use table properties.
IlBoolean IliDataSource::validate ( IlBoolean  interactive = IlFalse)

Validates the current row.

Validation is carried out in the following way:

  • If the row buffer of the data source is unmodified, validation succeeds immediately.
  • Otherwise, system-defined constraints are checked on the current row buffer. If these constraints are not satisfied, validation fails.
  • The onValidateRow virtual method is then called. It checks any application-defined constraints and if these are not satisfied, it calls the dontValidateRow() member function. In this case, validation fails.
  • Either the onPrepareInsert() or onPrepareUpdate() virtual member function is called (depending on whether the current row is the insert row or not).
  • A new row is then inserted into the underlying table or an existing row is updated in the underlying table (depending on whether the current row is the insert row or not). If successful, either the onQuitInsertMode or onQuitUpdateMode() virtual member function is called and IlTrue is returned.

If successful, the row buffer of the data source becomes unmodified. If the interactive parameter is IlTrue, any errors that may occur are automatically reported to the user by calling the reportErrors() member function. If the interactive parameter is IlFalse, errors are not reported.

Parameters
interactiveThe interactive flag.
Returns
IlTrue if successful.
static IlvSymbol* IliDataSource::ValidateRowSymbol ( )
static

Returns the callback name which is called by the corresponding virtual member function.

Returns
The callback name.

© Copyright 2016, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.