Rogue Wave Views Data Access Package API Reference Guide |
Rogue Wave Views Documentation Home |
Gadget class. More...
#include <ilviews/dataccess/gadgets/datasrc.h>
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... | |
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:
IlvGraphic
class): this name allows any field gadget to retrieve the data source and connect to it (see the IliRepository
class). getTable()
and setTable()
member functions). -1
. getValue()
and setValue()
member functions): the row buffer is an ordered collection of values that have the same schema as the data source table. applyToFields()
member function and the IliFieldItf
class). 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
.
IliErrorMessage
, IliErrorReporter
, IliErrorSink
, IliRepository
, IliValue
, IliDataSourceFieldCallback
.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:
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() |
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:
IliErrorList
object IliObserver
object whose func property contains a Rogue Wave Views Script function having the following signature: fct(IliErrorMessage msg)
[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:
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: There are many situations where you may want to manage errors in relation to a data source:
validate()
method). 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:
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:
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:
[ValidateRow] Here is an example of a ValidateRow callback:
IliDataSource::IliDataSource | ( | IlvDisplay * | display, |
const IlvPoint & | at, | ||
IlUShort | thickness = IlvDefaultGadgetThickness , |
||
IlvPalette * | palette = 0 |
||
) |
The constructor initializes a data source.
display | The display. |
at | The location. |
thickness | The border thickness. |
palette | The palette. |
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.
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.
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.
sink | The error sink. |
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.
interactive | The interactive flag. |
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:
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
.
cb | The callback. |
arg | The user data. |
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 |
Returns the callback name which is called by the corresponding virtual member function.
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).
IlTrue
if successful.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
void IliDataSource::enableAutoRowLocking | ( | IlBoolean | f | ) |
Specifies whether auto-row-locking mode is enabled for the data source.
f | The auto-row-locking permission. |
void IliDataSource::enableAutoSelect | ( | IlBoolean | autoSelect | ) |
Specifies whether auto-select mode is enabled for the data source.
autoSelect | The auto-select mode flag. |
void IliDataSource::enableInsert | ( | IlBoolean | enable | ) |
Specifies whether insertion is allowed.
enable | The insertion flag. |
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
virtual |
Returns the bitmap that is displayed during the design phase in Rogue Wave Views Data Access.
Reimplemented from IliDataGem.
Reimplemented in IliMemoryDataSource, and IliSQLDataSource.
IlInt IliDataSource::getColumnsCount | ( | ) | const |
Returns the number of columns in the table.
IlInt IliDataSource::getCurrentRow | ( | ) | const |
Returns the position of the current row.
-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).
const IliTablePropertyManager* IliDataSource::getEffectiveTablePropertyManager | ( | ) | const |
Returns the effective table property manager used by the data source.
It is obtained as follows:
useTableProperties
property is IlFalse
, this member function returns 0
. tablePropertyManagerName
property is not 0
, the table property manager with that name is returned. IliTablePropertyManager* IliDataSource::getEffectiveTablePropertyManager | ( | ) |
Returns the effective table property manager used by the data source.
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
.
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.
IlInt IliDataSource::getRowsCount | ( | ) | const |
Returns the number of rows in the table.
const IliTable* IliDataSource::getTable | ( | ) | const |
Returns the table of the data source.
IliTable* IliDataSource::getTable | ( | ) |
Returns the table of the data source.
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 current value of one column.
Note that this is the data source value for the column, as opposed to the underlying table value.
colno | The column position. |
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.
colname | The column name. |
IlBoolean IliDataSource::gotoFirst | ( | ) |
Changes the current row of the data source to the first row of the table after validating any pending user input.
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.
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.
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.
IlTrue
if successful. Changes the current row of the data source to a row.
Any pending user input is first validated by this member function.
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. |
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
.
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
.
IlBoolean IliDataSource::isCurrentRowNull | ( | ) | const |
Returns IlTrue
if all the columns of the current row have a null
value.
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.
IlBoolean IliDataSource::isInputModified | ( | ) | const |
Returns IlTrue
if the user has edited any of the fields managed by the data source.
IlTrue
if an editing has been done. IlBoolean IliDataSource::isInQueryMode | ( | ) | const |
Returns IlTrue
if the data source is currently in query mode.
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
.
IlBoolean IliDataSource::isOnInsertRow | ( | ) | const |
Returns IlTrue
if the current row is the insert row.
IlTrue
if the data source is positioned on the insert row. IlBoolean IliDataSource::isQueryModeSupported | ( | ) | const |
Returns IlTrue
if the query mode is supported.
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
.
IlBoolean IliDataSource::isUsingTableProperties | ( | ) | const |
Returns IlTrue
if the data source uses table properties.
Initially, this property is IlTrue
.
|
virtual |
Called just after the current edits have been canceled.
The default implementation of this virtual member function calls the CancelEdits
callback.
|
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 |
Called when the data source enters insert mode.
The default implementation of this virtual member function calls the EnterInsertMode
callback.
|
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.
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 |
Called whenever the data source enters a new row.
The default implementation of this virtual member function calls the EnterRow
callback.
|
virtual |
Called when the data source enters update mode.
The default implementation of this virtual member function calls the EnterUpdateMode
callback.
|
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 |
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:
dontDeleteRow()
should be called. In this case, deleteCurrentRow()
will not delete the row. Instead, it will return a value of IlFalse
. 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 |
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 |
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 |
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 |
Called just before leaving a row.
The default implementation of this virtual member function calls the QuitRow
callback.
|
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 |
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:
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. addErrorMessage()
member function may be called to describe the reason for the failure. 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:
or, alternatively, if you do not subclass the IliDataSource
class, you may use a callback:
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
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.
keepChanges | The "keepChanges" flag. |
IlTrue
if successful. 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.
keepChanges | The "keepChanges" flag. |
IlTrue
if successful. void IliDataSource::removeErrorSink | ( | IliErrorSink * | sink | ) |
Removes an error sink from this data source.
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.
Here is an example that shows how errors can be trapped:
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.
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.
reporter | The error reporter. |
|
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.
global | The data source scope (IlTrue for global). |
Reimplemented from IliDataGem.
void IliDataSource::setReadOnly | ( | IlBoolean | only | ) |
Specifies whether the data source is read-only.
only | The read only flag. |
Sets the table of the data source.
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.
name | The table property manager name. If 0 or an empty string, the default table property manager will be used. |
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.
colno | The column position. |
value | The value. |
IlTrue
if successful. 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.
colname | The column name. |
value | The value. |
IlTrue
if successful. 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.
colno | The column position. |
flag | The modified flag. |
Changes the modified attribute of the value of one column.
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.
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.
IlTrue
if successful. void IliDataSource::useTableProperties | ( | IlBoolean | flag | ) |
Enables/Disables use table properties.
flag | If IlTrue , the data source will use table properties. |
Validates the current row.
Validation is carried out in the following way:
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. onPrepareInsert()
or onPrepareUpdate()
virtual member function is called (depending on whether the current row is the insert row or not). 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.
interactive | The interactive flag. |
IlTrue
if successful.
|
static |
Returns the callback name which is called by the corresponding virtual member function.
© Copyright 2017, 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.