Gadget class. More...

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

Inheritance diagram for IliDataSource:

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 IlvBitmap *	getBitmap () 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 IliTablePropertyManager *	getEffectiveTablePropertyManager () const
	Returns the effective table property manager used by the data source. More...

IliTablePropertyManager *	getEffectiveTablePropertyManager ()
	Returns the effective table property manager used by the data source. More...

IliErrorReporter *	getErrorReporter () 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 IliTable *	getTable () const
	Returns the table of the data source. More...

IliTable *	getTable ()
	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 IliValue &	getValue (IlInt colno) const
	Returns the current value of one column. More...

const IliValue &	getValue (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 IlvSymbol *	CancelEditsSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	DeleteRowSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	EnterInsertModeSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	EnterModifiedStateSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	EnterRowSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	EnterUpdateModeSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	FetchRowSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	PrepareDeleteRowSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	PrepareInsertSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	PrepareUpdateSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	QuitInsertModeSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	QuitRowSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	QuitUpdateModeSymbol ()
	Returns the callback name which is called by the corresponding virtual member function. More...

static IlvSymbol *	ValidateRowSymbol ()
	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:

Name (inherited from the IlvGraphic class): this name allows any field gadget to retrieve the data source and connect to it (see the IliRepository class).
Table (see the getTable() and setTable() member functions).
Current row index: this designates either a valid row in the table or the insert row (just after the last valid row index in the table). Alternatively, it may be -1.
Row buffer (see the getValue() and setValue() member functions): the row buffer is an ordered collection of values that have the same schema as the data source table.
The set of field gadgets the data source manages (see the applyToFields() member function and the IliFieldItf class).
The state of the data source with regard to whether input has been modified (see the isInputModified() member function).

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:

An IliErrorList object
var errList = new IliErrorList
ds.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);
}
ds.addErrorSink(new IliObserver(OnError));

[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:

You may want to generate errors when user input violates some application defined constraints.
You may want to catch errors that are thrown by any lower-level piece of software when you call some higher-level function (for example, errors generated by the DBMS when you call the validate() method).
You may want to report errors to the user.

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

display	The display.
at	The location.
thickness	The border thickness.
palette	The 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

msg	The 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

msg	The 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

sink	The 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

interactive The 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

cb	The callback.
arg	The 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

f	The auto-row-locking permission.

void IliDataSource::enableAutoSelect ( IlBoolean autoSelect )

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

Parameters

autoSelect The auto-select mode flag.

void IliDataSource::enableInsert ( IlBoolean enable )

Specifies whether insertion is allowed.

Parameters

enable The 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

colno The 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

colname The 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

rowno The 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");
            dontValidateRow();
        }
    }
}

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

void MyValidateRowCallback(IlvGraphic* g, IlAny)
{
    IliDataSource* ds = (IliDataSource*)g;
    if (ds->getValue("Qty").asInteger() > 15) {
        ds->dontValidateRow();
        ds->addErrorMessage("Invalid quantity");
    }
}
...
IliDataSource* ds = ...;
ds->setCallback(IliDataSource::ValidateRowSymbol(),
                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

keepChanges The "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

keepChanges The "keepChanges" flag.

Returns: IlTrue if successful.

void IliDataSource::removeErrorSink ( IliErrorSink * sink )

Removes an error sink from this data source.

Parameters

sink	The 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

errorList The 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

reporter The 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

global The data source scope (IlTrue for global).

Reimplemented from IliDataGem.

void IliDataSource::setReadOnly ( IlBoolean only )

Specifies whether the data source is read-only.

Parameters

only	The read only flag.

virtual void IliDataSource::setTable	(	IliTable *	table,
		IlBoolean	owner = `IlTrue`
	)

virtual

Sets the table of the data source.

Parameters

table	The table.
owner	To 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

name	The 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

colno	The column position.
value	The 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

colname	The column name.
value	The 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

colno	The column position.
flag	The modified flag.

void IliDataSource::setValueModified	(	IliName	colname,
		IlBoolean	flag
	)

Changes the modified attribute of the value of one column.

Parameters

colname	The column name.
flag	The 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

flag	If `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

interactive The 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.

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Accessors

Data accessors

Method accessors

Errors

Callbacks

Constructor & Destructor Documentation

Member Function Documentation

Example