Standard actions used to navigate and manipulate a dataset in a datasource.

dbactns.pp contains classes used to implement TDataSetAction and its descendants. They are dataset-aware actions used to navigate and manipulate a dataset in a datasource.

This file is part of the Lazarus Component Library (LCL).

The following components are registered but not displayed on the Lazarus IDE component palette:

- TDataSetFirst
- TDataSetLast
- TDataSetNext
- TDataSetPrior
- TDataSetRefresh
- TDataSetCancel
- TDataSetDelete
- TDataSetEdit
- TDataSetInsert
- TDataSetPost

TDataSetAction
is the base class for all other standard TDataSet actions.

TDataSetAction is a TAction descendant that is the base class for all other standard TDataSet actions. TDataSetAction provides properties and methods which enables an action to be applied to a DataSource and its associated dataset.

TDataSetAction provides an overridden Notification method to perform component notifications when the DataSource is removed for the action. A virtual GetDataSet method is implemented to ensure that a DataSource is cast to a TDataSource class instance prior to accessing its dataset. The HandlesTarget method is overridden to determine if the class includes both a valid datasource and a dataset for a specified target.

Applications do not use instances of TDataSetAction; use one of the descendent classes that perform a specific action for a dataset.

TAction
Sets the value for the DataSource property.
New value for the property.
Performs a notification when the datasource for the component is removed.

Notification is an overridden procedure used to perform a notification message when the specified component is removed. AComponent contains the component for the notification message. Operation contains the operation for the notification message.

Notification calls the inherited method. When Operation contains the value opRemove and AComponent contains the same class instance as the DataSource property, the DataSource property is set to Nil.

Component for the notification.
Operation for the notification.
Gets the Dataset assigned to the specified target datasource.
TDataSet assigned to the specified target datasource.
DataSource object examined in the method.
Indicates if the action is handled for the specified target.
True when a valid DataSource and DataSet exist in the Target.
Object instance examined in the method.
DataSource with the dataset for the action.

DataSource is a TDataSource property which provides access to properties, methods, and events for the TDataSet used in the data source. Changing the value for DataSource causes a free notification message to be performed for the new class instance used as the value for the property.

TDataSetFirst
moves to first record in the DataSet.

TDataSetFirst is a TDataSetAction descendant which moves to the first record in the dataset for a DataSource. TDataSetFirst can be added to an action list and assigned to controls which perform the corresponding action.

TDataSetFirst publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its First method.
Target where the action is performed in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object. UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active and not already positioned at its beginning (or first record). This ensures that the action cannot be performed for a dataset that has not been opened, or does not require repositioning.

Target datasource examined in the method.
TDataSetLast
moves to last record in the DataSet.

TDataSetLast is a TDataSetAction descendant which moves to the last record in the dataset for a DataSource. TDataSetLast can be added to an action list and assigned to controls which perform the corresponding action.

TDataSetLast publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Last method.
Target datasource examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active and not already positioned at end-of-file (last record). This ensures that the action cannot be performed for a dataset that has not been opened, or does not require repositioning.

Target datasource examined in the method.
TDataSetNext
moves to next record in the DataSet.

TDataSetNext is a TDataSetAction descendant which moves to the next record in the dataset for a DataSource. TDataSetNext can be added to an action list and assigned to controls which perform the corresponding action.

TDataSetNext publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which uses the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Next method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active and not already positioned at end-of-file (or last record). This ensures that the action cannot be performed for a dataset that has not been opened, or does not require repositioning.

DataSource object examined in the method.
TDataSetPrior
moves to previous record in the DataSet.

TDataSetPrior is a TDataSetAction descendant which moves to the previous record in the dataset for a DataSource. TDataSetPrior can be added to an action list and assigned to controls which perform the corresponding action.

TDataSetPrior publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Prior method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active and not already positioned at its beginning (or first record). This ensures that the action cannot be performed for a dataset that has not been opened, or does not require repositioning.

DataSource object examined in the method.
TDataSetRefresh
refreshes the DataSet.

TDataSetRefresh is a TDataSetAction descendant which refreshes the record content in the dataset for a DataSource. TDataSetRefresh can be added to an action list and assigned to controls which perform the corresponding action.

TDataSetRefresh publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Refresh method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active. This ensures that the action cannot be performed for a dataset that has not been opened.

DataSource object examined in the method.
TDataSetCancel
cancels the current edit mode for a DataSet.

TDataSetCancel is a TDataSetAction descendant which cancels the current edit mode for a dataset record in its DataSource. This includes restoring the values in records to their pre-editing content, updating the record display, and removing any edit mode(s) assigned to the State property in the dataset. TDataSetCancel can be added to an action list and assigned to controls which perform the corresponding action.

TDataSetCancel publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Cancel method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active, and the value in its State property is in the dsEditModes set. This ensures that the action cannot be performed for a dataset that has not been opened, or has not been placed in edit mode.

DataSource object examined in the method.
TDataSetDelete
deletes the current record in the DataSet.

TDataSetDelete is a TDataSetAction descendant which deletes the current record in the dataset for the target DataSource.

Delete behavior is dependent on the underlying database engine. Datasets using the DBF engine simply mark a record for deletion; it is not physically removed until the database engine packs the storage structure. Other datasets, such SQL-based ones, may require that changes be committed before they are flushed to the database engine.

TDataSetDelete publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Delete method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active, is not positioned at the beginning- or end-of-file, and contains True in its CanModify property. This ensures that the action cannot be performed for a dataset that has not been opened, or when the current record cannot be modified.

DataSource object examined in the method.
TDataSetEdit
edits the current record in the DataSet.

TDataSetEdit is a TDataSetAction descendant which edits the current record in the dataset for the target DataSource. TDataSetEdit ensures that the dataset is placed in edit mode (when available) by calling the Edit method for the dataset. Edit behavior is dependent on the underlying database engine.

TDataSetEdit publishes the DataSource property which explicitly declares the target for the database action. The DataSource may be determined by examining a data-aware control which used the database action, and passed an an argument to the UpdateTarget and HandlesTarget methods.

Retrieves the dataset for the target datasource and calls its Edit method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active, contains True in its CanModify property, and the value in its State property is in the dsEditModes set. This ensures that the action cannot be performed for a dataset that has not been opened, has not been placed in edit mode, or the current record cannot be modified.

DataSource object examined in the method.
TDataSetInsert
inserts (appends) a new record into the DataSet.

TDataSetInsert is a TDataSetAction descendant which inserts a new record into the dataset for the target DataSource. The new record has blank values in each of its fields, and allows editing of the field values.

Positioning of the inserted record is actually determined using the facilities for the underlying database engine. In most cases, the record is simply appended to its data store and ordered using the indexing facilities for the database engine. Some database engines require an additional step to make the record insertion and/or field editing permanent; i.e. SQL databases require use of a COMMIT statement to flush the changes to the database engine.

TDataSetInsert calls the Insert method for the target dataset to perform the databse action.

Retrieves the dataset for the target datasource and calls its Insert method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object. UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active. No other conditions are checked for the dataset. This ensures that the action cannot be performed for a dataset that has not been opened.

DataSource object examined in the method.
TDataSetPost
posts changes for the current record to the DataSet.

TDataSetPost posts editing changes for the current record into the DataSet. Some datasets may require additional actions for editing changes to become permanent; i.e. SQL databases use transactions that require a COMMIT statement to be executed before changes are written to the database engine.

Retrieves the dataset for the target datasource and calls its Post method.
DataSource object examined in the method.
Enables or disables the action based on the state of the dataset in the target.

UpdateTarget is an overridden method which enables or disables the database action based on the state of the dataset in the Target object.

UpdateTarget calls the GetDataSet method to retrieve the dataset in the Target datasource. The action is Enabled when the dataset is active, and its State contains a value in the dsEditModes set. This ensures that the action cannot be performed for a dataset that has not been opened, or has not been placed in edit mode.

Please note that UpdateTarget does not check the values for fields in the current record to determine if they have actually been altered.

DataSource object examined in the method.
Registers components for use in the Lazarus IDE.

The following components are registered but not displayed on the Lazarus IDE component palette:

- TDataSetFirst
- TDataSetLast
- TDataSetNext
- TDataSetPrior
- TDataSetRefresh
- TDataSetCancel
- TDataSetDelete
- TDataSetEdit
- TDataSetInsert
- TDataSetPost