Copyright: Copyright © 1998-2008 Developer Express Inc. ALL RIGHTS RESERVED


TcxDataSummaryGroup
  TcxDataSummaryGroup Object

Hierarchy          Properties          Methods        See also

Represents a summary group.

Unit

cxCustomData

TcxDataSummaryGroup = class(TCollectionItem);

Description

A summary group is an association of specific grouping items with group summaries.  When grid records are grouped by any of these items, the data controller calculates the corresponding group summaries.

The example below demonstrates the summary group which associates grouping items (Customer and OrderNo) with specific group summaries.

When records are grouped by any of these grouping items, calculations are performed on:

•	the minimum value by the SaleDate item

•	the average value by the AmountPaid item

•	the sum of values in a group by the ItemsTotal item.

Grouping items are maintained by the Links property.  SummaryItems specifies the collection of corresponding group summaries.

TcxDataSummaryGroup is an element of the TcxDataSummaryGroups.Items collection.  The TcxDataSummaryGroups class allows you to define several summary groups for a grid control.


TcxDataSummaryGroup Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxDataSummaryGroup
TcxDataSummaryGroup Properties

TcxDataSummaryGroup          Legend

In TcxDataSummaryGroup

Links

SummaryGroups

SummaryItems


Methods for TcxDataSummaryGroup
TcxDataSummaryGroup Methods

TcxDataSummaryGroup          Legend

In TcxDataSummaryGroup

Assign

Create

Destroy


TcxDataSummaryGroup.Links

TcxDataSummaryGroup          See Also

Specifies the collection of grouping items that belong to the current summary group.

property Links: TcxDataSummaryGroupItemLinks;

Description

The Links property maintains the collection of TcxDataSummaryGroupItemLink objects, each of whichrefers to a grouping item.  A summary group associates grouping items with group summaries provided by the SummaryItems property.


TcxDataSummaryGroup.SummaryGroups

TcxDataSummaryGroup           See Also

Identifies the collection containing the current summary group.

property SummaryGroups: TcxDataSummaryGroups;

Description

Use the SummaryGroups property to access the collection of summary groups to which the current TcxDataSummaryGroup object belongs.

ReadOnly Property


TcxDataSummaryGroup.SummaryItems

TcxDataSummaryGroup           See Also

Defines the collection of group summaries in the current summary group.

property SummaryItems: TcxDataGroupSummaryItems;

Description

The SummaryItems property defines the collection of group summaries in the current summary group.  These group summaries are associated with grouping items that are set via the Links property.


TcxDataSummaryGroup.Assign

TcxDataSummaryGroup

Copies the properties of a specified summary group to the current TcxDataSummaryGroup class instance.

procedure Assign(Source: TPersistent); override;

Description

The Assign method copies the summary group specified by the Source parameter to the current TcxDataSummaryGroup object.


TcxDataSummaryGroup.Create

TcxDataSummaryGroup

Creates a TcxDataSummaryGroup instance.

constructor Create(Collection: TCollection); override;

Description

The constructor creates an instance of the TcxDataSummaryGroup class and initializes its properties to their default values.


TcxDataSummaryGroup.Destroy

TcxDataSummaryGroup

Destroys the current instance of the TcxDataSummaryGroup class.

destructor Destroy; override;

Description

The destructor destroys the current TcxDataSummaryGroup object and free all resources allocated for it.  Do not call Destroy directly.  Call Free instead.  Free verifies that the object reference is not nil before calling Destroy.


cxCustomData Unit Overview
cxCustomData Unit

Classes

TcxCustomDataController

TcxCustomDataSource

TcxCustomDataSummaryItem

TcxDataControllerGroups

TcxDataFilterCriteria

TcxDataFilterCriteriaItem

TcxDataFilterValueList

TcxDataFooterSummaryItems

TcxDataGroupSummaryItems

TcxDataSummary

TcxDataSummaryGroup

TcxDataSummaryGroupItemLink

TcxDataSummaryGroupItemLinks

TcxDataSummaryGroups

TcxDataSummaryItem

TcxDataSummaryItems

Other Types

TcxDataControllerOption

TcxDataControllerOptions

TcxDataSortOrder


TcxCustomDataController
TcxCustomDataController Object

Hierarchy          Properties          Methods          Events          See also

Represents the data controller that manages data from a data store.

Unit

cxCustomData

TcxCustomDataController = class(TPersistent, IUnknown);

Description

A data controller is an object that provides access to data in a data store and enables you to perform operations on it.  The TcxCustomDataController class provides the following data loading modes:

•	Unbound mode.  In this mode, you need to populate the data controller with data manually, record-by-record and item-by-item.  For this purpose, first set the number of records via the RecordCount property.  Then use the Values property to get/set data in a particular cell.

•	Provider mode.  In this mode, the data controller works with a custom (user-defined) data source.  You can create a custom data source by deriving from the TcxCustomDataSource class and this will provide data for the data controller.  Provider mode is a convenient way to populate the data controller with data from non data-aware sources (data which cannot be accessed via a TDataSource component).

To get more information on working in these modes in ExpressQuantumGrid, refer to the Provider Mode and Unbound Mode documents in the Task Based Help section.

A data controller stores data as an internal set of records (in provider mode, it loads all records from the custom data source to its internal store).  This enables applying a set of filter conditions to data, calculating summaries and handling grouping.

A data controller indexes records when they are loaded from a data source.  Every data record is assigned a zero based index called the record index, and this specifies the position of the corresponding record in the data source.  Record indexes always refer to the same data regardless of the record’s displayed position.  The total number of records in a data controller is defined by the RecordCount property.

The order in which records from your data controller are displayed on screen (for instance, using ExpressQuantumGrid) is based on the filtering, grouping and sorting applied.  The visual position of a record is specified by its row index.

The data controller assigns row indexes only to rows that can be visible.  This means data records and grouping rows which can be potentially displayed and therefore can be focused, selected and deleted.  Row indexes are not assigned to hidden rows.  This includes records hidden within collapsed data groups.  Note:  hidden data records can still be accessed by record indexes, even though they are not assigned row indexes by the data controller. The number of rows available to display is returned by the RowCount property.

See the GetRowIndexByRecordIndex method to retrieve the current position of a specific record in a data controller.

A data controller in turn provides the data it contains for other controls.  For instance, Grid Views in ExpressQuantumGrid obtain data from a data controller to display in various ways.  Grid Views interact with the user and invoke the data controller’s methods in response to user actions.  For instance, when the end-user presses the Insert key, the View invokes the data controller’s Insert method.

TcxCustomDataController is the base class for the TcxDBDataController class, which implements dataset functionality via TDataSource objects (i.e. the bound loading mode).  In bound mode, operations such as inserting, appending, deleting, posting, modifying data and navigating records are handled by the data controller calling the appropriate routines of the underlying dataset.

A data controller allows you to represent a master-detail relationship between stores.  In a master-detail relationship, every record from a master data source is associated with zero or more records from a detail data source.

ExpressQuantumGrid provides the ability to display master-detail relationships between stores.  Every Grid View (a descendant of the TcxCustomGridView class) in ExpressQuantumGrid is associated with a data controller to provide the data for the View.

To display a master-detail relationship, a hierarchical structure of Views should be created similarly to the one displayed in the following image:

The first View represents the data from a master source while the second View represents data from a detail data source.  Master and detail Views obtain data from their corresponding data controllers (master and detail).

There is one issue concerning detail Views and detail data controllers.  The DetailTableView in the image above actually represents a "pattern" View.  It is associated with a ‘pattern’ type data controller.  Pattern data controllers do not provide data and pattern Views do not display information.  They are only used as templates when creating real details (clones).  View and data controller clones are created on demand, i.e. when the user expands a record in the master View for the first time.

You can test whether a data controller is a detail by using the IsDetailMode function.  See the IsPattern function to know whether the current detail data controller is a pattern or its clone.

The GetDetailDataController function allows you to return a clone of the detail data controller associated with a particular record of a master data controller.

Changing settings of a clone of a detail data controller does not affect other existing clones of the same data controller.

You can change the settings of the pattern detail data controller and then call the ClearDetails method.  This will recreate existing clones with current settings of the pattern data controller.  To get a reference to the pattern data controller, see the GetPatternDataController function.

If the current data controller is a detail, you can use the GetMasterDataController function to obtain a reference to its master data controller.

You can refer to the Provider Mode: Master-Detail and Unbound Mode: Master-Detail sections in the ExpressQuantumGrid help system to get information on establishing master-detail relationships in these loading modes.

In bound mode, you have to use the MasterKeyFieldNames, DetailKeyFieldNames and KeyFieldNames properties to set up a master-detail relationship.  Also refer to the following documents: Master-Detail and Grid Mode: Master-Detail.


TcxCustomDataController Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomDataController
TcxCustomDataController Properties

TcxCustomDataController          Legend

In TcxCustomDataController

CustomDataSource

DisplayTexts

EditOperations

EditState

Filter

FilteredIndexByRecordIndex

FilteredRecordCount

FilteredRecordIndex

FocusedRecordIndex

FocusedRowIndex

Groups

IsEditing

IsPattern

MultiSelect

Options

RecordCount

RowCount

Search

Summary

Values


Methods for TcxCustomDataController
TcxCustomDataController Methods

TcxCustomDataController          Legend

In TcxCustomDataController

Append

AppendRecord

BeginFullUpdate

BeginUpdate

BeginUpdateFields

Cancel

ChangeDetailExpanding

ChangeRowSelection

CheckFocusedSelected

ClearBookmark

ClearDetailLinkObject

ClearDetails

ClearSelection

ClearSorting

CollapseDetails

DeleteFocused

DeleteRecord

DeleteSelection

Edit

EndFullUpdate

EndUpdate

EndUpdateFields

FindRecordIndexByText

FocusDetails

ForEachRow

GetDetailDataController

GetMasterDataController

GetMasterRecordIndex

GetPatternDataController

GetRowDisplayText

GetRowIndexByRecordIndex

GetRowInfo

GetRowValue

GetSelectedCount

GetSelectedRowIndex

GotoBookmark

GotoFirst

GotoLast

GotoNext

GotoPrev

Insert

InsertRecord

IsBOF

IsBookmarkAvailable

IsDetailMode

IsEOF

IsGridMode

IsRowSelected

LoadFromStream

MakeRecordVisible

Post

RefreshExternalData

RestoreKeys

SaveBookmark

SaveKeys

SaveToStream

SelectAll

SelectRows

SetEditValue

SetValue

SyncSelected

UpdateItems


Events for TcxCustomDataController
TcxCustomDataController Events

TcxCustomDataController          Legend

In TcxCustomDataController

OnAfterCancel

OnAfterDelete

OnAfterInsert

OnAfterPost

OnBeforeCancel

OnBeforeDelete

OnBeforeInsert

OnBeforePost

OnCompare

OnDataChanged

OnDetailCollapsed

OnDetailCollapsing

OnDetailExpanded

OnDetailExpanding

OnFilterRecord

OnGroupingChanged

OnNewRecord

OnRecordChanged

OnSortingChanged


TcxCustomDataController.CustomDataSource

TcxCustomDataController           See also          Example

Identifies the user-defined data source.

property CustomDataSource: TcxCustomDataSource;

Description

Use the CustomDataSource property to specify the user-defined data source which allows the representation of arbitrary data within a visual display control.  This mode is called provider mode.  To use provider mode you should create your own class by deriving it from TcxCustomDataSource and assign an instance of this class to the CustomDataSource property.


TcxCustomDataController.DisplayTexts

TcxCustomDataController           See also

Determines the text representation of the value in an item at a specific record.

property DisplayTexts[RecordIndex, ItemIndex: Integer]: string;

Description

The DisplayTexts property allows you to access the text representation of the value at a specific record and item.  The RecordIndex parameter identifies the record index in a data source.  The total number of records is defined by the RecordCount property.  The ItemIndex parameter addresses an item in the record and specifies the current value of the TcxCustomGridTableItem.Index property.  When working in a Grid View, the ItemIndex parameter defines the TcxGridColumn object position within the collection of owner columns.  When working in a Card View, the ItemIndex parameter defines the card row position of the TcxGridCardViewRow class.

To return actual values instead of their text representation, use the Values property.  This property allows you to set values for cells using the unbound and provider modes.  In bound mode, you need to use the methods provided by TDataSet descendants.


TcxCustomDataController.Filter

TcxCustomDataController           See also

Defines the set of filter conditions applied to a grid control.

property Filter: TcxDataFilterCriteria;

Description

Use the Filter property to specify the filter criteria for a grid control.  The filter criteria describe a set of filter conditions combined by logical operators.  You can add, remove filter conditions for specific items, customize a list of values for a filter condition and control the filtering process.  After you add filter conditions, you have to apply them by setting the TcxDataFilterCriteria.Active property to True.


TcxCustomDataController.Groups

TcxCustomDataController           See Also

Provides access to data groups in a grid control.

property Groups: TcxDataControllerGroups;

Description

The Groups property allows you to control grouping in a grid control.  Use the Groups property to get handles of specific data groups, group by individual items and expand or collapse data groups.  Handles (or indexes) of data groups are used to access attributes of groups (summary values, for instance).

ReadOnly Property


TcxCustomDataController.EditOperations

TcxCustomDataController          See also

Specifies a set of operations to perform on records in a data controller.

type

  TcxDataControllerEditOperation = (dceoAppend, dceoDelete, dceoEdit, dceoInsert, dceoShowEdit);

  TcxDataControllerEditOperations = set of TcxDataControllerEditOperation;

property EditOperations: TcxDataControllerEditOperations;

Description

The EditOperations property specifies which operations can be performed on records in a data controller.  The TcxDataControllerEditOperations type contains the range of possible operations.

The availability of particular operations is determined by the data controller (TcxCustomDataController and its descendants).

Value	Description
dceoAppend	Appending records in the data controller is enabled.
dceoDelete	Deleting records in the data controller is enabled.
dceoEdit	Editing records in the data controller is enabled.
dceoInsert	Inserting records in the data controller is enabled.
dceoShowEdit	An editor can be activated for a record’s field when records from the data controller are represented by the ExpressQuantumGrid, for instance.

In the unbound and provider modes implemented by the TcxCustomDataController class, all operations are allowed.

In bound mode (implemented by TcxDBDataController), all operations (except for dceoShowEdit) are available if the CanModify property of the underlying dataset and the SyncMode property are set to True.  The dceoShowEdit operation is available only if the SyncMode property is set to True.

ReadOnly Property


TcxCustomDataController.EditState

TcxCustomDataController          See also

Specifies the edit state of a data controller.

type

  TcxDataControllerEditKind = (dceInsert, dceEdit, dceChanging, dceModified);

  TcxDataControllerEditState = set of TcxDataControllerEditKind;

property EditState: TcxDataControllerEditState;

Description

The EditState property contains a set of flags indicating the current edit state of your data controller.  When you insert a record or modify its value, the data controller sets corresponding flags in EditState.

The following table describes the possible edit states:

Value	Description
dceInsert	Indicates that a record has been inserted but not yet posted.  After posting, the flag is cleared.
dceEdit	Indicates that a record is in edit mode.  This flag is not activated when the dceInsert flag is set, i.e. when editing a new record yet to be posted.
dceChanging	This flag is active in edit mode while changing the value of a record field using an editor, but before applying those changes to the data controller. After applying the changes, the flag is cleared. When records from the data controller are handled by ExpressQuantumGrid, for instance, the flag is activated when a user types a new value within the editor.  When he/she presses the Enter key, the changes made are sent back to the data controller and the flag is cleared.  After the Enter key is pressed, the dceModified flag is activated.
dceModified	This flag is active in edit mode after modifying a record field in the data controller.  See the description of the dceChanging flag for more details.

ReadOnly Property


TcxCustomDataController.FilteredIndexByRecordIndex

TcxCustomDataController          See also

Returns the position of a data record in the list of filtered records.

property FilteredIndexByRecordIndex[Index: Integer]: Integer;

Description

The FilteredIndexByRecordIndex property returns the position of a record in the list of filtered records.  The record required is identified by its index via the Index parameter.

The value returned is the index of a record within the list of filtered records.  It can vary from 0 to FilteredRecordCount – 1.  If a specific record doesn’t belong to the list of filtered records (it doesn’t meet the filter criteria set), the FilteredIndexByRecordIndex returns –1.

ReadOnly Property

The following code tests whether a particular record in a data controller meets the current filter criteria.

//Delphi

function IsFiltered(ADataController: TcxCustomDataController; ARecordIndex: Integer): Boolean;

begin

  Result := ADataController.FilteredIndexByRecordIndex[ARecordIndex] <> -1;

end;

//C++ Builder

bool IsFiltered(TcxCustomDataController * ADataController, int ARecordIndex) {

  return ADataController->FilteredIndexByRecordIndex[ARecordIndex] != -1;

}


TcxCustomDataController.FilteredRecordCount

TcxCustomDataController          See also         Example

Specifies the number of data records in a data controller after applying filter criteria.

property FilteredRecordCount: Integer;

Description

The FilteredRecordCount property returns the number of filtered data records in a data controller, i.e. the number of data records that meet the current filter criteria.  This does not take into account the grouping rows that are created when the data is grouped.  To get the number of rows (data records and grouping rows) actually visible, see the RowCount property.

If no filter criteria are applied, FilteredRecordCount returns the same value as the RecordCount property. RecordCount specifies the total number of data records in your data controller.

The FilteredRecordIndex property allows you to get the record index of a filtered record.  It takes the index of the filtered record (a value which varies from 0 to FilteredRecordCount – 1) as a parameter and returns the record index.  The FilteredIndexByRecordIndex property performs the opposite operation: it returns the position of a particular record among all filtered records.

ReadOnly Property


TcxCustomDataController.FilteredRecordIndex

TcxCustomDataController          See also         Example

Returns the record index of a filtered record.

property FilteredRecordIndex[Index: Integer]: Integer;

Description

The number of filtered records after filter criteria are applied is provided by the FilteredRecordCount property.

The FilteredRecordIndex property returns the record index of a filtered record by its position in the list of all filtered records (defined by the Index parameter).  The Index parameter can vary from 0 to FilteredRecordCount – 1.

See the FilteredIndexByRecordIndex property to get the position of a record with a particular record index within the list of filtered records.

ReadOnly Property


TcxCustomDataController.FocusedRecordIndex

TcxCustomDataController          See also

Specifies the record index of the record with the current focus.

property FocusedRecordIndex: Integer;

Description

The FocusedRecordIndex property specifies the record index of the focused record.  By changing the FocusedRecordIndex property, you can set focus to another data record.

If you need to focus a record at a particular position determined by its row index, use the FocusedRowIndex property.  This property enables you to focus data records and grouping rows that are visible or potentially visible by scrolling (for instance, using ExpressQuantumGrid).  Records hidden within collapsed data groups are not assigned row indexes and therefore cannot be focused via the FocusedRowIndex property.

Refer to the TcxCustomDataController class description for information on record and row indexes.

When synchronization between a grid control and a dataset is enabled (in bound mode implemented by the TcxDBDataController class), the focused record corresponds to the current/active record in TDataSet.  In this case, dataset navigation by the TDataSet.First, TDataSet.Last, TDataSet.Next, TDataSet.Prior and TDataSet.MoveBy methods changes the focused record position.  Synchronization between a grid control and a dataset is enabled when

•	the grid control works in Grid Mode

or

•	the DataController.DataModeController.SyncMode property is set to True

In bound Grid Mode, only a fixed number of records are loaded into the memory buffer at a time.  When scrolling causes a different set of records to be loaded into the buffer, the focused record automatically changes to address a record within this buffer.  In Grid Mode, the FocusedRecordIndex property stores a record index relative to the first record of the current record set loaded into the buffer.


TcxCustomDataController.FocusedRowIndex

TcxCustomDataController         See also

Specifies the row index of the record with focus.

property FocusedRowIndex: Integer;

Description

The FocusedRowIndex property returns the row index of the data record or grouping row currently focused.  Changing the FocusedRowIndex value moves the focus to the corresponding record. The FocusedRowIndex property allows you to focus data records and grouping rows currently visible or potentially visible by scrolling (for instance, using ExpressQuantumGrid).  Records hidden within collapsed data groups are not assigned row indexes and therefore cannot be focused via the FocusedRowIndex property.

You can focus a particular record by its record index via the FocusedRecordIndex property.  This property allows the focusing of any data records regardless of their visibility state.

Refer to the TcxCustomDataController class description for information on record and row indexes.

When synchronization between a grid control and a dataset is enabled (in bound mode implemented by the TcxDBDataController class), the focused record corresponds to the current/active record in TDataSet.  In this case, dataset navigation via the TDataSet.First, TDataSet.Last, TDataSet.Next, TDataSet.Prior and TDataSet.MoveBy methods changes the focused record position.  Synchronization between a grid control and a dataset is enabled when

•	the grid control works in Grid Mode

or

•	the DataController.DataModeController.SyncMode property is set to True

In bound Grid Mode, only a fixed number of records are loaded into the memory buffer at a time.  When scrolling causes a different set of records to be loaded into the buffer, the focused record automatically changes to address a record within this buffer.


TcxCustomDataController.IsEditing

TcxCustomDataController          See also

Specifies whether a data controller is in edit mode.

property IsEditing: Boolean;

Description

The IsEditing property returns a value indicating whether your data controller is in edit mode.  The function returns True in the following cases:

•	you activated edit mode using the Edit or the TDataSet.Edit method

•	you inserted or appended a new record and it is not yet posted.  To insert a new record, you can call the Insert, Append methods or the corresponding dataset methods.

In ExpressQuantumGrid, for instance, edit mode is activated when the end-user starts modifying a record, or presses the Insert key to add a new record.

When edit mode is disabled, the IsEditing function returns False.  This is the case when you are not editing the focused record.

ReadOnly Property


TcxCustomDataController.IsPattern

TcxCustomDataController          See also

Indicates whether the current detail data controller is a pattern, as defined below.

property IsPattern: Boolean;

Description

A non-pattern data controller is any data controller containing records with which the end-user can interact (via the ExpressQuantumGrid, for instance).  The IsPattern function returns False for:

1)	clones of a detail data controller

2)	data controllers without master data controllers (such data controllers have no patterns at all)

The term "pattern" can be applied only to detail data controllers.  A pattern data controller does not contain data and is only used to provide settings when creating its clones (instances of a detail data controller corresponding to particular records in a master data controller).

The TcxCustomDataController topic provides more information on patterns and clones.

The following image demonstrates a Structure Navigator of ExpressQuantumGrid displaying a master-detail relationship between two Views (MasterTableView and DetailTableView):

The Views are associated with the master and detail data controllers respectively, say MasterDataController and DetailDataController.  MasterDataController is a non-pattern, as it has no master data controller.  DetailDataController is a pattern.  It is used only as a template for creating its clones.

Settings of detail clones can be changed independently.  Also, changing settings of a pattern detail data controller does not affect its existing clones until the ClearDetails method of a non-pattern master data controller is called.  This recreates existing detail clones with the current settings from the pattern detail data controller.


TcxCustomDataController.MultiSelect

TcxCustomDataController          See also          Example1          Example2

Enables selection of multiple records in a data controller.

property MultiSelect: Boolean;

Description

A data controller enables you to select and focus particular rows (data records and grouping rows).  There is always one focused row in the data controller and this is determined by the FocusedRowIndex property.

If the MultiSelect property is set to False, there can be only one selected row — the focused row.  In this mode, when you focus a row, it is automatically selected and the GetSelectedCount method returns 1.  However, the SyncSelected method does allow you to unselect the focused row.  In this case, GetSelectedCount will return 0.

If the MultiSelect property is set to True, you are able to select multiple rows in the data controller.  In this mode, you can use the ChangeRowSelection, SelectRows and SelectAll methods to change the selection state of rows.  Changing the selection state of a row does not affect the focused row.

Use the GetSelectedCount method to return the number of selected rows.

Different approaches are required when accessing selected records in provider, unbound and default bound modes and when Grid Mode is applied.  Use the supplied ForEachRow method to hide this complexity as it provides iteration of rows regardless of the data mode.

In provider, unbound and default bound modes, the data controller maintains all records loaded from a data source in memory.  You can also use the GetSelectedRowIndex method to iterate selected rows.  The method’s parameter specifies the index of a selected row, which can vary from 0 to GetSelectedCount –1.  The method returns the row index of the selected row.  Once you obtain the row index, you can retrieve the row’s details by calling the GetRowInfo function.  This information includes the level, expansion state and its record index.  See Example1 showing how to access selected rows via GetSelectedRowIndex and ForEachRow.

Grid Mode is a special bound mode providing better performance for huge datasets.  To enable Grid mode, set the TcxDBDataController.DataModeController.GridMode property to True.  In grid mode, grouping is not allowed.  When you group data, grid mode is automatically disabled.

When Grid mode is applied, the data controller creates bookmarks for selected data records.  To access bookmarks and thus traverse through the selected records, you should use the GetSelectedBookmark function.  The ForEachRow method can also be used to iterate records in GridMode.

Example2 shows how to change values of a particular field within selected records in bound mode.  This can be used when GridMode is enabled or disabled.

To enable multiple record selection in ExpressQuantumGrid, you can also use the View’s OptionsSelection.MultiSelect property.  Changing the OptionsSelection.MultiSelect property sets the MultiSelect property of the data controller.


TcxCustomDataController.Options

TcxCustomDataController           See also

Defines the set of options affecting the behavior of a data controller.

property Options: TcxDataControllerOptions;

Description

The TcxDataControllerOptions type provides a set of flags controlling the behavior of a data controller when records are sorted, created, etc.

For instance, you can specify whether to apply locale settings and whether the comparison is case-insensitive.  It is possible to control comparison operations directly by writing an OnCompare event handler.

The default value of the Options property is [].


TcxCustomDataController.RowCount

TcxCustomDataController          See Also

Returns the number of rows in a data controller.

property RowCount: Integer;

Description

The number of records stored in a data controller is specified by its RecordCount property.  In bound and provider modes, it identifies the number of records loaded from a data source.  Note that when grid mode is applied, the value returned by RecordCount is determined by the GridModeBufferCount property.

The RowCount property returns the number of rows (data records and grouping rows) that can be actually displayed on screen.  The RowCount value can differ from RecordCount when grouping or filtering data is applied.

For instance, when the data controller filters records from a database table, RowCount returns the number of rows after applying filter condition(s).  The RecordCount property, in this case, returns the total number of records obtained from the table.

ReadOnly Property


TcxCustomDataController.RecordCount

TcxCustomDataController           See Also

Defines the number of records provided by the data controller.

property RecordCount: Integer;

Description

Use the RecordCount property to get and set the number of records displayed (i.e. the number of rows) in the data controller.  You can change the number of records in the data controller using the RecordCount property only in provider and unbound modes.  Setting the RecordCount property to a value exceeding the actual number of records in a data source forces a grid control to display extra empty records.

In bound mode, the data controller assigns the RecordCount automatically when loading records from the underlying dataset.  You must not change RecordCount in this mode.  You can use the data controller’s Append, Insert, DeleteFocused and DeleteSelection methods to add and delete records.


TcxCustomDataController.Search

TcxCustomDataController

Provides access to the object enabling you to perform incremental searching programmatically.

property Search: TcxDataControllerSearch;

Description

Use the Search property to access the TcxDataControllerSearch object whose methods allow you to perform incremental searching via code.  This object also declares properties that provide information about the current incremental searching state.  Note that the properties and methods exposed by the TcxDataControllerSearch object are not applicable to all Developer Express data-aware controls.  Please refer to the TcxDataControllerSearch class description for details.

ReadOnly Property


TcxCustomDataController.Summary

TcxCustomDataController           See Also

Specifies the set of summaries calculated by grid data.

property Summary: TcxDataSummary;

Description

Use the Summary property to define the number of summaries for a grid control.  It allows you to set footer and group summaries, access summary results and control the process of summary calculation.


TcxCustomDataController.UseNewItemRowForEditing

TcxCustomDataController

This property is for internal use only.  You will have no need to use it in applications.

property UseNewItemRowForEditing: Boolean;


TcxCustomDataController.Values

TcxCustomDataController           See Also

Determines the value of a specific record and item.

property Values[RecordIndex, ItemIndex: Integer]: Variant;

Description

The Values property allows you to access the value of a specific record and item.  The RecordIndex parameter identifies the record index in a data source.  The total number of records is defined by the RecordCount property.  The ItemIndex parameter addresses an item in the record for which to get/set a value.  The ItemIndex parameter specifies the value of the TcxCustomGridTableItem.Index property.  When working in a Table View, the ItemIndex parameter defines the TcxGridColumn object position within the collection of owner columns.  When working in a Card View, the ItemIndex parameter defines the card row position of the TcxGridCardViewRow class.

You can change cell values using the Values property only in provider and unbound modes.  To modify records in bound mode, you should use the functionality provided by your dataset instead.

To return a text representation of a value, use the DisplayTexts property instead.


TcxCustomDataController.Append

TcxCustomDataController          See Also

Appends a new record to the underlying dataset.

procedure Append; virtual;

Description

Use the Append method to add a new record to your data controller.  If the data controller represents dataset data (TcxDBDataController), the Append method just calls the TDataSet.Append method and this

1.	creates a new record at the end of the dataset

2.	sets the active record to the new record

After the record becomes active, a user can set its field values and then post those changes.  To set values via code, use the methods and properties of the dataset (for instance, TDataSet.FieldValues).  To post changes, see the Post method (you can also use the Post method provided by the dataset).

In provider and unbound modes, Append behaves in a similar manner:  It adds a new record and focuses it.  When in these modes, you should use the Values property to set field values.  To identify a particular cell, you should know its record and item indexes.  The Append method does not return the index of the new record.  To work around this, use the FocusedRecordIndex property after adding a new record.

When a record is added using the Append method, data changes are not immediately posted.  Thus you can cancel changes until the data posting is performed.  If the record is cancelled, all changes are lost and the record is deleted.  A user can cancel the new record by pressing the Esc key.  To cancel modifications via code, see the Cancel method.

Note:	Do not call the Append method within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.

In provider and unbound modes, you can use the AppendRecord method to add a new record.  AppendRecord retrieves the record index that can be used to access its field values via the Values property.  The record added by AppendRecord does not require posting.  Also such a record cannot be discarded by calling the Cancel method.


TcxCustomDataController.AppendRecord

TcxCustomDataController          See Also

Appends a new record to a data controller.

function AppendRecord: Integer;

Description

The AppendRecord method adds a new empty record to your data controller.  You should use this method only in provider and unbound modes.  If the data controller represents dataset data (TcxDBDataController), you should use the Append method instead.

The AppendRecord method returns the record index of a record.  The record index can be used to access its field values by the Values property.

In provider mode, you need to implement the AppendRecord and InsertRecord methods of your custom data source to allow appending records.


TcxCustomDataController.BeginFullUpdate

TcxCustomDataController

Prevents update notifications in the data controller and the object that displays its data until the EndFullUpdate method call.

procedure BeginFullUpdate; virtual;

Description

The BeginFullUpdate method does the same as the BeginUpdate method and in addition it also locks the object that displays the data managed by this data controller.  This may be useful since locking only the data controller may result in multiple updates to the object that displays data when the data controller is unlocked.  If using the BeginFullUpdate and EndFullUpdate methods, the object that displays data is unlocked only after the data controller has been unlocked and this ensures that this object is updated only once which improves performance.

The TcxCustomDataController class doesn’t have any associated visual objects that display data.  Thus, its BeginFullUpdate method does exactly the same as the BeginUpdate method.  TcxCustomDataController descendants that have associated visual objects override the BeginFullUpdate method to provide the functionality described above.

The BeginFullUpdate and EndFullUpdate methods are mainly used internally.  To have greater control over updates use the data controller’s BeginUpdate and EndUpdate methods and lock the object that displays data using its own methods.

Note:	Do not call the Append, Insert, Post, and SetEditValue methods within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.


TcxCustomDataController.BeginUpdate

TcxCustomDataController          See Also

Postpones sending update notifications by the data controller.

procedure BeginUpdate;

Description

When you need to perform a series of operations, each of which leads to updating data and a resulting update notification by the data controller, consider using the BeginUpdate and EndUpdate methods.

For instance, each time you change the number of records in your data controller or modify a record’s value, the data controller automatically sends an update notification to the control (ExpressQuantumGrid, for instance) displaying its data.  In this case, you can enclose the code performing these operations within the BeginUpdate and EndUpdate method calls.  This ensures that the control is only updated once.

Each call to BeginUpdate must correspond to a call to the EndUpdate method.  To ensure that EndUpdate is called even if an exception occurs, you should use a try...finally block.

Note:	Do not call the Append, Insert, Post, and SetEditValue methods within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.

The following code shows how to add and fill a new record in unbound mode in a tvPlanets View of the ExpressQuantumGrid control.  The APeriodIndex, ADistanceIndex, ANameIndex and AOrbitsIndex variables specify the indexes of the columns to fill.

//Delphi

var

  ARecordIndex: Integer;

//...

with tvPlanets.DataController do

  begin

    BeginUpdate;

    ARecordIndex := InsertRecord(FocusedRecordIndex);

    try

    Values[ARecordIndex, APeriodIndex] := 87.97;

    Values[ARecordIndex, ADistanceIndex] := 57910;

    Values[ARecordIndex, ANameIndex] := 'Mercury';

    Values[ARecordIndex, AOrbitsIndex] := 'Sun';

    finally

      EndUpdate;

    end;

  end;

//C++ Builder

  int ARecordIndex;

  TcxCustomDataController * dc = tvPlanets->DataController;

  dc->BeginUpdate();

  try {

    ARecordIndex = dc->InsertRecord(dc->FocusedRecordIndex);

    dc->Values[ARecordIndex][APeriodIndex] = 87.97;

    dc->Values[ARecordIndex][ADistanceIndex] = 57910;

    dc->Values[ARecordIndex][ANameIndex] = "Mercury";

    dc->Values[ARecordIndex][AOrbitsIndex] = "Sun";

  } __finally {

    dc->EndUpdate();

  }


TcxCustomDataController.BeginUpdateFields

TcxCustomDataController

Locks field update notifications until the EndUpdateFields method is called.

procedure BeginUpdateFields;

Description

This method is for internal use only.  You will have no need to use it in applications.


TcxCustomDataController.Cancel

TcxCustomDataController          See Also

Cancels unposted record modifications.

procedure Cancel; virtual;

Description

You can call the Cancel method to discard changes made to field(s) of the active record prior to posting.  If the data controller is not in edit state or the changes were posted, Cancel does nothing.

When a new record is inserted/appended and hasn’t been posted, the Cancel method deletes it.  If a field is being modified, the Cancel method reverts it to its old value.

When data controller records are displayed in a Grid View, for instance, the end-user can cancel record modifications by pressing the Esc key.


TcxCustomDataController.ChangeDetailExpanding

TcxCustomDataController          See Also

Expands or collapses a master record.

function ChangeDetailExpanding(ARecordIndex: Integer; AExpanded: Boolean): Boolean;

Description

The ChangeDetailExpanding function expands or collapses a master record based upon the value of the AExpanded parameter.  If the value passed as this parameter is True, a master record is expanded.  Otherwise, the master record is collapsed.  The master record is identified by its index which is passed as the ARecordIndex parameter.

The ChangeDetailExpanding function returns True if the expansion state of the master record was successfully changed.  Otherwise, False is returned.

Call the CollapseDetails method to collapse the details of all the master records within the current data controller.


TcxCustomDataController.ChangeRowSelection

TcxCustomDataController          See also

Changes the selection state of a particular row.

procedure ChangeRowSelection(ARowIndex: Integer; ASelection: Boolean); virtual;

Description

A data controller enables you to select and focus rows (data records and grouping rows).  There is always one focused row in the data controller, which is controlled by the FocusedRowIndex property.

If the data controller’s MultiSelect property is set to False, there can be only one selected row — the focused row.  When you focus a row in this mode, it is automatically selected and the GetSelectedCount method returns 1.  However, the SyncSelected method does allow you to unselect the focused row.  In this case, GetSelectedCount will return 0.

If the MultiSelect property is set to True, you are able to select multiple rows in the data controller.  In this mode, you can use the ChangeRowSelection, SelectRows and SelectAll methods to change row selection states.  Changing the selection state of a row does not affect the focused row.

Use the ChangeRowSelection method to specify a row’s selection state (a data record or a grouping row) addressed by the ARowIndex parameter.  The ARowIndex parameter defines its row index.  To select this row, set ASelection to True.  To unselect it, set ASelection to False.

Note: To enable multiple record selection in ExpressQuantumGrid, you can also use the View’s OptionsSelection.MultiSelect property.  Changing the OptionsSelection.MultiSelect property sets the data controller’s MultiSelect property.

Let’s consider an example of selecting records within the tvCustomers View in ExpressQuantumGrid.  The following code selects records based on the Customer field value.  The Customer field is a string field displayed by the tvCustomersCustomer column.  We need to select records with the Customer field set to ‘Y’.

To get a row index using a particular record index, the GetRowIndexByRecordIndex method of the View’s data controller is used.  Its first parameter provides the record index and the second parameter determines whether the record should be visible if currently hidden under a collapsed group row.  The second parameter is set to True, to ensure that the record is visible, thus enabling its selection.

You should use this code only when GridMode is not in effect (the View’s DataController.DataModeController.GridMode property is set to False).  In Grid Mode, you will not be able to process all records using the following code.  To navigate records in Grid Mode, use the members of your TDataSet object (First, Last, Next, Prior and MoveBy).

//Delphi

var

  I: Integer;

//...

  tvCustomers.OptionsSelection.MultiSelect := True;

  with tvCustomers.DataController do

  begin

    ClearSelection();

    for I := 0 to RecordCount - 1 do

    begin

      if Values[I, tvCustomersCustomer.Index] = 'Y' then

        ChangeRowSelection(GetRowIndexByRecordIndex(I, True), True);

    end;

  end;

//C++ Builder

  tvCustomers->OptionsSelection->MultiSelect = true;

  TcxCustomDataController * ADataController =
    tvCustomers->DataController;

  ADataController->ClearSelection();

  for(int i = 0; i < ADataController->RecordCount; i++) {

    if (VarCompareValue(ADataController->      Values[i][tvCustomersCustomer->Index], "Y") == vrEqual)

      ADataController->ChangeRowSelection(        ADataController->GetRowIndexByRecordIndex(i, true), true);

  }


TcxCustomDataController.CheckFocusedSelected

TcxCustomDataController          See also

When selection of multiple records is enabled, this method selects the focused record.

procedure CheckFocusedSelected;

Description

The CheckFocusedSelected method is in effect only when selection of multiple records is enabled via the MultiSelect property.

In this mode, CheckFocusedSelected unselects all currently selected records and then sets selection to the focused record.  For instance, moving focus by the FocusedRowIndex property or by the TDataSet.Locate method does not affect the rows selected.  To select the newly focused row, call CheckFocusedSelected.

Use the ChangeRowSelection method to change the selection state of a particular row.


TcxCustomDataController.ClearBookmark

TcxCustomDataController          See Also

Removes the current bookmark.

procedure ClearBookmark;

Description

ClearBookmak allows you to clear the bookmark created by the SaveBookmark method.  After ClearBookmark is called, the bookmark becomes unavailable and the IsBookmarkAvailable function returns False.

If a bookmark exists, you can jump to the corresponding record via the GotoBookmark method.

For more information on bookmarks, see the SaveBookmark topic.


TcxCustomDataController.ClearDetailLinkObject

TcxCustomDataController          See also

Recreates a particular detail clone.

procedure ClearDetailLinkObject(ARecordIndex: Integer; ARelationIndex: Integer);

Description

Use the ClearDetailLinkObject method to recreate a detail clone specified by the master record index and relation index.  These indexes should be passed as the ARecordIndex and ARelationIndex parameters respectively.  Note that the ClearDetailLinkObject method is applied to non-pattern master data controllers, i.e. to master data controllers whose IsPattern property returns False.  See the description of this for additional information.

If you need to recreate all detail clones for a particular master data controller, use the ClearDetails method instead.


TcxCustomDataController.ClearDetails

TcxCustomDataController          See also

Recreates existing clones of detail data controllers associated with the current master data controller.

procedure ClearDetails;

Description

The ClearDetails method is applied to non-pattern master data controllers, i.e. to master data controllers whose IsPattern property returns False.   See this property description for more information.

The ClearDetails method recreates existing clones of detail data controllers associated with the current non-pattern master data controller.  Clones are recreated using the current settings of this detail data controller.

For instance, you can change the settings of the pattern detail data controller and then call ClearDetails to apply these changes to all existing detail clones.

For information on patterns and clones, see the TcxCustomDataController description.

The following example adds a new filter condition (PurchaseDate > 01/01/2003) to the pattern data controller of the detail tvOrders View in ExpressQuantumGrid.  The ClearDetails method is called for the master data controller (the data controller for the master tvCustomers View) in order to apply this condition to all existing clones of the detail data controller.

//Delphi

var

  ADate: string;

//...

  ADate := '01/01/2003';

  with tvOrders.DataController do

  begin

    BeginUpdate;

    try

      Filter.Clear;

      Filter.Root.AddItem(tvOrdersPurchaseDate, foGreater, StrToDate(ADate), ADate);

      Filter.Active := True;

    finally

      EndUpdate;

    end;

  end;

  tvCustomers.DataController.ClearDetails;

//C++ Builder

  String ADate = "01/01/2003";

  TcxCustomDataController * ADetailDC = tvOrders->DataController;

  ADetailDC->BeginUpdate();

  try {

    ADetailDC->Filter->Clear();

    ADetailDC->Filter->Root->AddItem(tvOrdersPurchaseDate, foGreater, StrToDate(ADate), ADate);

    ADetailDC->Filter->Active = true;

  } __finally {

    ADetailDC->EndUpdate();

  }

  tvCustomers->DataController->ClearDetails();


TcxCustomDataController.ClearSelection

TcxCustomDataController          See also

Unselects all rows in a data controller.

procedure ClearSelection;

Description

A data controller enables you to select rows (data records and grouping rows).

To enable multiple selection of rows, set the MultiSelect property to True.  In this case, you can use the ChangeRowSelection, SelectAll and SelectRows methods to select rows.

If MultiSelect is False, you are not able to select multiple rows.

The ClearSelection method clears the selection state of all selected rows.  ClearSelection is in effect only when MultiSelect is set to True.  To delete selected rows, use the DeleteSelection method.

The number of selected rows is determined by the GetSelectedCount method.  See the MultiSelect description for more information.


TcxCustomDataController.ClearSorting

TcxCustomDataController          See Also

Clears sort orders applied to items.

procedure ClearSorting(AKeepGroupedItems: Boolean);

Description

Use the ClearSorting method to clear sorting applied to items in the data controller.  The AKeepGroupedItems parameter specifies whether grouping items are affected by the method.  If AKeepGroupedItems is True, only the sort order of non-grouping items is changed.  Otherwise, the sort order of grouping items is reset.  See the TcxDataSortOrder type description for the list of the available sort orders.

Note, that the sort order of an item cannot be set to soNone while data is grouped by this item.  ClearSorting changes the sort order of a grouping item to soAscending, but when you ungroup data by this item, its sort order is automatically changed to soNone.


TcxCustomDataController.CollapseDetails

TcxCustomDataController          See also

Collapses details of the current master data controller.

procedure CollapseDetails;

Description

This method is applied to non-pattern master data controllers, i.e. to master data controllers whose IsPattern property returns False.  The CollapseDetails method collapses all the records expanded within the current master data controller.

You can change the expansion state of a specific record using the ChangeDetailExpanding method.  In the ExpressQuantumGrid, you can use the Expand method of record objects also.


TcxCustomDataController.DeleteFocused

TcxCustomDataController          See also

Deletes the focused row in a data controller.

procedure DeleteFocused; virtual;

Description

The DeleteFocused method deletes the focused row in your data controller.  The DeleteFocused method allows deleting both data and grouping rows.  Deleting a group row will delete all rows belonging to its corresponding group.

The currently focused row is specified by the FocusedRowIndex property.

If multiple row selection is enabled, you can use the DeleteSelection method to delete all selected rows in a single operation.


TcxCustomDataController.DeleteRecord

TcxCustomDataController          See Also

Deletes a data record referenced by record index (unbound and provider modes only).

procedure DeleteRecord(ARecordIndex: Integer);

Description

Use the DeleteRecord method to delete a data record referenced by a record index in provider and unbound modes.  The record index is a unique value assigned to every data record in a data controller.  The visual record order can change due to sorting applied.  However, record indexes always refer to the same data regardless of record positions.

See the DeleteFocused and DeleteSelection methods to delete the focused and selected rows respectively.  They allow you to delete data records and grouping rows in all loading modes.


TcxCustomDataController.DeleteSelection

TcxCustomDataController          See also

Deletes selected rows from a data controller.

procedure DeleteSelection; virtual;

Description

The DeleteSelection method deletes all selected rows (data records and grouping rows) from your data controller.

The MultiSelect property specifies whether multiple rows selection is enabled.  If MultiSelect is False, there can be only one selected row (the focused row).  In this mode, the SyncSelected method allows you to specify whether the focused record should be selected.

If MultiSelect is True, you are able to select multiple rows by the ChangeRowSelection, SelectRows and SelectAll methods.


TcxCustomDataController.Edit

TcxCustomDataController          See Also

Activates edit mode for the focused record.

procedure Edit; virtual;

Description

The Edit method activates edit mode in your data controller.   It sets the dceEdit flag in the EditState property.

In the bound mode (implemented by the TcxDBDataController class), the data controller represents dataset records (a TDataSet descendant).  In this case, the Edit method calls the Edit method of the underlying dataset to activate edit mode for the focused record.  The TDataSet.Edit method fires the TDataSet.BeforeEdit and TDataSet.AfterEdit events.

In unbound and provider modes, it is not required to call Edit before modifying field values of the focused record.  You can use the Values property to change fields of any record at any time.  However, the Edit method can be used to produce the effect of starting editing data by the end-user via an external control (ExpressQuantumGrid or ExpressQuantumTreeList).


TcxCustomDataController.EndUpdate

TcxCustomDataController          See Also

Re-enables sending update notifications by the data controller after they were suspended by calling BeginUpdate.

procedure EndUpdate;

Description

Use the EndUpdate method to re-enable sending update notifications by the data controller after BeginUpdate was called.  Use the BeginUpdate and EndUpdate methods when you perform a series of operations, each of which leads to refreshing data in the data controller (inserting records, modifying record fields).  See the BeginUpdate description for more information.

Note:	Do not call the Append, Insert, Post, and SetEditValue methods within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.


TcxCustomDataController.EndFullUpdate

TcxCustomDataController

Unlocks the data controller and its associated visual object after the BeginFullUpdate method call.

procedure EndFullUpdate; virtual;

Description

Use the EndFullUpdate method to unlock the data controller and the object that displays its data after they have been locked using the BeginFullUpdate method.  Note that the number of BeginFullUpdate method calls must match the number of EndFullUpdate method calls to ensure unlocking.  Thus, it is recommended to use try…finally statements when performing a batch update.

Note:	Do not call the Append, Insert, Post, and SetEditValue methods within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.


TcxCustomDataController.EndUpdateFields

TcxCustomDataController

Re-enables field update notifications after the BeginUpdateFields method call.

procedure EndUpdateFields;

Description

This method is for internal use only.  You will have no need to use it in applications.


TcxCustomDataController.FindRecordIndexByText

TcxCustomDataController          See Also

Returns the record index of the record matching the supplied text within a particular field.

function FindRecordIndexByText(AStartRecordIndex, AItemIndex: Integer; const AText: string; APartialCompare, ACircular, AForward: Boolean): Integer; virtual;

Description

The FindRecordIndexByText function returns the record index of the first record that contains a field value matching the specified AText.  This can be used to implement incremental search functionality, i.e. to locate specific records by text they contain.  The record index retrieved by the function can be used, for instance, to focus a record by the FocusedRecordIndex property.

If a record containing specified text couldn’t be found, the function returns –1.

FindRecordIndexByText iterates records matching the current filter criteria.  The search starts from the record addressed by the AStartRecordIndex parameter, which specifies the record index (the record’s position in the data source).

The search is performed against the item specified by the AItemIndex parameter.  In the ExpressQuantumGrid control, you can use the TcxCustomGridTableItem.Index property value for this parameter.

The AForward parameter determines the search direction.  It specifies whether to search forwards or backwards.

Setting the ACircular parameter to True ensures that the search will cycle when reaching the first record (if AForward is False) and the last record (if AForward is True).  If ACircular is False, the search stops once it reaches these records.

The function compares strings without case sensitivity.  The APartialCompare parameter allows you to specify whether the text being searched must match the display text of a field partially or entirely.  If APartialCompare is True, the function is successful if the search text matches the starting characters of the field text.  If APartialCompare is False, strings to compare must be identical.

In ExpressQuantumGrid, you can use the View’s Controller.IncSearchingText property to start the incremental search.


TcxCustomDataController.FocusDetails

TcxCustomDataController          See Also

Recursively focuses records in all the active details which correspond to the specified master record.

procedure FocusDetails(ARecordIndex: Integer);

Description

The FocusDetails method focuses records in all the active details which correspond to the specified master record.  The master record is identified by the ARecordIndex parameter which specifies its record index (the position of the record in the underlying data source).  This method recursively traverses all the active details for which detail data controllers have been created and focuses records within these active details (if they’re not focused).

This method is for internal use only.


TcxCustomDataController.ForEachRow

TcxCustomDataController          See also         Example1          Example2

Calls a custom procedure for each row in a data controller.

TcxDataControllerEachRowProc = procedure(ARowIndex: Integer; ARowInfo: TcxRowInfo) of object;

procedure ForEachRow(ASelectedRows: Boolean; AProc: TcxDataControllerEachRowProc); virtual;

Description

Use the ForEachRow method to iterate selected or all rows available in your data controller.  Call a custom procedure (callback function) for each row.  The ASelectedRows parameter specifies whether to process selected or all rows.  The callback function is passed as the AProc parameter.  The function prototype is determined by the TcxDataControllerEachRowProc type.

The ForEachRow method can be used in all loading modes (unbound, provider, bound and Grid modes).  When iterating rows in Grid mode, the ForEachRow method focuses a row and then calls the specified callback function.  In other modes, focus is not affected by ForEachRow.

Use the RowCount property to determine the total number of rows.  It takes into account data records and grouping rows which are visible or potentially visible by scrolling (i.e. not hidden in a collapsed group).  You can use the MakeRecordVisible method first to make a particular record visible if it is hidden within a collapsed group.

The number of selected rows is determined by the GetSelectedCount function.


TcxCustomDataController.GetDetailDataController

TcxCustomDataController          See also

Returns a clone of the detail data controller associated with a specific record in the current master data controller.

function GetDetailDataController(ARecordIndex: Integer; ARelationIndex: Integer): TcxCustomDataController;

Description

This method is applied to a non-pattern master data controller, i.e. to the master data controller whose IsPattern function returns False.

Use the GetDetailDataController function to return a clone of the detail data controller associated with a specific record in the current master data controller.  The master record is identified by the ARecordIndex parameter, which specifies its record index (the position of the record in the underlying data source).

It is possible to set up several master-detail relationships for a single master data controller.  In ExpressQuantumGrid, you usually create a structure of grid levels/Views to represent master-detail relationships.  Every Grid View is linked to the corresponding data controller providing data to display.  The following screenshot shows the Structure Navigator with a MasterTableView for which two master-detail relationships are created.  The first relationship is between MasterTableView and DetailTableView1.  The second relationship is between MasterTableView and DetailTableView2.

The ARelationIndex parameter specifies the zero-based index of a master-detail relationship for the current data controller.  For the data controller of the MasterTableView in the image above, ARelationIndex can vary from 0 to 1.

The GetDetailDataController function can be used when populating detail data controllers in unbound mode.  See the example below.

For information on representing master-detail relationships via data controllers, see the TcxCustomDataController topic.

Consider an example of displaying a master-detail relationship in ExpressQuantumGrid in unbound mode.  The FMasterTableView and FDetailTableView Views represent master and detail Views respectively.  The detail View contains three columns.

It is assumed that the master View contains only two records.  Therefore, only two detail clones of the FDetailTableView View corresponding to these records exist.  The following code shows how to populate both clones with data.  The first detail clone will contain two records (the RecordCount property is set to 2), the second one will contain only one record.

//Delphi

var

  I: Integer;

  ADetDataController: TcxCustomDataController;

//...

  with FMasterTableView.DataController do

  begin

    BeginUpdate;

    try

      for I := 0 to RecordCount - 1 do

      begin

        ADetDataController := GetDetailDataController(I, 0);

        with ADetDataController do

        begin

          BeginUpdate;

          try

            case I of

              0:

              begin

                RecordCount := 2;

                Values[0, 0] := 'Io';

                Values[0, 1] := 422;

                Values[0, 2] := 1.77;

                Values[1, 0] := 'Europa';

                Values[1, 1] := 671;

                Values[1, 2] := 3.55;

              end;

              1:

              begin

                RecordCount := 1;

                Values[0, 0] := 'Moon';

                Values[0, 1] := 384;

                Values[0, 2] := 27.32;

              end;

            end;

          finally

            EndUpdate;

          end;

        end;

      end;

    finally

      EndUpdate();

    end;

  end;

//C++ Builder

  TcxCustomDataController * AMasterDataController =    FMasterTableView->DataController;

  AMasterDataController->BeginUpdate();

  try {

    for(int I = 0; I < AMasterDataController->RecordCount; I++) {

      TcxCustomDataController * ADetailDataController =        AMasterDataController->GetDetailDataController(I, 0);

      ADetailDataController->BeginUpdate();

      try {

        switch(I) {

          case 0:

            ADetailDataController->RecordCount = 2;

            ADetailDataController->Values[0][0] = "Io";

            ADetailDataController->Values[0][1] = 422;

            ADetailDataController->Values[0][2] = 1.77;

            ADetailDataController->Values[1][0] = "Europa";

            ADetailDataController->Values[1][1] = 671;

            ADetailDataController->Values[1][2] = 3.55;

            break;

          case 1:

            ADetailDataController->RecordCount = 1;

            ADetailDataController->Values[0][0] = "Moon";

            ADetailDataController->Values[0][1] = 384;

            ADetailDataController->Values[0][2] = 27.32;

            break;

        }

      } __finally {

        ADetailDataController->EndUpdate();

      }

    }

  } __finally {

    AMasterDataController->EndUpdate();

  }


TcxCustomDataController.GetMasterDataController

TcxCustomDataController          See also

Returns the master data controller for the current detail data controller.

function GetMasterDataController: TcxCustomDataController; virtual;

Description

A single master-detail relationship is represented by two data controllers (master and detail).  The GetMasterDataController function returns the master data controller associated with the current detail data controller.

See the TcxCustomDataController topic for more information on representing master-detail relationships using data controllers.


TcxCustomDataController.GetMasterRecordIndex

TcxCustomDataController          See also

Returns the record index of the master record corresponding to the current clone of a detail data controller.

function GetMasterRecordIndex: Integer; virtual;

Description

The GetMasterRecordIndex method can be called only for clones of a detail data controller.  It returns the record index of the master record corresponding to the current clone of your detail data controller.

For pattern detail and master data controllers, GetMasterRecordIndex returns –1.  See the TcxCustomDataController description for information on patterns, clones, and record indexes.

The GetMasterRecordIndex method can be used when implementing a master-detail relationship in provider mode.  See the Provider Mode: Master-Detail document in the ExpressQuantumGrid help system for more information.

To get a master data controller for the current detail, see the GetMasterDataController function.


TcxCustomDataController.GetPatternDataController

TcxCustomDataController          See also

Returns a pattern data controller for a detail data controller.

function GetPatternDataController: TcxCustomDataController;

Description

The GetPatternDataController function can be applied only to detail data controllers.  Data controllers, which are not details, have no patterns at all.

The function returns a pattern data controller for the current detail data controller.

A pattern data controller does not contain data and is only used to provide settings when creating its clones (instances of the detail data controller corresponding to specific records in a master data controller).  Refer to the TcxCustomDataController description for more information on patterns and clones.  To know whether the current data controller is a pattern or a non-pattern, use the IsPattern property.

If the current data controller is a pattern, GetPatternDataController returns a reference to the current object.

Changing settings of a pattern data controller does not affect its existing clones.  However, you can call the ClearDetails method of a master data controller to recreate detail clones based on the settings of the pattern detail data controller.

To return a master data controller, use the GetMasterDataController function.


TcxCustomDataController.GetRowDisplayText

TcxCustomDataController          See Also

Returns the display text for an item of a specific row.

function GetRowDisplayText(const ARowInfo: TcxRowInfo; AItemIndex: Integer): string;

Description

The GetRowDisplayText function allows you to obtain the display text for a specific row (data records and grouping rows).  The row is identified by the ARowInfo parameter.  It specifies a TcxRowInfo object that can be obtained using the GetRowInfo function.

The AItemIndex parameter specifies the index of the item for which to return the display text.  It identifies the position of the item within the collection of all items.  In the ExpressQuantumGrid control, you can use the TcxCustomGridTableItem.Index property value for this parameter.

Note that if the ARowInfo parameter refers to a grouping row, the function returns the display text of the corresponding grouping item and ignores the AItemIndex parameter.

To get a variant value instead of its text representation, use the GetRowValue function.

If you only need to return the display text of data records (including records currently invisible because of filtering, for instance), you can use the DisplayTexts property.  This property does not return display texts for grouping rows.


TcxCustomDataController.GetRowIndexByRecordIndex

TcxCustomDataController          See Also

Returns the position of a data record in a data controller by its record index.

function GetRowIndexByRecordIndex(ARecordIndex: Integer; AMakeVisible: Boolean): Integer;

Description

Use the GetRowIndexByRecordIndex function to return the row index for a specific data record.  The function returns a value between 0 and RowCount – 1.

The data record is identified by the ARecordIndex parameter, which specifies the record index.  Record indexes vary from 0 to RecordCount – 1.

Record indexes define the order in which data records appear in the underlying data source.  Row indexes define the order in which rows (data records and grouping rows) should be displayed on screen.  This order depends on the grouping, filtering and/or sorting applied.  For more details on record and row indexes, refer to the TcxCustomDataController description.

Row indexes are assigned only to potentially visible rows (i.e. visible now or available by scrolling).  Rows collapsed within data groups have no row indexes.  If a particular data record is hidden within a collapsed group, you can make it visible by setting the AMakeVisible parameter to True.  In this case, GetRowIndexByRecordIndex expands the data group, which contains the record, reassigns row indexes to all potentially visible rows and then returns the row index for the required record.

If the record is hidden within a group and the AMakeVisible parameter is set to False, the function returns –1.  The function also returns –1 if the specified record does not match the current filter criteria and therefore cannot be displayed.

If a record is already visible, GetRowIndexByRecordIndex just returns its row index.  In this case, AMakeVisible is ignored.

GetRowIndexByRecordIndex does not affect focus.  See the FocusedRecordIndex and FocusedRowIndex properties to move focus to a specific record/row.

The row index can be used to:

-	get information on a row via the GetRowInfo and GetRowValue methods

-	select a row via ChangeRowSelection

Iterating though data records is performed differently in provider/unbound and bound modes.  In provider & unbound modes, you can use record indexes to access values of a specific record by the Values property.

In bound mode, you have to use methods provided by a TDataSet descendant associated with the data controller to navigate and change records.


TcxCustomDataController.GetRowInfo

TcxCustomDataController          See Also

Returns an object containing information on a particular row.

function GetRowInfo(ARowIndex: Integer): TcxRowInfo;

Description

The GetRowInfo function returns a TcxRowInfo structure containing information on a row (a potentially visible data record or a grouping row) at a particular position.  The row is addressed by the ARowIndex parameter, which also specifies its position within the data controller.  The total number of rows is determined by the RowCount property.  For more information on row indexes, see the TcxCustomDataController description.

The RowInfo object returned by the function describes the row’s record index, its group level and expansion state.

Several functions (for instance, GetRowDisplayText and GetRowValue) require the RowInfo object.

The following example tests whether a specific row is a grouping row:

//Delphi

function IsGroupingRow(ARowInfo: TcxRowInfo; ADataController: TcxCustomDataController): Boolean;

begin

  with ADataController do

    Result := ARowInfo.Level <> Groups.GroupingItemCount;

end;

//C++ Builder

bool IsGroupingRow(const TcxRowInfo & ARowInfo, TcxCustomDataController * ADataController) {

  return ARowInfo.Level != ADataController->Groups-> GroupingItemCount;

}


TcxCustomDataController.GetRowValue

TcxCustomDataController          See Also

Obtains the value for a particular row/item.

function GetRowValue(const ARowInfo: TcxRowInfo; AItemIndex: Integer): Variant;

Description

Use the GetRowValue function to obtain the value of a particular row item.  This method can be applied to potentially visible data records and grouping rows.  Such rows can be accessed by row indexes.

A row is identified by the ARowInfo parameter.  It specifies a TcxRowInfo object that you can obtain using the GetRowInfo function.

The AItemIndex parameter specifies the index of the item for which to return the value and identifies the position of the item within the collection of all items.  In the ExpressQuantumGrid control, you can use the TcxCustomGridTableItem.Index property value for this parameter.

Note that if the ARowInfo parameter refers to a grouping row, the function returns the value of the corresponding grouping item and ignores the AItemIndex parameter.

Use the GetRowDisplayText function to return an item’s display text instead of the variant value.

The Values property can be used to return values of specific data records even if they are currently invisible because of an applied filter.  This property does not allow you to return values of grouping rows because Values requires the record index as a parameter.


TcxCustomDataController.GetSelectedCount

TcxCustomDataController          See also          Example

Returns the number of selected rows.

function GetSelectedCount: Integer;

Description

The GetSelectedCount property returns the number of selected rows (data records and grouping rows) in the current data controller.

When the selection of multiple rows is disabled (the MultiSelect property is set to False), there can be only one selected row (equivalent to the focused row).  In this mode, GetSelectedCount returns 1.  However, you can call the SyncSelected method to unselect the focused row.  In this case, GetSelectedCount will return 0.

If the MultiSelect property is set to True, it is possible to have several selected rows in the data controller at once.

GetSelectedCount can be used in all loading modes (provider/unbound, bound and grid modes).  To access selected rows, you need to use the GetSelectedRowIndex method (in unbound/provider and default bound modes) or the GetSelectedBookmark function (in grid mode).


TcxCustomDataController.GetSelectedRowIndex

TcxCustomDataController          See also          Example

Returns the row index of a selected row.

function GetSelectedRowIndex(Index: Integer): Integer; virtual;

Description

The GetSelectedRowIndex function returns the row index of a selected row.  Row indexes define the order in which rows (data records and grouping rows) appear in the data controller.  See the TcxCustomDataController topic for information on row indexes.

The Index parameter addresses a particular selected row by its position within the collection of all selected rows.  Index can vary from 0 to GetSelectedCount – 1.

GetSelectedRowIndex returns valid row indexes for selected rows only in provider, unbound and default bound modes.

In Grid mode, the data controller does not load all records from the underlying dataset.  It loads only a fixed number of records at once into the memory buffer and its size is determined by the GridModeBufferCount property.  The data controller indexes only the records falling within the current buffer.  Other records are not assigned row & record indexes.  If a particular row does not belong to the current buffer, the GetSelectedRowIndex function returns –1.  Otherwise, GetSelectedRowIndex returns the row index of the selected record relative to the first record in the buffer.

To access all selected records in grid mode, use the GetSelectedBookmark function.

The row index retrieved by the method can be used to:

•	get information on a row using the GetRowInfo and GetRowValue functions

•	focus a row using the FocusedRowIndex property, etc.

To iterate selected rows, you can also use the ForEachRow method.  This can be applied in all loading modes.

The MultiSelect topic provides more information on selecting rows.


TcxCustomDataController.GotoBookmark

TcxCustomDataController          See Also

Locates the record referred to by the current bookmark.

procedure GotoBookmark;

Description

Use this method to jump to the record addressed by the current bookmark.  GotoBookmark may change the focused record specified by the FocusedRecordIndex property.  In ExpressQuantumGrid, this fires the View’s OnFocusedRecordChanged event.

If a bookmark is unavailable, GotoBookmark does nothing.  Use the IsBookmarkAvailable function to test whether a bookmark exists.

To create a bookmark, use the SaveBookmark method.  See the SaveBookmark topic for information on maintaining bookmarks.


TcxCustomDataController.GotoFirst

TcxCustomDataController          See Also

Moves focus to the first visible row.

procedure GotoFirst;

Description

The GotoFirst method focuses the first visible row within a data controller.

In Grid mode implemented by the TcxDBDataController class, GotoFirst calls the dataset’s First method.

The current focused row is addressed by the FocusedRowIndex property.  You can retrieve information on a particular row using the GetRowInfo function.

See the Record Navigation topic for more information.


TcxCustomDataController.GotoLast

TcxCustomDataController          See Also

Moves focus to the last visible row.

procedure GotoLast;

Description

The GotoLast method focuses the last visible row within a data controller.

In Grid mode implemented by the TcxDBDataController class, GotoLast calls the dataset’s Last method.

The current focused row is addressed by the FocusedRowIndex property.  You can retrieve information on a particular row with the help of the GetRowInfo function.

See the Record Navigation topic for more information.


TcxCustomDataController.GotoNext

TcxCustomDataController          See Also

Moves focus to the next visible row.

procedure GotoNext;

Description

The GotoNext method focuses the row following the current one.

In Grid mode implemented by the TcxDBDataController class, GotoNext calls the dataset’s Next method.

The current focused row is addressed by the FocusedRowIndex property.  You can retrieve information on a particular row using the GetRowInfo function.

See the Record Navigation topic for more information.


TcxCustomDataController.GotoPrev

TcxCustomDataController          See Also

Moves focus to the previous visible row within a data controller.

procedure GotoPrev;

Description

The GotoPrev method focuses the row preceding the current one.

In Grid mode implemented by the TcxDBDataController class, GotoPrev calls the dataset’s Prior method.

The current focused row is addressed by the FocusedRowIndex property.  You can retrieve information on a specific row via the GetRowInfo function.

See the Record Navigation topic for more information.


TcxCustomDataController.Insert

TcxCustomDataController          See Also

Inserts a new record in a data controller.

procedure Insert; virtual;

Description

The Insert method inserts a new record in a data controller.  This method sets the dceInsert flag in the EditState property.

In bound mode, when the data controller (TcxDBDataController) represents dataset records, the Insert method merely calls the TDataSet.Insert method.  It performs the following:

1.	Opens a new, empty dataset record

2.	Sets the active record to the new record

The TDataSet.Insert method fires the TDataSet.BeforeInsert and TDataSet.AfterInsert events, thus allowing you to perform actions before and after insert mode is activated.

After the record becomes active, a user can set its field values and then post those changes.  To set values via code, use the methods and properties of the dataset (for instance, TDataSet.FieldValues).  To post changes, see the Post method (you can also use the Post method provided by the dataset).

In provider and unbound modes, Insert behaves in a similar manner:  It inserts a new record at the position specified by the currently focused record and then sets focus to it.  In these modes, you should use the Values property to set field values.  This property needs record and item indexes to identify a particular cell.  The Insert method does not return the index of the inserted record.  To work around this, use the FocusedRecordIndex property after inserting.

If a record is inserted using the Insert method, it is not immediately posted to the data source. Thus, you can cancel the insertion as long as posting is not performed. If canceling, the inserted record is deleted and all changes are lost. End-users can perform this by pressing the Esc key. The Cancel method enables you to cancel changes via code.

Note:	Do not call the Insert method within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.

In provider and unbound modes, you can use the InsertRecord method to add a new record.  InsertRecord retrieves the record index of the new record and this can be used to access its field values via the Values property.  The record added by InsertRecord does not require posting.  Also such a record cannot be discarded by calling the Cancel method.


TcxCustomDataController.InsertRecord

TcxCustomDataController          See Also

Inserts a new empty record in the current data controller.

function InsertRecord(ARecordIndex: Integer): Integer;

Description

Use the InsertRecord method to insert a new empty record in the current data controller in unbound and provider modes.  In bound mode, when the data controller (TcxDBDataController) provides dataset records, you should use the Insert method instead.

A new record is inserted at the position specified by the ARecordIndex parameter.  InsertRecord returns the record index of the inserted record.  The record index can be used to access field values of the record via the Values property.

In provider mode, you need to implement the AppendRecord and InsertRecord methods of your custom data source to allow record insertions.  The AppendRecord method of your custom data source is automatically called when you insert a record in an empty data controller.


TcxCustomDataController.IsBOF

TcxCustomDataController          See Also

Returns a value indicating whether the first visible row is focused.

function IsBOF: Boolean;

Description

The IsBOF function returns True if the first visible row is focused.  Otherwise, the function returns False.

In Grid mode implemented by the TcxDBDataController class, IsBOF returns the result of the TDataSet.BOF property.

In other loading modes (unbound, provider and default bound modes), IsBOF returns True if the FocusedRowIndex property is set to 0 or if there are no rows at all.

If you need to know whether the first data record is focused in bound mode, you should use the dataset’s BOF property.

The IsBOF and IsEOF functions take the order in which rows are displayed on screen into account.  A row represents a potentially visible data record or a grouping row, which can be focused, selected and deleted.  The order in which rows are displayed on screen is based on the sorting, filtering and grouping applied.

The difference between rows and records is described in the TcxCustomDataController topic.


TcxCustomDataController.IsBookmarkAvailable

TcxCustomDataController          See Also

Indicates whether there is a bookmark available (created by the SaveBookmark method).

function IsBookmarkAvailable: Boolean; virtual;

Description

Use the IsBookmarkAvailable function to test whether the SaveBookmark method was used to create a bookmark and that the bookmark still exists.  If the bookmark is available, you can jump to the record to which it refers using the GotoBookmark method.

A bookmark can be unavailable for the following reasons:

•	the SaveBookmark was not called

•	the bookmark was cleared explicitly by the ClearBookmark method

•	the bookmark was cleared implicitly when the record referred to by the bookmark was deleted

For more details on bookmarks, refer to the SaveBookmark description.


TcxCustomDataController.IsDetailMode

TcxCustomDataController          See also

Returns a value indicating whether the current data controller is a detail of another data controller.

function IsDetailMode: Boolean; virtual;

Description

A single master-detail relationship between data sources is established using two detail data controllers: master and detail.

The IsDetailMode function returns True for detail data controllers, i.e. for data controllers associated with a master data controller.

The function returns False for data controllers which have no master data controller.

See the TcxCustomDataController topic for more information on master-detail relationships.


TcxCustomDataController.IsEOF

TcxCustomDataController          See Also

Returns a value indicating whether the last visible row is focused.

function IsEOF: Boolean;

Description

The IsEOF function returns True if the last visible row is focused.  Otherwise, the function returns False.

In Grid mode implemented by the TcxDBDataController class, IsEOF returns the result of the TDataSet.EOF property.

In other loading modes (unbound, provider and default bound modes), IsEOF returns True if the FocusedRowIndex property specifies the RowCount – 1 value or if there are no rows at all.

If you need to know whether the last data record is focused in bound mode, you should use the dataset’s EOF property.

The IsBOF and IsEOF functions take the order in which rows are displayed on screen into account.  A row represents a potentially visible data record or a grouping row, which can be focused, selected and deleted.  The order in which rows are displayed on screen is based on the sorting, filtering and grouping applied.

The difference between rows and records is described in the TcxCustomDataController topic.


TcxCustomDataController.IsGridMode

TcxCustomDataController          See Also

Indicates whether your data controller is working in GridMode.

function IsGridMode: Boolean;

Description

The IsGridMode function returns a value indicating Grid Mode is in effect.

Grid Mode is a special bound loading mode implemented by the TcxDBDataController class.  It provides more speed for huge datasets by loading only a fixed number of records into memory at once.  For TcxCustomDataController objects, IsGridMode always returns False.  For TcxDBDataController objects, the IsGridMode function returns True if:

•	the DataModeController.GridMode property is set to True

•	the underlying dataset is non-unidirectional

•	grouping data is not applied

In other cases, IsGridMode returns False, thus indicating that Grid Mode is currently disabled.  When Grid Mode is disabled, the data controller loads all records from the dataset into the memory buffer.

To enable Grid Mode for a data-aware data controller, set its DataModeController.GridMode property to True.  However, if the dataset is unidirectional (the dataset represents a descendant of the TCustomSQLDataSet class), Grid mode is not activated even if the GridMode property is set to True.  See the TDataSet.IsUniDirectional property to know whether the dataset is unidirectional.

Grouping data is not supported in grid mode.  If you group data when the GridMode property is set to True, Grid Mode is automatically disabled and the IsGridMode function returns False.  When you clear grouping, Grid Mode is automatically re-enabled (IsGridMode will return True).

For more information on Grid Mode, see the DataModeController.GridMode property description and the documents in the Base Concepts and Task Based Help sections.


TcxCustomDataController.IsRowSelected

TcxCustomDataController          See also

Returns a value indicating whether a particular row is selected.

function IsRowSelected(ARowIndex: Integer): Boolean;

Description

The IsRowSelected function returns True if the particular row (a data record or a grouping row) is selected.  Otherwise, it returns False.  The ARowIndex parameter specifies a row by its index, i.e. its position within the data controller.

The number of selected rows is determined by the GetSelectedCount function.  To access selected rows, you can use the GetSelectedRowIndex function (in provider, unbound and default bound modes) and GetSelectedBookmark (in Grid mode).

To iterate selected rows, the ForEachRow method can be applied.

See the MultiSelect property for more details.


TcxCustomDataController.LoadFromStream

TcxCustomDataController          See Also           Example

Populates your data controller with data from a stream.

procedure LoadFromStream(AStream: TStream);

Description

The LoadFromStream method allows you to restore data (record count and field values) from a stream previously stored by the SaveToStream method.  This method replaces the existing data in the data controller.

LoadFromStream and SaveToStream can be used only in unbound mode.

The AStream parameter represents a TStream descendant from which data is loaded.

The number of items in the current data controller and in the stream must be identical.  Also, the data controller validates the data types of the values being loaded from the stream.  These values must match the data types of items in the current data controller.  If these checks fail, loading from the stream stops and the EcxInvalidDataControllerOperation exception with the message "Invalid stream format" is raised.

After checking stream validity, the method assigns the appropriate value to the RecordCount property and loads values for records and items.


TcxCustomDataController.MakeRecordVisible

TcxCustomDataController          See Also

Makes a record potentially visible by expanding the data group owning it.

procedure MakeRecordVisible(ARecordIndex: Integer);

Description

The MakeRecordVisible method makes the record specified by the ARecordIndex parameter potentially visible (visible by scrolling).  When grouping is applied, the data controller locates and expands the data group owning the record.  If the record is already potentially visible, MakeRecordVisible performs no action.

The record to display is addressed by the ARecordIndex parameter, which specifies the record index, i.e. its position within a data source.

You cannot use this method to make your record visible if it does not meet the current filter criteria.  To test whether a record meets the filter criteria, see the FilteredIndexByRecordIndex property.

MakeRecordVisible does not move the focus to the record.  To make a record visible and focused, use the FocusedRecordIndex property.


TcxCustomDataController.Post

TcxCustomDataController          See Also

Posts a modified record to a data source.

procedure Post; virtual;

Description

Use the Post method to write a modified record to a data source.  You should use this method if you need to post changes to the record after calling Insert, Append or Edit.  If you do not want to post the changes, use the Cancel method instead.

In bound mode, implemented by the TcxDBDataController class, Post calls the Post method of the underlying dataset.

Note:	Do not call the Post method within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.

In unbound and provider modes, you should use Post to post your modified record after calling Insert, Append or Edit.  However, in these modes, you can change records directly via the Values property without activating edit mode.  In this case, Post should not be used.

When the end-user starts modifying a data record in ExpressQuantumGrid or ExpressQuantumTreelist, for instance, edit mode is automatically activated.  In edit mode, users can freely change field values and subsequently restore old values by pressing the Esc key.  However, when a different record is focused, the data controller’s Post method is called implicitly.


TcxCustomDataController.RefreshExternalData

TcxCustomDataController

Forces a data controller to reload data from a data source.

procedure RefreshExternalData; virtual;

Description

Use the RefreshExternalData method to force your data controller to reload all records from a data source.  This ensures that the data controller contains the latest data and for displaying by a bound control.  For instance, you can call RefreshExternalData if another application has changed data in the current data source.

In unbound and provider modes, this method does nothing.  In bound mode implemented by TcxDBDataController, RefreshExternalData merely calls the Refresh method of the underlying dataset.

Note that the Refresh method does not work for all TDataSet descendants.  In particular, TQuery components do not support the Refresh method if the query is not "live".  To refresh a static TQuery, close and reopen the dataset.

For huge datasets, data reloading can consume much time.  If you need to work with large datasets, you should consider activating Grid Mode.  In this bound mode, the data controller loads only a fixed number of records at once, thus providing faster loading, reloading, navigating and displaying of records.

The data controller normally preserves the selected record and bookmarks after data is reloaded from the dataset.  However, they may not be restored correctly if records were deleted from the dataset by another application.


TcxCustomDataController.RestoreKeys

TcxCustomDataController          See Also

Restores the record identifiers of the expanded master rows, grouping rows and selected rows.

procedure RestoreKeys;

Description

Use the RestoreKeys method to restore the record identifiers of the master rows, grouping rows and selected rows.  Unlike record handles and indexes, record identifiers are not changed when the number and order of records within a data set changes (see the TcxCustomDataSource class description for information on record indexes and record handles).

The record identifiers are generated via the GetRecordId method which accepts a record handle as its parameter.

Call the RestoreKeys method after making changes to a data set (for instance, before deleting a record).  This will restore the expansion and selection state within the data controller when changing the order of records within the associated data set.  Call the SaveKeys method to save a record’s state.


TcxCustomDataController.SaveBookmark

TcxCustomDataController          See Also

Saves the focused record as a bookmark.

procedure SaveBookmark;

Description

The SaveBookmark method saves the position of the currently focused record as a bookmark thus allowing you to return to this record later using the GotoBookmark procedure.

A bookmark is a reference to a record in a data controller.  SaveBookmark allows you to save a bookmark for the current record.  While the bookmark is available, you can use the GotoBookmark procedure to jump back to this record later at any time.

The data controller maintains only one bookmark.  It is supported though by all loading modes (unbound, provider, bound and grid mode).  In unbound, provider and default bound modes, a bookmark represents a record index of a record.  In grid mode, a bookmark represents a TBookmarkStr object returned by the TDataSet.Bookmark property.

You do not need to operate with bookmarks directly.  Instead you should use the following methods:

•	SaveBookmark.  Saves a bookmark for the current record.

•	GotoBookmark.  The method jumps to the record referred by the current bookmark.

•	ClearBookmark.  Removes the bookmark stored by SaveBookmark.

•	IsBookmarkAvailable.  Indicates whether a bookmark exists.

If you delete a bookmarked record, the bookmark will be deleted also.

Bookmarks created by the SaveBookmark method are used only for dataset navigation, i.e. you can store the current record position as a bookmark and then jump to this position at any time using GotoBookmark.  In ExpressQuantumGrid, for instance, the SaveBookmark and GotoBookmark methods are available as navigator control buttons within in a Grid View.

In Grid Mode, the data controller maintains another type of bookmark – bookmarks for selected records.  They are created automatically when you select record(s) and they provide the only way to access selected records in grid mode.  The GetSelectedBookmark function allows you to access the bookmarks and selected records.

Selection bookmarks do not affect bookmarks created by the SaveBookmark method and vice versa.  Bookmarks for selected and focused rows are created independently and are used for different purposes.

The data controller preserves bookmarks and the selected record after data is reloaded from the dataset.  However, it may not correctly restore them if dataset records were deleted by another application.


TcxCustomDataController.SaveKeys

TcxCustomDataController          See Also

Saves the record identifiers of the expanded master rows, grouping rows and selected rows.

procedure SaveKeys;

Description

Use the SaveKeys method to save the record identifiers of the master rows, grouping rows and selected rows.  Unlike record handles and record indexes, record identifiers are not changed when the number and order of records within a data set changes (see the TcxCustomDataSource class description for information on record indexes and record handles).

The record identifiers are generated via the GetRecordId method which accepts record handles as its parameter.

Call the SaveKeys method before making changes to a data set (for instance, before deleting a record).  This will keep the expansion and selection state within the data controller when changing the order of records within the associated data set.  Call the RestoreKeys method to restore the record state, saved via the SaveKeys method.


TcxCustomDataController.SaveToStream

TcxCustomDataController          See Also           Example

Saves data provided by the current data controller to a stream.

procedure SaveToStream(AStream: TStream);

Description

The SaveToStream method allows you to save data from the current data controller to the stream specified by the AStream parameter.  It saves the number of items, their data types, the number of records and all values.

You can restore data from a stream later using the LoadFromStream method.

LoadFromStream and SaveToStream can be used only in unbound mode.


TcxCustomDataController.SelectAll

TcxCustomDataController          See also

Selects all potentially visible rows in the current data controller.

procedure SelectAll; virtual;

Description

The SelectAll method selects all potentially visible rows (data records and grouping rows currently visible or available via scrolling). This method is in effect only when MultiSelect property is set to True.

You can select only potentially visible rows.  Thus, rows belonging to a data group being collapsed are automatically unselected.

To select individual rows, see the ChangeRowSelection and SelectRows methods.

Controls using data controllers to retrieve data from a data source provide events to control row selection.  In ExpressQuantumGrid, for instance, you can handle a View’s OnSelectionChanged event for this purpose.

The MultiSelect topic provides more information on selecting rows in a data controller.


TcxCustomDataController.SelectRows

TcxCustomDataController          See also

Selects a continuous range of rows.

procedure SelectRows(AStartRowIndex, AEndRowIndex: Integer);

Description

Use the SelectRows method to select a continuous range of rows (potentially visible data records and grouping rows).  The starting and ending row indexes of the range are specified by the AStartRowIndex and AEndRowIndex parameters.

The total number of rows is specified by the RowCount property.

In order to enable selection of more than a single row, you should set the MultiSelect property to True.  Refer to the description of this property for more information.

The ChangeRowSelection method lets you change the selection state of individual rows.  See the SelectAll method to select all rows.

Controls using data controllers to retrieve data from a data source provide events to control row selection.  In ExpressQuantumGrid, for instance, you can handle a View’s OnSelectionChanged event for this purpose.

You can select only potentially visible rows.  Thus, rows belonging to a data group being collapsed are automatically unselected.


TcxCustomDataController.SetEditValue

TcxCustomDataController

Sets the value of a specific item in the record currently being edited.

type

  TcxDataEditValueSource = (evsValue, evsText, evsKey);

function SetEditValue(AItemIndex: Integer; const AValue: Variant; AEditValueSource: TcxDataEditValueSource): Boolean; virtual;

Description

Use the SetEditValue function to change dataset values programmatically.  The AItemIndex parameter specifies the record’s field whose value will be changed.  The field is specified by the index of the corresponding item (a Table View column, a card row, etc).  The field’s value to be assigned should be passed as the Value parameter.  The edit value’s type should be passed as the AEditValueSource parameter.

Value	Meaning
evsValue	AValue the value to set the specified item to (used for binary data editing controls).
evsText	AValue represents the text representation of the specified item’s value (used for text editing controls).
evsKey	AValue represents the key field value of the specified item in the lookup data source (used for lookup controls).

The SetEditValue function returns True if the item’s value was set successfully.  Otherwise, False is returned.

Note:	Do not call the SetEditValue function within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.


TcxCustomDataController.SetValue

TcxCustomDataController

Sets the value in the specified record and item.

procedure SetValue(ARecordIndex, AItemIndex: Integer; const Value: Variant); virtual;

Description

Use the SetValue method to change dataset values programmatically.  The ARecordIndex and AItemIndex parameters specify the record and the field where to change the value.  The record is specified by its index while the field is specified by the index of the corresponding item (a Table View column, a card row, etc).  The value to be assigned should be passed as the Value parameter.


TcxCustomDataController.SyncSelected

TcxCustomDataController          See also

Allows you to select/unselect the focused row when multiple row selection is disabled.

procedure SyncSelected(ASelected: Boolean);

Description

The SyncSelected method is in effect only when multiple row selection is disabled, i.e. when the MultiSelect property is set to False.

This method selects/unselects the focused record based on the ASelected parameter value.

By default, when multiple record selection is disabled, the focused and selected rows are equivalent and the GetSelectedCount function returns 1.

Calling the SyncSelected function set to False as the ASelected parameter unselects the focused row and GetSelectedCount returns 0.  Note that after you have moved focus to another row, it becomes selected again.

Calling the SyncSelected method with the ASelected parameter set to True restores the selection state of the focused row after it was cleared by using SyncSelected(False).

When data from the data controller is represented by a control (ExpressQuantumGrid, for instance), selected rows are painted in a different color so that they can be distinguished from regular records.  Unselecting the focused row clears highlighting and so it looks like no rows are selected.  Also, in this case, you are unable to access the selected record via the GetSelectedRowIndex or the GetSelectedBookmark function.


TcxCustomDataController.UpdateItems

TcxCustomDataController

Forces the current data controller to recreate items, and reload their values based on the bound data source.

procedure UpdateItems(AUpdateFields: Boolean);

Description

By default, a data controller receives change notifications from the bound data source, and automatically reloads all the records to update its internal data store.  However, this reload doesn’t happen if:

•	Data controller is in Smart Refresh mode.

•	Bound dataset’s ControlsDisabled property is set to True.

In these instances, you have to manually call the UpdateItems method to update items in the internal data store.

To reflect the data source’s structure changes in the internal store (for instance, when data fields are created, deleted or their types are modified), pass True as the AUpdateFields parameter.  Otherwise, you can pass False to avoid structure change verifications.


TcxCustomDataController.OnAfterCancel

TcxCustomDataController          See Also

Occurs after canceling the modifications to the active record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnAfterCancel: TcxDataControllerNotifyEvent;

Description

Write an OnAfterCancel event handler to perform specific actions after the changes to the active record are canceled.  The OnAfterCancel event is called by the Cancel method.

Handle the OnBeforeCancel event to respond before canceling the modifications to the active record.


TcxCustomDataController.OnAfterDelete

TcxCustomDataController          See Also

Occurs after deleting a record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnAfterDelete: TcxDataControllerNotifyEvent;

Description

Write an OnAfterDelete event handler to perform specific actions immediately after an application deletes the active record in a dataset.  The OnAfterDelete event is called by the DeleteRecord method.

Handle the OnBeforeDelete event to respond before a record is deleted.


TcxCustomDataController.OnAfterInsert

TcxCustomDataController          See Also

Occurs after inserting a new record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnAfterInsert: TcxDataControllerNotifyEvent;

Description

Write an OnAfterInsert event handler to perform specific actions immediately after inserting a record. The Insert and Append methods generate an OnAfterInsert event after inserting or appending a new record.

Handle the OnBeforeInsert event to respond before inserting a record.


TcxCustomDataController.OnAfterPost

TcxCustomDataController          See Also

Occurs after saving changes made to a record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnAfterPost: TcxDataControllerNotifyEvent;

Description

Write an OnAfterPost event handler to perform specific actions immediately after an application posts a change to the active record. The Post method generates the OnAfterPost event after a modification or insertion is made to a record.

Handle the OnBeforePost event to respond before posting the record changes to the data set.


TcxCustomDataController.OnBeforeCancel

TcxCustomDataController          See Also

Occurs before canceling modifications to the active record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnBeforeCancel: TcxDataControllerNotifyEvent;

Description

Write an OnBeforeCancel event handler to perform specific actions before the changes to the active record are canceled.  The OnBeforeCancel event is called by the Cancel method.

Handle the OnAfterCancel event to respond after canceling the modifications to the active record.


TcxCustomDataController.OnBeforeDelete

TcxCustomDataController          See Also

Occurs before deleting a record if working in unbound or provider mode.

type

  TcxDataDetailExpandedEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer) of object;

  TcxDataRecordNotifyEvent = TcxDataDetailExpandedEvent;

property OnBeforeDelete: TcxDataRecordNotifyEvent;

Description

Write an OnBeforeDelete event handler to perform specific actions before the changes to the active record are canceled.  The OnBeforeDelete event is called by the DeleteRecord method.

The ARecordIndex specifies the index of the record being deleted.

Handle the OnAfterDelete event to respond after deleting a record.


TcxCustomDataController.OnBeforeInsert

TcxCustomDataController          See Also

Occurs before inserting a new record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnBeforeInsert: TcxDataControllerNotifyEvent;

Description

Write an OnBeforeInsert event handler to perform specific actions before inserting a record. The Insert and Append methods generate an OnBeforeInsert event before inserting or appending a new record.

Handle the OnAfterInsert event to respond after inserting a record.


TcxCustomDataController.OnBeforePost

TcxCustomDataController          See Also

Occurs before saving changes made to the modified record if working in unbound or provider mode.

type

  TcxDataControllerNotifyEvent = procedure(ADataController: TcxCustomDataController) of object;

property OnBeforePost: TcxDataControllerNotifyEvent;

Description

Write an OnBeforePost event handler to perform specific actions before an application posts a change to the active record. The Post method generates the OnBeforePost event before a modification or insertion is made to a record.

Handle the OnAfterPost event to respond after posting the record changes to the data set.


TcxCustomDataController.OnCompare

TcxCustomDataController           Example 1          Example 2

Occurs when sorting records within a grid control.

type

  TcxDataControllerCompareEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex1, ARecordIndex2, AItemIndex: Integer; const V1, V2: Variant; var Compare: Integer) of object;

property OnCompare: TcxDataControllerCompareEvent;

Description

The OnCompare event occurs when values from two records are compared when sorting.  The ARecordIndex1 and ARecordIndex2 parameters identify indexes of records that must be compared.  The item for which the event is generated is specified by the AItemIndex parameter.  When working in a Grid View, the ItemIndex parameter defines the TcxGridColumn object position within the collection of owner columns.  When working in a Card View, the ItemIndex parameter defines the card row position of the TcxGridCardViewRow class.

Values are provided by V1 and V2 parameters.  To set the result of the compare operation you need to assign a negative value to Compare if V1<V2, zero if V1=V2 and a positive value if V1>V2.  You must always return the result of the compare operation.

The ADataController parameter specifies the data controller which fires the event.

Use the OnCompare event when you want to change the default comparison rules.  For instance, you can group records with NULL values and place them at the bottom of all records, then group other rows according to their values (the same year, month) and so on.


TcxCustomDataController.OnDataChanged

TcxCustomDataController

Occurs on changing data provided by the data controller.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnDataChanged: TNotifyEvent;

Description

The OnDataChanged event is fired when data provided by the data controller is changed.  In bound mode, the event is generated when data is posted to a data set.  In unbound mode it occurs when changing either data or the record count using the Values and RecordCount properties.

The Sender parameter specifies the data controller firing this event.


TcxCustomDataController.OnDetailCollapsed

TcxCustomDataController          See Also

Occurs after the details of a particular master record have been collapsed.

type

  TcxDataDetailExpandedEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer) of object;

property OnDetailCollapsed: TcxDataDetailExpandedEvent;

Description

Handle the OnDetailCollapsed event to perform specific actions after the details of a particular master record have been collapsed.

The ADataController parameter specifies the data controller which fires the event.

The ARecordIndex parameter specifies the index of the master record whose details have been collapsed.

Note:	The OnDetailCollapsed event is not fired when the AAllow parameter is set to False within the OnDetailCollapsing event handler.


TcxCustomDataController.OnDetailCollapsing

TcxCustomDataController          See Also

Occurs when the details of a particular master record are about to be collapsed.

type

  TcxDataDetailExpandingEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer; var AAllow: Boolean) of object;

property OnDetailCollapsing: TcxDataDetailExpandingEvent;

Description

Handle the OnDetailCollapsing event to control whether the details of a particular master record can be collapsed.

The ADataController parameter specifies the data controller which fires the event.

The ARecordIndex parameter specifies the index of the master record whose details are about to be collapsed.

Set the AAllow parameter to False to prevent the details of the master record from being collapsed.  Otherwise, the details will be collapsed (which is done by default).

Note:	The OnDetailCollapsed event is not fired when the AAllow parameter is set to False within the OnDetailCollapsing event handler.


TcxCustomDataController.OnDetailExpanded

TcxCustomDataController          See Also

Occurs after the details of a particular master record have been expanded.

type

  TcxDataDetailExpandedEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer) of object;

property OnDetailExpanded: TcxDataDetailExpandedEvent;

Description

Handle the OnDetailExpanded event to perform specific actions after the details of a particular master record have been expanded.

The ADataController parameter specifies the data controller which fires the event.

The ARecordIndex parameter specifies the index of the master record whose details have been expanded.

Note:	The OnDetailExpanded event is not fired when the AAllow parameter is set to False within the OnDetailExpanding event handler.


TcxCustomDataController.OnDetailExpanding

TcxCustomDataController          See Also

Occurs when the details of a particular master record are about to be expanded.

type

  TcxDataDetailExpandingEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer; var AAllow: Boolean) of object;

property OnDetailExpanding: TcxDataDetailExpandingEvent;

Description

Handle the OnDetailExpanding event to control whether the details of a particular master record can be expanded.

The ADataController parameter specifies the data controller which fires the event.

The ARecordIndex parameter specifies the index of the master record whose details are about to be expanded.

Set the AAllow parameter to False to prevent details of the master record from being expanded.  Otherwise, the details will be expanded (which is done by default).

Note:	The OnDetailExpanded event is not fired when the AAllow parameter is set to False within the OnDetailExpanding event handler.


TcxCustomDataController.OnFilterRecord

TcxCustomDataController

Fires when the data controller is about to perform internal filtering.

type

  TcxDataFilterRecordEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer; var Accept: Boolean) of object;

property OnFilterRecord: TcxDataFilterRecordEvent;

Description

Implement the OnFilterRecord event handler to provide custom filter conditions.

The ADataController parameter specifies the data controller;

The ARecordIndex parameter specifies the record index;

The Accept parameter specifies the visibility of the filtered records. Set the Accept parameter to True to make the filtered records visible or to False to hide the filtered records.


TcxCustomDataController.OnGroupingChanged

TcxCustomDataController          See Also

Occurs after data grouping is changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnGroupingChanged: TNotifyEvent;

Description

You can handle the OnGroupingChanged event to perform specific actions when data grouping is changed.  This involves changing grouping order or clearing grouping.

Group operations are implemented by the TcxDataControllerGroups class.  See the Groups attribute to access its functionality.

The Sender parameter specifies the data controller generating this event.


TcxCustomDataController.OnNewRecord

TcxCustomDataController          See Also

Fires when the data controller is about to focus a newly inserted record.

type

  TcxDataRecordNotifyEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex: Integer) of object;

property OnNewRecord: TcxDataRecordNotifyEvent;

Description

Implement the OnNewRecord event handler to perform specific actions before a newly inserted record receives focus.  This event is fired after the OnBeforeInsert event and prior to the OnAfterInsert event.

The ADataController parameter specifies the data controller.

The ARecordIndex parameter specifies the inserted record index.


TcxCustomDataController.OnSortingChanged

TcxCustomDataController          See Also

This event is fired after data sorting has changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnSortingChanged: TNotifyEvent;

Description

The OnSortingChanged event is generated after data sorting has changed.  In a grid control you can sort data by setting the item’s SortOrder property.

The data controller that fires this event is specified by the Sender parameter.

If the grid data controller works in Grid Mode, then you must handle this event in order to implement sorting within a View.


TcxCustomDataController.OnRecordChanged

TcxCustomDataController          See Also

Fires in response to data changes.

type

  TcxDataRecordChangedEvent = procedure(ADataController: TcxCustomDataController; ARecordIndex, AItemIndex: Integer) of object;

property OnRecordChanged: TcxDataRecordChangedEvent;

Description

The OnRecordChanged event is raised in response to data changing, as a result of either editing cell values in a data-aware control or the result of changing values via code.  The ADataController parameter represents the data controller whose data has been changed.  The ARecordIndex parameter identifies the record that has been altered.  If the AItemIndex parameter’s value is not –1, then this parameter identifies the column whose value has been changed.  If several columns’ values have been changed at once, this parameter returns –1.

Note that the OnRecordChanged event is raised only when working in provider or unbound mode.


TcxDataControllerOption
TcxDataControllerOption type

Enumerates the various options affecting the behavior of a data controller.

Unit

cxCustomData

type

  TcxDataControllerOption = (dcoAnsiSort, dcoCaseInsensitive, dcoAssignGroupingValues, dcoAssignMasterDetailKeys, dcoSaveExpanding, dcoSortByDisplayText, dcoFocusTopRowAfterSorting, dcoGroupsAlwaysExpanded, dcoImmediatePost, dcoInsertOnNewItemRowFocusing);

Description

The TcxDataControllerOption class describes options affecting aspects of the data controller’s behavior.  The following table lists the options:

Value	Description
dcoAnsiSort	If active, a grid control uses Windows locale settings to sort records.  This option is useful when grid cells contain native language text. Otherwise, strings are compared based on the 8-bit ordinal value of each character.
dcoCaseInsensitive	If set, sorting is case-insensitive.
dcoAssignGroupingValues	When a new record is inserted, this flag allows you to automatically assign the values of fields by which grouping, if any, is currently applied.  Values for these fields are obtained from the focused record. If the flag is not set, grouping fields are not assigned.
dcoAssignMasterDetailKeys	This flag is applied when inserting a new record within a detail dataset.  If active, it makes the data controller automatically assign the record fields specified by the DetailKeyFieldNames property.  The DetailKeyFieldNames property identifies the key fields in a detail dataset used to establish a master-detail relationship with a master dataset.
dcoSaveExpanding	If active, keeps the current expansion state of rows when dataset records are reloaded.  This also keeps the current selection of records in the current data controller when grouping is applied. If the flag is inactive, reloading dataset records clears the current expansion state and selection of rows.
dcoSortByDisplayText	By default, records are sorted by field values (edit values).  The dcoSortByDisplayText flag allows you to activate sorting by display text (the text displayed in item cells).  This can be useful when items are assigned to Lookup or ComboBox editors, for instance, when the edit value and text are different.
dcoFocusTopRowAfterSorting	If active, the top-most record gets focus after sorting.  Otherwise, focus remains at its prior position.
dcoGroupsAlwaysExpanded	If active, the grouped records always appear expanded.
dcoImmediatePost	If active, the changes to a field value (edit value) are immediately posted to a dataset.
dcoInsertOnNewItemRowFocusing	If active, a new record is inserted into the dataset as soon as the new item row receives focus.

The options of the data controller are set via its Options property.


TcxDataControllerOptions
TcxDataControllerOptions type

Represents a set of options controlling the behavior of a data controller.

Unit

cxCustomData

type

  TcxDataControllerOption = (dcoAnsiSort, dcoCaseInsensitive, dcoAssignGroupingValues, dcoAssignMasterDetailKeys, dcoSaveExpanding, dcoSortByDisplayText, dcoFocusTopRowAfterSorting, dcoGroupsAlwaysExpanded, dcoImmediatePost, dcoInsertOnNewItemRowFocusing);

  TcxDataControllerOptions = set of TcxDataControllerOption;

Description

The TcxDataControllerOptions class represents a set of options which control the behavior of a data controller.  The options are set via the TcxCustomDataController.Options property.


TcxDataSortOrder
TcxDataSortOrder type

Enumerates the available sort orders.

Unit

cxCustomData

type

  TcxDataSortOrder = (soNone, soAscending, soDescending)

Description

The TcxDataSortOrder type defines the available sort orders when sorting items by their values.  To sort items, use the TcxCustomGridTableItem.SortOrder property.  To reset the sorting order applied to items within a data controller, use the controller’s ClearSorting method.  The next table describes the possible item’s sort orders:

Value	Description
soNone	Data is not sorted.
soAscending	Data is sorted in ascending order.
soDescending	Data is sorted in descending order.


TcxCustomDataSummaryItem
TcxCustomDataSummaryItem Object

Hierarchy          Properties          Methods          See also

Represents an item within a grid control used to calculate summaries.

Unit

cxCustomData

TcxCustomDataSummaryItem = class(TCollectionItem);

Description

The TcxDataSummaryItem class provides the ItemLink property that determines the item within a grid control.  When data is presented using a grid view, an item designates a grid column of the TcxGridColumn class.

The TcxCustomDataSummaryItem is not used directly.  It represents common properties and methods for the TcxDataSummaryGroupItemLink and TcxDataSummaryItem classes.  TcxDataSummaryItem implements a single summary calculation.  It provides the type of operation to perform.  TcxDataSummaryGroupItemLink represents a grouping item in the summary group.

The TcxCustomDataSummaryItem class is derived from the TCollectionItem class.  This allows the storing of individual TcxCustomDataSummaryItem objects in a TCollection.


TcxCustomDataSummaryItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxCustomDataSummaryItem
TcxCustomDataSummaryItem Properties

TcxCustomDataSummaryItem          Legend

In TcxCustomDataSummaryItem

DataController

ItemLink


Methods for TcxCustomDataSummaryItem
TcxCustomDataSummaryItem Methods

TcxCustomDataSummaryItem          Legend

In TcxCustomDataSummaryItem

Assign

BeginUpdate

EndUpdate


TcxCustomDataSummaryItem.DataController

TcxCustomDataSummaryItem           See Also

Represents the data controller containing the collection of TcxCustomDataSummaryItem elements to which the current object belongs.

property DataController: TcxCustomDataController;

Description

Read the DataController property to gain access to the data controller that contains the collection to which the current object belongs.

ReadOnly Property


TcxCustomDataSummaryItem.ItemLink

TcxCustomDataSummaryItem           See Also

Specifies the item within a grid control.

property ItemLink: TObject;

Description

When grid data is presented by using a grid view, an item stands for a grid column.  In this case the ItemLink property specifies the object of the TcxGridColumn class.

The descendant TcxDataSummaryItem class uses ItemLink to store the item for which a summary is calculated.  Another descendant, TcxDataSummaryGroupItemLink, stores a grouping item in this property.  It is used in the summary group of the TcxDataSummaryGroup class.


TcxCustomDataSummaryItem.Assign

TcxCustomDataSummaryItem

Copies the contents of the Source parameter to the current object.

procedure Assign(Source: TPersistent); override;

Description

The Assign method sets the ItemLink property to point to the same item as the source ItemLink property.

The Source parameter determines the source item.


TcxCustomDataSummaryItem.BeginUpdate

TcxCustomDataSummaryItem           See Also

Suspends summary calculations until EndUpdate is called.

procedure BeginUpdate;

Description

The BeginUpdate method suspends summary calculations until EndUpdate is called.  Use BeginUpdate and EndUpdate to enclose the changes of the current object properties.


TcxCustomDataSummaryItem.EndUpdate

TcxCustomDataSummaryItem           See Also

Re-enables summary calculations after the BeginUpdate method is called.

procedure EndUpdate;

Description

Use the EndUpdate method to re-enable summary calculations after the BeginUpdate method is called.  Use BeginUpdate and EndUpdate to enclose the changes of the current object properties.


TcxDataControllerGroups
TcxDataControllerGroups Object

Hierarchy          Properties          Methods         See Also          Example

Encapsulates group operations in a grid control.

Unit

cxCustomData

TcxDataControllerGroups = class(TObject);

Description

The TcxDataControllerGroups class allows you to retrieve information about data groups within a grid control.

When you group data by items, a hierarchical structure of data groups is created and grid data is displayed at different levels.  To address an individual data group, you need to supply its index.  It defines the data group position in a grid control.  Data groups can have other data groups as children.  And every data group has a parent data group.  Data groups at level 0 have their parent reference set to –1.

Data group indexes are used to identify an individual data group.  For instance, to get a group summary value for a specific data group you can supply its index in the GroupSummaryValues property.  Refer to the appropriate example.

To identify the data group, which contains a specific row, use the DataGroupIndexByRowIndex property.  You can determine parent and child data groups via the ParentDataGroupIndex and ChildDataGroupIndex properties.

TcxDataControllerGroups implements the group reordering, collapsing and expanding.

The data controller contains the TcxCustomDataController.Groups member of the TcxDataControllerGroups type and this can help you manipulate data groups.


TcxDataControllerGroups Hierarchy
Hierarchy

TObject

     |

TcxDataControllerGroups


Properties for TcxDataControllerGroups
TcxDataControllerGroups Properties

TcxDataControllerGroups          Legend

In TcxDataControllerGroups

ChildCount

ChildDataGroupIndex

ChildRecordIndex

DataController

DataGroupIndexByRowIndex

FieldGroupIndex

GroupDisplayTexts

GroupingItemCount

GroupingItemIndex

GroupValues

ItemGroupIndex

Level

ParentDataGroupIndex


Methods for TcxDataControllerGroups
TcxDataControllerGroups Methods

TcxDataControllerGroups          Legend

In TcxDataControllerGroups

ChangeExpanding

ChangeGrouping

ClearGrouping

Create

FullCollapse

FullExpand

GetDataGroupIndexByGroupValue

HasAsParent

LoadRecordIndexes

LoadRecordIndexesByRowIndex


TcxDataControllerGroups.ChildCount

TcxDataControllerGroups           See Also

Returns the number of children for a specified data group.

type

  TcxDataGroupIndex = Integer;

property ChildCount[DataGroupIndex: TcxDataGroupIndex]: Integer;

Description

The DataGroupIndex parameter defines the index of a data group whose number of children is returned.  The ChildCount property returns the number of child data groups.  If a specified data group corresponds to the last grouping item it has no child data groups.  In this case the ChildCount property returns the number of data rows in the group.

To return the number of data groups at level 0 you should pass value –1 for the DataGroupIndex parameter.

Use the ChildDataGroupIndex property to iterate the child data groups.

The following image demonstrates five data groups.

For this sample grid control:

ChildCount[-1] returns 2 (there are data groups 0 and 2 at level 0)

ChildCount[0] returns 1 (data group 0 owns only data group 1)

ChildCount[4] returns 3 (data group 4 owns three data rows)

ReadOnly Property


TcxDataControllerGroups.ChildDataGroupIndex

TcxDataControllerGroups           See Also

Returns the index of a specific child data group.

type

  TcxDataGroupIndex = Integer;

property ChildDataGroupIndex[ParentDataGroupIndex: TcxDataGroupIndex; ChildIndex: Integer]: TcxDataGroupIndex;

Description

The ChildDataGroupIndex property returns the index of the specific child data group belonging to the parent data group addressed by the ParentDataGroupIndex parameter.  The number of children of the parent data group is defined via its ChildCount property.  The ChildIndex parameter can vary from 0 to (ChildCount – 1).  To return a child data group at level 0 you need to pass value –1 for the ParentDataGroupIndex parameter.  The ChildDataGroupIndex property returns –1 if it cannot locate a child for the parent data group.

The ParentDataGroupIndex property returns the index of the parent data group.

Consider a grid control displayed in the following image:

For this sample grid:

ChildDataGroupIndex[-1, 1] returns 2 (the ‘EXCHANGE:  NYSE’ row)

ChildDataGroupIndex[2, 0] returns 3 (the first child of the ‘EXCHANGE:  NYSE’ row)

ChildDataGroupIndex[1, 1] returns –1 (there is only one child for the ‘RISK : MED’ row)

ReadOnly Property


TcxDataControllerGroups.ChildRecordIndex

TcxDataControllerGroups           See Also

Returns the index of the record within a specific data group.

type

  TcxDataGroupIndex = Integer;

property ChildRecordIndex[ParentDataGroupIndex: TcxDataGroupIndex; ChildIndex: Integer]: Integer;

Description

Use this property to access the index of the record that corresponds to the data row within a data group addressed by the ParentDataGroupIndex parameter.  The ChildIndex parameter specifies the index of this data row.  Both these parameters accept only zero-based indexes.

The ChildRecordIndex property returns –1 if the specified data group or row cannot be found.

ReadOnly Property


TcxDataControllerGroups.DataController

TcxDataControllerGroups           See Also

Identifies the data controller to which the current TcxDataControllerGroups object belongs.

property DataController: TcxCustomDataController;

Description

The DataController property defines an instance of the TcxCustomDataController class, which owns the current TcxDataControllerGroups object.

ReadOnly Property


TcxDataControllerGroups.DataGroupIndexByRowIndex

TcxDataControllerGroups           See Also

Returns the data group index for a specified row index.

type

  TcxDataGroupIndex = Integer;

property DataGroupIndexByRowIndex[RowIndex: Integer]: TcxDataGroupIndex;

Description

Row index defines the visible row position within a grid control.  DataGroupIndexByRowIndex returns the index of the data group which owns a specified row.  Use the ParentDataGroupIndex and ChildDataGroupIndex properties to return indexes of the parent and child data groups.

The following image demonstrates relations between row and data group indexes.

For this sample grid control:

DataGroupIndexByRowIndex[0] returns 0

DataGroupIndexByRowIndex[1] returns 1

DataGroupIndexByRowIndex[2] returns 1

ReadOnly Property


TcxDataControllerGroups.FieldGroupIndex

TcxDataControllerGroups

Returns the data group index by the field containing values of the mapped item that the data is grouped by.

property FieldGroupIndex[AField: TcxCustomDataField]: Integer;

Description

Each data group can be determined in a number of different ways.  For example, you can find a specific data group by a row (see the DataGroupIndexByRowIndex property) or by an item (see the ItemGroupIndex property) that this data group contains.

The FieldGroupIndex property allows you to find out which data group corresponds to the AField field that the data is grouped by.

ReadOnly Property


TcxDataControllerGroups.GroupDisplayTexts

TcxDataControllerGroups          See Also

Returns the group row’s display text.

type

  TcxDataGroupIndex = Integer;

property GroupDisplayTexts[ADataGroupIndex: TcxDataGroupIndex]: string;

Description

ADataGroupIndex specifies the data group’s index whose the group row’s display text is to be returned.

ReadOnly Property


TcxDataControllerGroups.GroupingItemCount

TcxDataControllerGroups           See Also

Returns the current number of grouping items.

property GroupingItemCount: Integer;

Description

Use the GroupingItemCount property to determine the number of items by which grid data is grouped.  If grid data is presented by using the grid view, this property returns the number of columns whose GroupIndex property value is greater than –1.

To change the group order use the ChangeGrouping method.  It allows you to set a group index or delete grouping by a specific item.

Use the GroupingItemIndex property to define the grouping item position within a collection of all items.  The ItemGroupIndex property performs the opposite operation.  It returns the group index of the item at a specific position within the collection.

ReadOnly Property


TcxDataControllerGroups.GroupingItemIndex

TcxDataControllerGroups           See Also

Returns the grouping item position within a collection of all items.

property GroupingItemIndex[Index: Integer]: Integer;

Description

Index identifies the group index.  It addresses a grouping item and can vary from 0 to (GroupingItemCount – 1).  GroupingItemIndex returns the grouping item position within the collection of all items to which it belongs.

If grid data is displayed by using the grid view, the Index parameter specifies the value of the GroupIndex property.  GroupingItemIndex returns the Index property value of the corresponding column.

ReadOnly Property


TcxDataControllerGroups.GroupValues

TcxDataControllerGroups          See Also

Returns the persistent field’s value that uniquely identifies the ADataGroupIndex group row.

type

  TcxDataGroupIndex = Integer;

property GroupValues[ADataGroupIndex: TcxDataGroupIndex]: Variant;

Description

If the data is hierarchically grouped by items in the grid view, data rows are consolidated into hierarchical data groups headed by group rows.

The GroupValues property searches the value in the field mapped to the grouping item.  The search criterion is the group row that this value corresponds to.

ADataGroupIndex specifies the index of the group row in the view.

ReadOnly Property


TcxDataControllerGroups.ItemGroupIndex

TcxDataControllerGroups           See Also

Returns the group index of the item at a specified position.

property ItemGroupIndex[ItemIndex: Integer]: Integer;

Description

The ItemIndex parameter identifies the position of an item within the collection of all items to which it belongs.  The ItemGroupIndex property returns the item group index.  If the ItemIndex parameter does not specify the grouping item, ItemGroupIndex returns –1.  If the ItemIndex parameter addresses a grouping item, the returned value is within the range from 0 to (GroupingItemCount – 1).

If grid data is displayed by using the grid view, the ItemIndex parameter represents a value of the Index property.  And the returned value is defined via the GroupIndex property.

To obtain the grouping item position within the collection of all items use the GroupingItemIndex property.

You can change the item group index via the ChangeGrouping method.

ReadOnly Property


TcxDataControllerGroups.Level

TcxDataControllerGroups          See Also

Returns the hierarchy level of the currently processed data group.

type

  TcxDataGroupIndex = Integer;

property Level[ADataGroupIndex: TcxDataGroupIndex]: Integer;

Description

If grouped by items, data groups are displayed in the grid hierarchically, at different levels.

The root level is –1.  The Level property’s value for the top-level data groups is 0.  For each level from top to bottom, the value is incremented by 1.

ADataGroupIndex specifies the data group’s index whose level is to be returned.

ReadOnly Property


TcxDataControllerGroups.ParentDataGroupIndex

TcxDataControllerGroups           See Also

Returns the index of a parent data group.

type

  TcxDataGroupIndex = Integer;

property ParentDataGroupIndex[ChildDataGroupIndex: TcxDataGroupIndex]: TcxDataGroupIndex;

Description

The ParentDataGroupIndex property returns the index of the parent data group containing the specified child data group.  Every data group in a grid control has a parent, even those at level 0, which have a virtual data group with an index of –1.

Use the ChildDataGroupIndex property to determine the index of child data groups.

Let us examine a grid control displayed in the following image:

For this sample grid:

ParentDataGroupIndex [0] returns –1 (the ‘EXCHANGE:  NONE’ data group is at level 0)

ParentDataGroupIndex [1] returns 0 (the parent of data group 1 is data group 0)

ParentDataGroupIndex [4] returns 2 (the parent of data group 4 is data group 2)

ReadOnly Property


TcxDataControllerGroups.ChangeExpanding

TcxDataControllerGroups           See Also

Expands or collapses a data group.

procedure ChangeExpanding(ARowIndex: Integer; AExpanded, ARecursive: Boolean);

Description

The ChangeExpanding method expands or collapses a group based upon the value of the AExpanded parameter.  If AExpanded is True, a group is expanded.  Otherwise the group is collapsed.  To identify a data group, you should pass the index of a group row via the ARowIndex parameter.  Specifying the index of a data row will do nothing.

The ARecursive parameter allows you to expand or collapse nested groups recursively.  Set this parameter to True to expand/collapse all the nested groups.

To expand and collapse all data groups use the FullExpand and FullCollapse methods respectively.


TcxDataControllerGroups.ChangeGrouping

TcxDataControllerGroups           See Also

Sets the group index for a specified item

procedure ChangeGrouping(AItemIndex, AGroupIndex: Integer);

Description

The ChangeGrouping method allows you to set the group index for an item.  The item is addressed by its position within a collection of all items.  The AGroupIndex parameter defines a new group index.  To delete grouping by a specific item you must pass –1 as the AGroupIndex parameter.  The number of current grouping items is defined via the GroupingItemCount property.  To determine the current group index for an item, use the ItemGroupIndex property.


TcxDataControllerGroups.ClearGrouping

TcxDataControllerGroups           See Also

Removes grid data grouping.

procedure ClearGrouping;

Description

The ClearGrouping method removes all grouping of the grid data (defined by grouping items).  The number of grouping items is defined via the GroupingItemCount property.  The method also deletes all data groups.


TcxDataControllerGroups.Create

TcxDataControllerGroups

Creates an instance of the TcxDataControllerGroups class.

constructor Create(ADataController: TcxCustomDataController);

Description

The constructor creates an instance of the TcxDataControllerGroups class for a specified data controller.


TcxDataControllerGroups.FullCollapse

TcxDataControllerGroups           See Also

Collapses all data groups within a grid control recursively.

procedure FullCollapse;

Description

Use the FullCollapse method to collapse all data groups, including nested data groups.  To collapse a specific data group, use the ChangeExpanding method.

The FullExpand method allows you to expand all data groups.


TcxDataControllerGroups.FullExpand

TcxDataControllerGroups           See Also

Expands all data groups within a grid control recursively.

procedure FullExpand;

Description

Use the FullExpand method to expand all data groups, including nested data groups.  To expand a specific data group, use the ChangeExpanding method.

The FullCollapse method allows you to collapse all data groups.


TcxDataControllerGroups.GetDataGroupIndexByGroupValue

TcxDataControllerGroups          See Also

Returns an index of the group row (data group) by the corresponding value stored in the underlying persistent field.

type

  TcxDataGroupIndex = Integer;

function GetDataGroupIndexByGroupValue(AParentDataGroupIndex: TcxDataGroupIndex; const AGroupValue: Variant): TcxDataGroupIndex;

Description

The GetDataGroupIndexByGroupValue method finds the data group‘s index by the specified parent data group, and the mapped field’s value that corresponds to the group row.

AParentDataGroupIndex specifies the parent data group that contains the data group to be found.

AGroupValue specifies the mapped field’s value corresponding to the data group (group row) to be found.


TcxDataControllerGroups.HasAsParent

TcxDataControllerGroups

Checks whether the ARowIndex row is a child of the AParentRowIndex row.

function HasAsParent(ARowIndex, AParentRowIndex: Integer): Boolean;

Description

Since data groups are hierarchically structured in the grid, each row in a nested group is a child of the row located in the parent group.

The HasAsParent method determines whether two specified rows are in the parent-child relationship.  If so, the method returns True; otherwise – False.


TcxDataControllerGroups.LoadRecordIndexes

TcxDataControllerGroups          See Also

Populates AList with indexes of records that correspond to rows of the ADataGroupIndex data group.

type

  TcxDataGroupIndex = Integer;

procedure LoadRecordIndexes(AList: TList; ADataGroupIndex: TcxDataGroupIndex);

Description

If the data is grouped by items in the grid view, rows are organized into hierarchical data groups.

The LoadRecordIndexes method allows you to cache information on records of the specific data group.

ADataGroupIndex specifies the data group whose corresponding record indexes are to be cached.


TcxDataControllerGroups.LoadRecordIndexesByRowIndex

TcxDataControllerGroups          See Also

Populates AList with indexes of records that correspond to rows of the data group identified by the ARowIndex row.

procedure LoadRecordIndexesByRowIndex(AList: TList; ARowIndex: Integer);

Description

If the data is grouped by items in the grid view, rows are organized into hierarchical data groups.

Each data group can be identified by a row that it contains (see the DataGroupIndexByRowIndex property).

The LoadRecordIndexesByRowIndex method allows you to cache information on records that correspond to rows of a particular data group.


TcxDataFilterCriteria
TcxDataFilterCriteria Object

Hierarchy          Properties          Methods          Events          See Also

Represents filter criteria for a grid control when working in unbound mode.

Unit

cxCustomData

TcxDataFilterCriteria = class(TcxFilterCriteria);

Description

The TcxDataFilterCriteria class is a descendant of the TcxFilterCriteria class, which implements the base grid filtering facilities.  The TcxDataFilterCriteria class realizes data filtering in unbound mode.  It also publishes the OnGetValueList event, which allows you to customize a list of values for filter conditions.  This list represents a collection of values from which a user can visually select a filter condition for a specific item.

TcxDBDataFilterCriteria derives from the TcxDataFilterCriteria class and implements filtering for a TDataSet object.


TcxDataFilterCriteria Hierarchy
Hierarchy

TPersistent

     |

TcxFilterCriteria

     |


Properties for TcxDataFilterCriteria
TcxDataFilterCriteria Properties

TcxDataFilterCriteria          Legend

In TcxDataFilterCriteria

Active

DataController

Derived from TcxFilterCriteria

DateTimeFormat

FilterCaption

FilterText

MaxValueListCount

Options

PercentWildcard

Root

StoreItemLinkNames

SupportedLike

TranslateBetween

TranslateIn

TranslateLike

UnderscoreWildcard


Methods for TcxDataFilterCriteria
TcxDataFilterCriteria Methods

TcxDataFilterCriteria          Legend

In TcxDataFilterCriteria

Create

Destroy

FindItemByItemLink

IsFiltering

RemoveItemByField

Derived from TcxFilterCriteria

AddItem

Assign

BeginUpdate

CancelUpdate

Clear

Create

Destroy

EndUpdate

LoadFromStream

RemoveItemByItemLink

RestoreDefaults

SaveToStream


Events for TcxDataFilterCriteria
TcxDataFilterCriteria Events

TcxDataFilterCriteria          Legend

In TcxDataFilterCriteria

OnGetValueList

Derived from TcxFilterCriteria

OnChanged


TcxDataFilterCriteria.Active

TcxDataFilterCriteria           See Also

Enables the filtering feature for a grid control.

property Active: Boolean;

Description

Use the Active property to activate filtering within a grid control.  When filtering is enabled, a grid control is populated only with the records that meet filter criteria.  Use the Root property to set filter criteria.  When the Active property is set to True, filter arrows are displayed to the right of the column captions for which filter conditions are set.

The default value of the Active property is False.


TcxDataFilterCriteria.DataController

TcxDataFilterCriteria           See Also

Specifies the TcxCustomDataController object for which the current filter criteria are applied.

property DataController: TcxCustomDataController;

Description

Use the DataController property to determine the object of the TcxCustomDataController class for which the current filter criteria are applied.

ReadOnly Property


TcxDataFilterCriteria.Create

TcxDataFilterCriteria

Creates an instance of the TcxDataFilterCriteria class.

constructor Create(ADataController: TcxCustomDataController);

Description

The constructor creates and initializes an instance of the TcxDataFilterCriteria class.  The ADataController parameter specifies the object of the TcxCustomDataController class for which filter criteria should be applied.


TcxDataFilterCriteria.Destroy

TcxDataFilterCriteria

Destroys an instance of the TcxDataFilterCriteria class.

destructor Destroy; override;

Description

The destructor deletes a TcxDataFilterCriteria object and frees all resources allocated for it.  Do not call Destroy directly.  Call Free instead.  Free verifies that the object reference is not nil before calling Destroy.


TcxDataFilterCriteria.FindItemByItemLink

TcxDataFilterCriteria

Returns a filter condition for a specific grid item.

function FindItemByItemLink(AItemLink: TObject): TcxFilterCriteriaItem; override;

Description

This function returns the first filter condition found for the grid item identified by a link passed as the AItemLink parameter.  If this condition can’t be found, nil is returned.

To identify an item, use the TcxGridColumn object.


TcxDataFilterCriteria.IsFiltering

TcxDataFilterCriteria

Specifies whether filtering is in effect.

function IsFiltering: Boolean; virtual;

Description

Use the IsFiltering function to determine whether a filter condition is applied.  The function returns True if the filter condition specified by the FilterText property is not empty and the Active property is set to True.


TcxDataFilterCriteria.OnGetValueList

TcxDataFilterCriteria           See Also             Example

Occurs before displaying a popup list of values for a filter condition.

type

  TcxDataFilterGetValueListEvent = procedure(Sender: TcxFilterCriteria; AItemIndex: Integer; AValueList: TcxDataFilterValueList) of object;

property OnGetValueList: TcxDataFilterGetValueListEvent;

Description

The popup list displays values for a filter condition within which a user can select an element and thus generate a filter condition for the column.  You can use the OnGetValueList event to customize the list before it is displayed on screen.  This event is generated every time a user clicks the down-arrow button on the column caption.

The Sender parameter identifies the filter criteria applied to a grid control.  The AItemIndex parameter is the index of the grid item for which the event is generated.  You can use the Index property of the grid column object to determine the column index.  The AValueList parameter specifies the list of values for a filter condition.


TcxDataFilterCriteria.RemoveItemByField

TcxDataFilterCriteria

Removes all filter conditions for a specific grid item identified by an internal data field.

procedure RemoveItemByField(AField: TcxCustomDataField);

Description

This method is for internal use only.  It simply calls the RemoveItemByItemLink method, and passes AField as its parameter.


TcxDataFilterCriteriaItem
TcxDataFilterCriteriaItem Object

Hierarchy          Properties          Methods

Represents a filter condition.

Unit

cxCustomData

TcxDataFilterCriteriaItem = class(TcxFilterCriteriaItem);

Description

The TcxDataFilterCriteriaItem class extends the functionality of the TcxFilterCriteriaItem class by working with the data controller.


TcxDataFilterCriteriaItem Hierarchy
Hierarchy

TObject

     |

TcxCustomFilterCriteriaItem

     |

TcxFilterCriteriaItem

     |


Properties for TcxDataFilterCriteriaItem
TcxDataFilterCriteriaItem Properties

TcxDataFilterCriteriaItem          Legend

In TcxDataFilterCriteriaItem

DataController

Derived from TcxFilterCriteriaItem

DisplayValue

OperatorKind

Value


Methods for TcxDataFilterCriteriaItem
TcxDataFilterCriteriaItem Methods

TcxDataFilterCriteriaItem          Legend

Derived from TcxFilterCriteriaItem

Create

Destroy


TcxDataFilterCriteriaItem.DataController

TcxDataFilterCriteriaItem

Specifies the TcxCustomDataController class for which the current filter condition is applied.

property DataController: TcxCustomDataController;

Description

Use the DataController property to retrieve the data controller object for which the current filter condition is applied.

ReadOnly Property


TcxDataFilterValueList
TcxDataFilterValueList Object

Hierarchy          Properties          Methods          See Also

Represents the list of values for filter conditions.

Unit

cxCustomData

TcxDataFilterValueList = class(TcxFilterValueList);

Description

The TcxDataFilterValueList class extends the functionality of TcxFilterValueList.  It provides the Load method, which is used to populate the list of values of different kinds.


TcxDataFilterValueList Hierarchy
Hierarchy

TObject

     |

TcxFilterValueList

     |


Properties for TcxDataFilterValueList
TcxDataFilterValueList Properties

TcxDataFilterValueList          Legend

In TcxDataFilterValueList

DataController

Derived from TcxFilterValueList

Count

Criteria

Items

SortByDisplayText


Methods for TcxDataFilterValueList
TcxDataFilterValueList Methods

TcxDataFilterValueList          Legend

In TcxDataFilterValueList

Load

Derived from TcxFilterValueList

Add

Clear

Create

Delete

Destroy

FindItemByKind

FindItemByValue


TcxDataFilterValueList.DataController

TcxDataFilterValueList           See Also

Specifies the object of the TcxCustomDataController class for which the current list is generated.

property DataController: TcxCustomDataController;

Description

The DataController property specifies the data controller for which the list of values for filter conditions is generated.  Values are obtained from the data controller via the Load method.

ReadOnly Property


TcxDataFilterValueList.Load

TcxDataFilterValueList           See also

Populates a list of values for filter conditions.

procedure Load(AItemIndex: Integer); virtual;

Description

The Load method adds elements of different types to the list.  The first items added are always elements of the fviAll and fviCustom types.  Then it adds unique values from the table item whose index is defined by the AItemIndex parameter.  Values are added as elements of the fviValue type.  If an item contains any NULL values, then this method also adds elements of the fviBlanks, fviNonBlanks types.  The Load method generates the TcxDataFilterCriteria.OnGetValueList event, which enables you to customize the generated list.  For instance, you can add, delete specific elements, and add user-defined elements of the fviUser type.


TcxRowInfo
TcxRowInfo type

Represents a structure storing information on a single row within a data controller.

Unit

cxCustomData

TcxRowInfo = record

    Expanded: Boolean;

    Level: Integer;

    RecordIndex: Integer;

end;

Description

The TcxRowInfo type represents the structure for storing information on a single row to pass to the data controller’s members.  This structure is filled by the GetRowInfo function, which returns the TcxRowInfo object describing a row (a data record or a grouping row) at a specific position.  The RowInfo object is required by several methods (for instance, GetRowDisplayText and GetRowValue).

The Expanded field specifies the expansion status of the current row.  It is applied only to grouping rows.  For data records, Expanded is always False.

The Level field specifies the grouping level of a row, i.e. the level of the data group, containing the current row.

The RecordIndex field identifies the record index of a row.  If the row represents a grouping row, RecordIndex specifies the record index of the first data record belonging to the current data group.


TcxDataFooterSummaryItems
TcxDataFooterSummaryItems Object

Hierarchy          Properties          Methods          Events          See also

Represents a collection of footer summaries.

Unit

cxCustomData

TcxDataFooterSummaryItems = class(TcxDataSummaryItems);

Description

The TcxDataFooterSummaryItems class is a collection of footer summaries.  A footer summary is calculated against all records in a grid control.  You can create several footer summaries within the collection by calling the Add method.

To set footer summaries for a grid, use the TcxCustomDataController.Summary property.  It identifies the object of the TcxDataSummary class, which allows you to add both footer and group summaries.


TcxDataFooterSummaryItems Hierarchy
Hierarchy

TCollection

     |

TcxDataSummaryItems

     |


Properties for TcxDataFooterSummaryItems
TcxDataFooterSummaryItems Properties

TcxDataFooterSummaryItems          Legend

Derived from TcxDataSummaryItems

DataController

Items

Summary


Methods for TcxDataFooterSummaryItems
TcxDataFooterSummaryItems Methods

TcxDataFooterSummaryItems          Legend

Derived from TcxDataSummaryItems

Add

Create

DeleteItems

DefaultFormat

IndexOfItemLink

ItemOfItemLink


Events for TcxDataFooterSummaryItems
TcxDataFooterSummaryItems Events

TcxDataFooterSummaryItems          Legend

Derived from TcxDataSummaryItems

OnSummary


TcxDataGroupSummaryItems
TcxDataGroupSummaryItems Object

Hierarchy          Properties          Methods          Events         See also

Represents a collection of group summaries.

Unit

cxCustomData

TcxDataGroupSummaryItems = class(TcxDataSummaryItems);

Description

The TcxDataGroupSummaryItems class is a collection of group summaries.  A group summary is calculated against records within individual groups.  You can create several group summaries within the collection by calling the Add method.

To assign group summaries to a grid, use the DataController.Summary property.  It identifies the object of the TcxDataSummary class and this allows you to add both footer and group summaries.

The grid control allows you to define:

•	default group summaries, which are calculated when grouping by any item is applied.  Summaries of this type are set via the TcxDataSummary.DefaultGroupSummaryItems property.  To redefine group summaries for a specific grouping item, you can use group summaries of the following type.

•	group summaries, which are calculated when grouping by specific items is applied.  To create summaries of this type you must specify summary groups via the TcxDataSummary.SummaryGroups property.  Each summary group associates a collection of group summaries with grouping items.


TcxDataGroupSummaryItems Hierarchy
Hierarchy

TCollection

     |

TcxDataSummaryItems

     |


Properties for TcxDataGroupSummaryItems
TcxDataGroupSummaryItems Properties

TcxDataGroupSummaryItems          Legend

In TcxDataGroupSummaryItems

BeginText

EndText

Separator

Derived from TcxDataSummaryItems

DataController

Items

Summary


Methods for TcxDataGroupSummaryItems
TcxDataGroupSummaryItems Methods

TcxDataGroupSummaryItems          Legend

In TcxDataGroupSummaryItems

Create

SortedSummaryItem

Derived from TcxDataSummaryItems

Add

Create

DeleteItems

DefaultFormat

IndexOfItemLink

ItemOfItemLink


Events for TcxDataGroupSummaryItems
TcxDataGroupSummaryItems Events

TcxDataGroupSummaryItems          Legend

Derived from TcxDataSummaryItems

OnSummary


TcxDataGroupSummaryItems.BeginText

TcxDataGroupSummaryItems           See also

Identifies the prefix to add to the summary text in the group panel.

property BeginText: string;

Description

If group summaries are displayed in the group panel (see TcxDataSummaryItem.Position), they are enclosed with strings specified by the BeginText and EndText properties.  Individual group summaries within the panel are separated by a Separator.

The following image demonstrates the group summaries in the group panel for which:

•	BeginText is set to ‘{’

•	EndText is set to ‘}’

•	Separator is set to ‘;’


TcxDataGroupSummaryItems.EndText

TcxDataGroupSummaryItems           See also

Identifies the suffix to add to the summary text in the group panel.

property EndText: string;

Description

If group summaries are displayed in the group panel (see TcxDataSummaryItem.Position), they are enclosed with strings specified by the BeginText and EndText properties.  Individual group summaries within this text are separated by a Separator.

The following image demonstrates the group summaries in the group panel for which:

•	BeginText is set to ‘{’

•	EndText is set to ‘}’

•	Separator is set to ‘;’


TcxDataGroupSummaryItems.Separator

TcxDataGroupSummaryItems           See also

Specifies the string which separates individual group summaries in the group panel.

property Separator: string;

Description

If group summaries are displayed in the group panel (see TcxDataSummaryItem.Position), they are enclosed with strings specified by the BeginText and EndText properties.  Individual group summaries within this text are separated by a Separator.

The following image demonstrates the group summaries in the group panel for which:

•	BeginText is set to ‘{’

•	EndText is set to ‘}’

•	Separator is set to ‘;’


TcxDataGroupSummaryItems.Create

TcxDataGroupSummaryItems

Creates a new instance of the TcxDataGroupSummaryItems class.

type

  TcxDataSummaryItemClass = class of TcxDataSummaryItem;

constructor Create(ASummary: TcxDataSummary; AItemClass: TcxDataSummaryItemClass); override;

Description

The constructor creates a collection of group summaries.  Each summary represents an object of the AItemClass class.  The element class information is required by the Add method used to create a new collection element.

The ASummary parameter specifies the TcxDataSummary class instance which becomes the owner of the collection.


TcxDataGroupSummaryItems.SortedSummaryItem

TcxDataGroupSummaryItems

Returns the summary object whose values are used to sort data groups associated with the collection of group summaries.

function SortedSummaryItem: TcxDataSummaryItem;

Description

If none of the summary objects within the collection provides values for sorting, nil is returned.

To specify the summary object to provide values for sorting, set its Sorted property to True.


TcxDataSummary
  TcxDataSummary Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of summaries calculated using grid data.

Unit

cxCustomData

TcxDataSummary = class(TPersistent);

Description

All summaries for a grid control are set via the TcxDataSummary class.  There are two main types of summaries you can calculate: footer summaries and group summaries.  Footer summaries are calculated for all records using specific items.  Footer summaries are displayed in the footer panel at the bottom of the grid.

Group summaries are calculated when data is grouped by an item.  Only records within a group are used to evaluate summary values.  Group summaries are displayed either in the group panel or in the group footer.

TcxDataSummary provides you with the ability to create several summaries for the same item.  This is useful when creating group summaries because they can all be displayed in the group panel, for instance.  If you create several footer summaries for one item, only the first footer summary is displayed.

Footer summaries are supported by the FooterSummaryItems property.  It identifies a collection of summaries calculated for all grid records by specific grid items.

Group summaries are set via two properties: DefaultGroupSummaryItems and SummaryGroups.  The DefaultGroupSummaryItems property determines the default group summaries to calculate when grid records are grouped by any item.  SummaryGroups allows you to override the default group summaries for individual grouping items.

Using the SummaryGroups property you define the so called summary groups.  Each summary group associates a set of grouping items with group summaries.  Every time grid data is grouped by a specific grouping item, the data controller looks for group summaries associated with the item in SummaryGroups.  If it fails, it calculates group summaries provided by the DefaultGroupSummaryItems property.

When all summaries have been calculated, the OnAfterSummary event occurs.  The TcxDataSummary class enables you to get summary results and change them.  Summary results can be obtained via the FooterSummaryValues, GroupSummaryValues and GroupSummaryDisplayValues properties.  To return formatted text representations of summary values use the FooterSummaryTexts, GroupSummaryText and GroupFooterSummaryTexts properties.

To calculate summaries only against selected rows or exclude NULL values from summary results use the Options property.


TcxDataSummary Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxDataSummary
TcxDataSummary Properties

TcxDataSummary          Legend

In TcxDataSummary

DataController

DefaultGroupSummaryItems

FooterSummaryItems

FooterSummaryTexts

FooterSummaryValues

GroupFooterIndexOfItemLink

GroupFooterSummaryTexts

GroupSummaryDisplayValues

GroupSummaryItems

GroupSummaryText

GroupSummaryValues

Options

SummaryGroups


Methods for TcxDataSummary
TcxDataSummary Methods

TcxDataSummary          Legend

In TcxDataSummary

Assign

BeginUpdate

Calculate

CalculateFooterSummary

CalculateGroupSummary

CancelUpdate

Create

Destroy

EndUpdate


Events for TcxDataSummary
TcxDataSummary Events

TcxDataSummary          Legend

In TcxDataSummary

OnAfterSummary


TcxDataSummary.DataController

TcxDataSummary           See Also

Represents the data controller which contains the current set of summaries.

property DataController: TcxCustomDataController;

Description

Read this property to get access to the data controller properties.  The data controller contains data that is used to make up a summary.

ReadOnly Property


TcxDataSummary.DefaultGroupSummaryItems

TcxDataSummary           See Also

Specifies the collection of group summaries.

property DefaultGroupSummaryItems: TcxDataGroupSummaryItems;

Description

Use the DefaultGroupSummaryItems property to assign group summaries to items.  When grid records are grouped by any item, these summaries are calculated.  But you can use the SummaryGroups property to redefine summaries when grouping is performed by specific items.

To define footer summaries use the FooterSummaryItems property.

Use the GroupSummaryValues and GroupSummaryDisplayValues properties to get a value of an individual group summary or set it manually.  You can do this, for instance, in the OnAfterSummary event which occurs after all summaries have been calculated.

To return formatted text representations of summary values use the GroupFooterSummaryTexts and GroupSummaryText properties.


TcxDataSummary.FooterSummaryItems

TcxDataSummary           See also

Specifies the collection of footer summaries.

property FooterSummaryItems: TcxDataFooterSummaryItems;

Description

The FooterSummaryItems property allows you to set footer summaries which are calculated for all records.  Footer summaries are displayed in the footer panel at the bottom of the grid control.  You can access a footer summary value and its text representation using the FooterSummaryValues and FooterSummaryTexts properties respectively.

To set group summaries use the DefaultGroupSummaryItems and SummaryGroups properties.

Use the FooterSummaryValues property to get a value of an individual footer summary or set it manually.  You can do this, for instance, in the OnAfterSummary event which occurs after all summaries have been calculated.

To return formatted text representations of footer summary values use FooterSummaryTexts.


TcxDataSummary.FooterSummaryTexts

TcxDataSummary           See also

Specifies the text representation of a specified footer summary .

property FooterSummaryTexts[Index: Integer]: string;

Description

Footer summaries are provided by the FooterSummaryItems collection.  The FooterSummaryTexts property returns text representations of footer summary values, which can be accessed via the FooterSummaryValues property.  To determine the number of footer summaries in the collection use the FooterSummaryItems.Count property.

ReadOnly Property


TcxDataSummary.FooterSummaryValues

TcxDataSummary           See also

Specify the footer summary value at a specified index.

property FooterSummaryValues[Index: Integer]: Variant;

Description

The FooterSummaryValues property allows you to access footer summary values by their indexes.  Footer summaries are set via the FooterSummaryItems collection.  To determine the number of footer summaries in the collection use the FooterSummaryItems.Count property.

The FooterSummaryTexts property allows you to obtain text representations of footer summary values.


TcxDataSummary.GroupFooterIndexOfItemLink

TcxDataSummary

Returns the index of a specific group summary at a particular level in the collection displayed in the group footer panel.

property GroupFooterIndexOfItemLink[Level: Integer; ItemLink: TObject]: Integer;

Description

The GroupFooterIndexOfItemLink property searches a group summary calculated by the item defined by the ItemLink parameter at the required level.   It gets a collection of group summaries at the level via the GroupSummaryItems property and returns the index of an individual group summary which was created for a specific ItemLink and displayed in the group footer panel.  The value returned by the GroupFooterIndexOfItemLink property can be used in the GroupFooterSummaryTexts property to obtain the text of a specific group summary.

ReadOnly Property


TcxDataSummary.GroupFooterSummaryTexts

TcxDataSummary

Returns the text representation of an individual group summary at a particular level displayed in the group footer group footer panel.

property GroupFooterSummaryTexts[RowIndex, Level, Index: Integer]: string;

Description

The GroupFooterSummaryTexts property needs three coordinates to obtain the text representation of a group summary displayed in the group footer panel.

The RowIndex parameter identifies a row index that belongs (directly or indirectly) to the level provided by the Level parameter.  The GroupFooterSummaryTexts property can return group summary text not only for the level to which a specified row belongs, but also for upper levels that include this level.

The Index parameter addresses an individual group summary within a collection of group summaries displayed at the level.  This parameter must always address a group summary displayed in the group footer panel.  You can use the GroupFooterIndexOfItemLink property to return such an index for the required item.

To return text representations of group summaries displayed in the group panel use the GroupSummaryText property.

The next image demonstrates levels and row indexes in a sample grid control.  Level 0 contains the {Count=2} and {Min Ratio = 23.1} group summaries.  Level 1 contains the {Average Price = 76.3} and {MAX=84.25} group summaries.

To access the first collection of group summaries you need to set RowIndex to 0..3 and Level to 0.  To access the second group summary collection you have to set RowIndex to 1..3 and Level to 1.  Index can address only group summaries displayed in the group footer panel.

For instance, GroupFooterSummaryTexts [3, 0, 1] returns ‘Min Ratio = 23.1’ (Index, which is set to 1, identifies a group summary in the group footer panel)

ReadOnly Property


TcxDataSummary.GroupSummaryDisplayValues

TcxDataSummary

Determines an individual group summary value at a specified level.

property GroupSummaryDisplayValues[RowIndex, Level, Index: Integer]: Variant;

Description

The GroupSummaryDisplayValues property needs three coordinates to retrieve a group summary value.

The RowIndex parameter identifies a row index that belongs (directly or indirectly) to the level provided by the Level parameter.  The GroupSummaryDisplayValues property can return a group summary value not only for the level to which a specified row belongs, but also for upper levels that include this level.

The Index parameter addresses an individual group summary within a collection of group summaries displayed at the level.

The GroupSummaryDisplayValues property allows you to set a new group summary value programmatically.

To return the formatted text representation of the group summary use the GroupFooterSummaryTexts and GroupSummaryText properties.

The next image demonstrates levels and row indexes in a sample grid control.  Level 0 contains the {Count=2} and {Min Ratio = 23.1} group summaries.  Level 1 contains the {Average Price = 76.3} and {MAX=84.25} group summaries.

To access the first collection of group summaries you need to set RowIndex to 0..3 and Level to 0.  To access the second group summary collection you have to set RowIndex to 1..3 and Level to 1.  Index in this example can vary from 0 to 1 since there are two group summaries in each level.

For instance, GroupSummaryDisplayValues[3, 0, 1] returns 23.1 because it is the second item in the collection of group summaries at level 0.  To return the collection of group summaries at a specified level you can use the GroupSummaryItems property.


TcxDataSummary.GroupSummaryItems

TcxDataSummary           See also

Returns a collection of group summaries calculated at a specific level.

property GroupSummaryItems[Level: Integer]: TcxDataGroupSummaryItems;

Description

The GroupSummaryItems property retrieves the collection of group summaries calculated at a specific level.  The level is associated with a grouping item.  If data is grouped by two grouping items, for instance, you can pass 0 or 1 as a Level value.

Group summaries are set via the DefaultGroupSummaryItems and SummaryGroups properties.  If no group summaries are calculated for the specific level, the GroupSummaryItems property returns a valid object containing 0 summaries.

ReadOnly Property


TcxDataSummary.GroupSummaryText

TcxDataSummary

Specifies the formatted text string representing group summary values in a specific group panel.

property GroupSummaryText[RowIndex: Integer]: string;

Description

The GroupSummaryText property returns text representations of group summaries displayed in a specific group panel.  To identify a group for which text representations of group summaries are returned, you should supply any index of a row that belongs to the desired group.  The row index defines the current visible position of the row in a grid control.  Child rows of collapsed group rows are not taken into account.

Let us examine the following image:

The GroupSummaryText property returns the following strings for the specified row indexes:

RowIndex	Group Summary Text
0	{Count=2}
1	{Average Price = 76.3}
2	{Count=7}
3	{Average Price = 74.3}
4..9	{Average Price = 91.3}

The GroupSummaryText property does not return the text of a group summary displayed in the group footer panel.  To get the text of a group summary in the group footer panel use the GroupFooterSummaryTexts property.

ReadOnly Property


TcxDataSummary.GroupSummaryValues

TcxDataSummary           See Also

Determines an individual group summary value for a specific data group.

property GroupSummaryValues[DataGroupIndex: TcxDataGroupIndex; Index: Integer]: Variant;

Description

The GroupSummaryDisplayValues property can only access expanded group summary values as it uses a row index as a parameter.  The GroupSummaryValues property allows you to access all group summary values calculated in a grid regardless of their expansion status.

The DataGroupIndex parameter defines the index of a data group.  You can use methods of the TcxDataControllerGroups class to determine the index of the required data group.

The Index parameter addresses an individual group summary within a collection of group summaries displayed for a data group.

To return the formatted text representation of the group summary use the GroupFooterSummaryTexts and GroupSummaryText properties.


TcxDataSummary.Options

TcxDataSummary           See Also

Represents options responsible for summary calculations.

type

  TcxSummaryOption = (soNullIgnore, soSelectedRecords, soMultipleSelectedRecords);

  TcxSummaryOptions = set of TcxSummaryOption;

property Options: TcxSummaryOptions;

Description

The Options property allows you to control the behavior of summary calculations.  The following table lists the TcxSummaryOption values.

Value	Meaning
soNullIgnore	If set, NULL values are ignored when calculating summaries. To ignore NULL values for individual summaries you should write a TcxDataSummaryItems.OnSummary event.  You can access this event via FooterSummaryItems.OnSummary, DefaultGroupSummaryItems.OnSummary or SummaryGroups[Index].SummaryItems.OnSummary.  Refer to the example described in the TcxDataSummaryItems.OnSummary event topic.
soSelectedRecords	If set, summaries are calculated for the selected records.  Otherwise, they are calculated for all records. Note:  Setting this option automatically resets the soMultipleSelectedRecords option.
soMultipleSelectedRecords	If set, summaries are calculated for the selected records only when two or more records are selected.  Otherwise, they are calculated for all records (as if the option is not set). Note:  Setting this option automatically resets the soSelectedRecords option.

The default value of the Options property is [].


TcxDataSummary.SummaryGroups

TcxDataSummary           See Also

Defines the collection of group summaries for specific grouping items.

property SummaryGroups: TcxDataSummaryGroups;

Description

The SummaryGroups property allows you to access summary groups.  Use the SummaryGroups property to associate group summaries with specific grouping items.  These summaries are calculated when data is grouped by these items.  You can assign any grouping item to a set of group summaries.  Moreover, you can assign the same set of group summaries to several grouping items.

DefaultGroupSummaryItems also defines the collection of group summaries.  It specifies summaries calculated when you group by any item that is not referenced by SummaryGroups.

You can use the GroupSummaryItems property to access the collection of group summaries at the specific level disregarding whether they are provided by the DefaultGroupSummaryItems or SummaryGroups property.

Use the GroupSummaryValues and GroupSummaryDisplayValues properties to get a value of an individual group summary or to set it manually.  You can do this, for instance, in the OnAfterSummary event which occurs after all summaries have been calculated.

To return formatted text representations of summary values use GroupFooterSummaryTexts and GroupSummaryText.


TcxDataSummary.Assign

TcxDataSummary

Copies a specified summary to the current object.

procedure Assign(Source: TPersistent); override;

Description

The Assign method copies the data summary specified by the Source parameter to the current TcxDataSummary object.


TcxDataSummary.BeginUpdate

TcxDataSummary           See Also

Prevents the TcxDataSummary object from being updated until the CancelUpdate or EndUpdate method is called.

procedure BeginUpdate;

Description

Call the BeginUpdate method before you add a set of summaries.  After all changes are made, you should call the EndUpdate method.  If no changes have been made, you can call the CancelUpdate method.


TcxDataSummary.Calculate

TcxDataSummary           See also

Calculates all summaries contained in the current TcxDataSummary class instance.

procedure Calculate; virtual;

Description

The Calculate method performs calculations of footer and group summaries.  Footer summaries are provided by the FooterSummaryItems property.  Group summaries are represented by the DefaultGroupSummaryItems and SummaryGroups properties.

This method makes subsequent calls to CalculateFooterSummary and CalculateGroupSummary.


TcxDataSummary.CalculateFooterSummary

TcxDataSummary           See also

Calculates footer summaries in the current TcxDataSummary class instance.

procedure CalculateFooterSummary; virtual;

Description

The CalculateFooterSummary method calculates footer summaries provided by the FooterSummaryItems property.  To calculate both group and footer summaries use the Calculate method.


TcxDataSummary.CalculateGroupSummary

TcxDataSummary           See also

Calculates group summaries in the current TcxDataSummary class instance.

procedure CalculateGroupSummary; virtual;

Description

The CalculateGroupSummary method calculates group summaries if grouping is applied.  Group summaries are provided by the DefaultGroupSummaryItems and SummaryGroups properties.  If a grouping item is referenced by the SummaryGroups object, group summaries are obtained from SummaryGroups.  Otherwise, group summaries are determined by the DefaultGroupSummaryItems property.

To calculate both group and footer summaries use the Calculate method.


TcxDataSummary.CancelUpdate

TcxDataSummary           See Also

Enables updating the TcxDataSummary object after the BeginUpdate method is called.

procedure CancelUpdate;

Description

After the BeginUpdate method is called, a grid control does not receive notifications about summaries changing.  When changes to summaries are complete, you should call the EndUpdate method.  If no changes are made, you can call the CancelUpdate method.  Unlike the EndUpdate method the CancelUpdate method does not send a notification to a grid control.


TcxDataSummary.Create

TcxDataSummary

Creates a TcxDataSummary object for a specified data controller.

constructor Create(ADataController: TcxCustomDataController);

Description

The constructor creates an instance of the TcxDataSummary class and initializes its properties to their default values.


TcxDataSummary.Destroy

TcxDataSummary

Destroys the current instance of the TcxDataSummary class.

destructor Destroy; override;

Description

The destructor destroys the TcxDataSummary object and frees all resources allocated for it.  Do not call Destroy directly.  Call the Free method instead.  The Free method verifies that the object reference is not nil before calling Destroy.


TcxDataSummary.EndUpdate

TcxDataSummary           See Also

Enables updating the TcxDataSummary object after the BeginUpdate method is called.

procedure EndUpdate;

Description

The EndUpdate method should be called after all changes have been made to summaries.  It sends a notification to a grid control about the changes made.  If no changes have been made after calling the BeginUpdate method, it is recommended that you use CancelUpdate instead.


TcxDataSummary.OnAfterSummary

TcxDataSummary           See Also          Example

Occurs after all summaries have been calculated.

type

  TcxAfterSummaryEvent = procedure(ASender: TcxDataSummary) of object;

property OnAfterSummary: TcxAfterSummaryEvent;

Description

The OnAfterSummary event occurs after all summaries provided by the DefaultGroupSummaryItems, SummaryGroups and FooterSummaryItems properties have been calculated.  You can read and change an individual summary value via the FooterSummaryValues, GroupSummaryDisplayValues or GroupSummaryValues properties.  To get the formatted text representation of the summary value use the FooterSummaryTexts, GroupFooterSummaryTexts and GroupSummaryText properties.


TcxDataSummaryGroupItemLink
TcxDataSummaryGroupItemLink Object

Hierarchy          Properties          Methods       See also

Represents a grouping item in the summary group.

Unit

cxCustomData

TcxDataSummaryGroupItemLink = class(TcxCustomDataSummaryItem);

Description

The TcxDataSummaryGroupItemLink class represents a grouping item in the summary group.  A grouping item is provided by the ItemLink property.  Every summary group is an instance of the TcxDataSummaryGroup class.  It associates a set of grouping items with group summaries.  When grid records are grouped by any of these grouping items, the data controller automatically calculates the corresponding group summaries.  The TcxDataSummaryGroupItemLinks class provides a collection of TcxDataSummaryGroupItemLink objects via the TcxDataSummaryGroupItemLinks.Items property.

The TcxDataSummary class defines all summaries for a grid control.


TcxDataSummaryGroupItemLink Hierarchy
Hierarchy

TCollectionItem

     |

TcxCustomDataSummaryItem

     |


Properties for TcxDataSummaryGroupItemLink
TcxDataSummaryGroupItemLink Properties

TcxDataSummaryGroupItemLink          Legend

In TcxDataSummaryGroupItemLink

SummaryGroupItemLinks

Derived from TcxCustomDataSummaryItem

DataController

ItemLink


Methods for TcxDataSummaryGroupItemLink
TcxDataSummaryGroupItemLink Methods

TcxDataSummaryGroupItemLink          Legend

Derived from TcxCustomDataSummaryItem

 Assign

 BeginUpdate

 EndUpdate


TcxDataSummaryGroupItemLink.SummaryGroupItemLinks

TcxDataSummaryGroupItemLink           See Also

Identifies the collection to which the current TcxDataSummaryGroupItemLink object belongs.

property SummaryGroupItemLinks: TcxDataSummaryGroupItemLinks;

Description

Use the SummaryGroupItemLinks property to access the collection of grouping items to which the current TcxDataSummaryGroupItemLink object belongs.

ReadOnly Property


TcxDataSummaryGroupItemLinks
  TcxDataSummaryGroupItemLinks Object

Hierarchy          Properties          Methods         See also

Represents a collection of grouping items in the summary group.

Unit

cxCustomData

TcxDataSummaryGroupItemLinks = class(TCollection);

Description

The TcxDataSummaryGroupItemLinks class is a collection of grouping items, each of which is an object of the TcxDataSummaryGroupItemLink class.  The TcxDataSummaryGroupItemLinks collection belongs to the summary group, which associates its elements with group summaries.  A summary group is provided by the TcxDataSummaryGroup class.  When grid records are grouped by any of grouping items, the data controller automatically calculates the corresponding group summaries.

The TcxDataSummary class defines all summaries for a grid control.


TcxDataSummaryGroupItemLinks Hierarchy
Hierarchy

TCollection

     |


Properties for TcxDataSummaryGroupItemLinks
TcxDataSummaryGroupItemLinks Properties

TcxDataSummaryGroupItemLinks          Legend

In TcxDataSummaryGroupItemLinks

Items

SummaryGroup


Methods for TcxDataSummaryGroupItemLinks
TcxDataSummaryGroupItemLinks Methods

TcxDataSummaryGroupItemLinks          Legend

In TcxDataSummaryGroupItemLinks

Add

Create

IndexOfItemLink

ItemOfItemLink


TcxDataSummaryGroupItemLinks.Items

TcxDataSummaryGroupItemLinks           See also

Identifies the collection of grouping items provided by the current TcxDataSummaryGroupItemLinks object.

property Items[Index: Integer]: TcxDataSummaryGroupItemLink;

Description

Use the Items property to access a specific grouping item by its index.  Every grouping item represents an object of the TcxDataSummaryGroupItemLink class.  A grouping item is identified by the ItemLink property of the TcxDataSummaryGroupItemLink object.


TcxDataSummaryGroupItemLinks.SummaryGroup

TcxDataSummaryGroupItemLinks           See also

Defines the summary group to which the current collection belongs.

property SummaryGroup: TcxDataSummaryGroup;

Description

Use this property to identify the summary group to which the current collection of grouping items belongs.

ReadOnly Property


TcxDataSummaryGroupItemLinks.Add

TcxDataSummaryGroupItemLinks           See also

Adds a new element to the collection of grouping items.

function Add: TcxDataSummaryGroupItemLink;

Description

The Add method creates a new object of the TcxDataSummaryGroupItemLink class and adds it to the current collection of grouping items.  You can use the Add method to add a grouping item to the collection, which is maintained by the Items property.


TcxDataSummaryGroupItemLinks.Create

TcxDataSummaryGroupItemLinks

Creates a new instance of the TcxDataSummaryGroupItemLinks class.

constructor Create(ASummaryGroup: TcxDataSummaryGroup;
AItemClass: TcxDataSummaryGroupItemLinkClass); virtual;

Description

The constructor creates a collection of grouping items in the summary group.  Each grouping item represents an object of the AItemClass class.  The information on the element class is required by the Add method which creates a new collection element.

The ASummary parameter specifies the summary group, which becomes the owner of the collection.


TcxDataSummaryGroupItemLinks.IndexOfItemLink

TcxDataSummaryGroupItemLinks           See also

Determines the position of the collection element, which makes reference to a specified item.

function IndexOfItemLink(AItemLink: TObject): Integer;

Description

The IndexOfItemLink function returns the index of the element in the collection, which makes reference to a specified item via the ItemLink property.  If the current collection does not contain the TcxDataSummaryGroupItemLink object, which references AItemLink, the function returns –1.  The collection of items is supported by the Items property.

You can use the ItemOfItemLink method to retrieve the TcxDataSummaryGroupItemLink object itself instead of its index.


TcxDataSummaryGroupItemLinks.ItemOfItemLink

TcxDataSummaryGroupItemLinks           See also

Determines the TcxDataSummaryGroupItemLink object, which references a specified item.

function ItemOfItemLink(AItemLink: TObject): TcxDataSummaryGroupItemLink;

Description

The ItemOfItemLink function returns the TcxDataSummaryGroupItemLink object contained in the current collection, which references AItemLink via the ItemLink property.  If the current collection does not contain such an object, the function returns nil.  The collection of items is maintained by the Items property.

You can use the IndexOfItemLink method to retrieve the index of the appropriate TcxDataSummaryGroupItemLink object instead of the object itself.


TcxDataSummaryGroups
TcxDataSummaryGroups Object

Hierarchy          Properties          Methods          See also

Represents a collection of summary groups.

Unit

cxCustomData

TcxDataSummaryGroups = class(TCollection);

Description

The TcxDataSummaryGroups class represents a collection of the so called summary groups.  A summary group is an association of specific grouping items with group summaries.  When data in a grid control is grouped by any of the grouping items, relevant group summaries are calculated.

The Items property provides the indexed access to individual summary groups.  Each summary group is maintained by a separate TcxDataSummaryGroup object.

The main class, which calculates all grid summaries, is TcxDataSummary.  Both the TcxDataSummary.SummaryGroups and TcxDataSummary.DefaultGroupSummaryItems properties support group summaries.  The TcxDataSummary.DefaultGroupSummaryItems property defines the default group summaries when grouping by any item.  You can redefine group summaries for specific items via the TcxDataSummary.SummaryGroups property.


TcxDataSummaryGroups Hierarchy
Hierarchy

TCollection

     |


Properties for TcxDataSummaryGroups
TcxDataSummaryGroups Properties

TcxDataSummaryGroups          Legend

In TcxDataSummaryGroups

Items

Summary


Methods for TcxDataSummaryGroups
TcxDataSummaryGroups Methods

TcxDataSummaryGroups          Legend

In TcxDataSummaryGroups

Add

Create

FindByItemLink


TcxDataSummaryGroups.Items

TcxDataSummaryGroups

Identifies the collection of summary groups.

property Items: TcxDataSummaryGroup;

Description

The Items property allows you to access a specific summary group by its index.


TcxDataSummaryGroups.Summary

TcxDataSummaryGroups

Specifies the owner of the current summary groups collection.

property Summary: TcxDataSummary;

Description

Use the Summary property to access the TcxDataSummary object to which the current summary group belongs.

ReadOnly Property


TcxDataSummaryGroups.Add

TcxDataSummaryGroups          See also

Adds a summary group to the current collection.

function Add: TcxDataSummaryGroup;

Description

The Add method creates a new summary group and returns a reference to it.


TcxDataSummaryGroups.Create

TcxDataSummaryGroups

Constructs a new TcxDataSummaryGroups object.

constructor Create(ASummary: TcxDataSummary);

Description

The constructor creates a new instance of the TcxDataSummaryGroups class and initializes its properties to their default values.


TcxDataSummaryGroups.FindByItemLink

TcxDataSummaryGroups          See also

Returns the summary group associating a specified grouping item with group summaries.

function FindByItemLink(AItemLink: TObject): TcxDataSummaryGroup;

Description

The FindByItemLink method returns a reference to the summary group in the current collection, which associates a grouping item with summaries.  The method simply retrieves the summary group, whose TcxDataSummaryGroup.Links property contains the item specified by the AItemLink parameter.


TcxDataSummaryItem
TcxDataSummaryItem Object

Hierarchy          Properties          Methods          Events          See also

Represents a single summary to calculate on a specific item.

Unit

cxCustomData

TcxDataSummaryItem = class(TcxCustomDataSummaryItem);

Description

In addition to the settings inherited from the base TcxCustomDataSummaryItem class, the TcxDataSummaryItem class introduces properties that allow you to specify:

•	the summary function (the sum, maximum, count, average of values, etc.), which is used to calculate an item's summary (Kind).  The item can be accessed via the ItemLink property;

•	the format pattern for summary values (Format);

•	the position where summaries are displayed (Position);

•	whether summary values determine the sort order of data groups in a grid control (Sorted).

TcxDataSummaryItem objects are stored as elements in the TcxDataSummaryItems collection.  TcxDataSummaryItems is the base class for TcxDataFooterSummaryItems and TcxDataGroupSummaryItems which implement footer summaries and group summaries respectively.

To add a summary to a grid control use the TcxCustomDataController.Summary property.  This allows you to specify footer summaries, group summaries and group summaries by specific grouping items.


TcxDataSummaryItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxCustomDataSummaryItem

     |


Properties for TcxDataSummaryItem
TcxDataSummaryItem Properties

TcxDataSummaryItem          Legend

In TcxDataSummaryItem

DataController

Format

Kind

Position

Sorted

SummaryItems

Derived from TcxCustomDataSummaryItem

ItemLink


Methods for TcxDataSummaryItem
TcxDataSummaryItem Methods

TcxDataSummaryItem          Legend

In TcxDataSummaryItem

Assign

FormatValue

Derived from TcxCustomDataSummaryItem

BeginUpdate

EndUpdate


Events for TcxDataSummaryItem
TcxDataSummaryItem Events

TcxDataSummaryItem          Legend

In TcxDataSummaryItem

OnGetText


TcxDataSummaryItem.DataController

TcxDataSummaryItem           See also

Specifies the data controller containing the collection to which the current summary belongs.

property DataController: TcxCustomDataController;

Description

Use the DataController property to access the data controller containing the collection to which the current object belongs.

ReadOnly Property


TcxDataSummaryItem.Format

TcxDataSummaryItem           See Also

Specifies the format string to display a summary value.

property Format: string;

Description

Use the Format property to set the format pattern, which controls the manner in which a summary value is displayed.  If an empty string is specified, default patterns retrieved by the TcxDataSummaryItems.DefaultFormat function are used.

If values in the associated item are of the float type, they are formatted by the FormatFloat function defined in the SysUtils unit.  In this instance, the Format property identifies the format string passed to this function.  See the FormatFloat function for details on format specifiers.

Date/time values are formatted using the DateToStr, TimeToStr and DateTimeToStr functions.  If a value contains both time and date information, it is formatted by the DateTimeToStr function.  Otherwise, either DateToStr or TimeToStr is used.  The Format property specifies the prefix in this case.  A string returned by the DateToStr, TimeToStr or DateTimeToStr function is added to Format.  If the summary’s Kind property is skCount, the value is not formatted by the above-mentioned date/time procedures.  Instead, FormatFloat is called and Format is passed to it as a parameter.


TcxDataSummaryItem.Kind

TcxDataSummaryItem

Specifies the type of the summary to calculate.

type

  TcxSummaryKind = (skNone, skSum, skMin, skMax, skCount, skAverage);

property Kind: TcxSummaryKind;

Description

The Kind property defines the type of the summary to calculate.  The following table lists possible summary kinds.

Value	Meaning
skNone	Summary is not used.
skSum	Sums item values within a group (for group summaries) or against all records (for footer summaries).
skMin	Retrieves the minimum value among item values within a group (for group summaries) or against all records (for footer summaries).
skMax	Retrieves the maximum value among item values within a group (for group summaries) or against all records (for footer summaries).
skCount	Displays the number of records within a group (for group summaries) or against all records (for footer summaries).
skAverage	Calculates the average item value within a group (for group summaries) or against all records (for footer summaries).

The default value of the Kind property is skNone.


TcxDataSummaryItem.Position

TcxDataSummaryItem

Specifies the panel where a summary is displayed.

type

  TcxSummaryPosition = (spGroup, spFooter);

property Position: TcxSummaryPosition;

Description

The following table lists possible values:

Value	Meaning
spGroup	The summary is displayed in the group panel.  This value is applicable only for group summaries of the TcxDataGroupSummaryItems class.
spFooter	The summary is displayed either in the footer panel or in the group footer panel. It is impossible to change the position of footer summaries which are calculated against all records in a grid control.  Footer summaries are always drawn in the footer panel and Position is set to spFooter. As for group summaries, if Position is spFooter, the summary is displayed in the group footer panel (under all records belonging to a group).


TcxDataSummaryItem.Sorted

TcxDataSummaryItem          See Also

Specifies whether summary values determine the sort order of data groups in a grid control.

property Sorted: Boolean;

Description

This property is relevant only for the TcxDataGroupSummaryItems class group summaries.  There’s only one summary object that can provide values that are used to sort data groups.  Its Sorted property is set to True.

When sorting is changed, the data controller’s OnSortingChanged event is fired.

The default value of the Sorted property is False.


TcxDataSummaryItem.SummaryItems

TcxDataSummaryItem

Provides access to the collection of summaries that the summary object belongs to.

property SummaryItems: TcxDataSummaryItems;

ReadOnly Property


TcxDataSummaryItem.Assign

TcxDataSummaryItem

Copies a specific summary to the current object.

procedure Assign(Source: TPersistent); override;

Description

The Assign method copies properties of the summary item specified by the Source parameter to the current TcxDataSummaryItem object.


TcxDataSummaryItem.FormatValue

TcxDataSummaryItem

Returns a string representation of a specific summary object value.

function FormatValue(const AValue: Variant; AIsFooter: Boolean): string; virtual;

Description

The AValue parameter refers to the summary value.

The AIsFooter parameter is equal to True when the summary value is displayed either in a footer panel or a group footer panel.

By default, this function formats the summary value using the format pattern specified by the Format property.  If this property is assigned an empty string, the default format string is used as specified by the DefaultFormat function of a collection summary that the summary object belongs to.

Note:	You can handle the OnGetText event to customize the return value of the FormatValue function.


TcxDataSummaryItem.OnGetText

TcxDataSummaryItem

Allows you to customize a string representation of a specific summary object value.

type

  TcxDataSummaryItemGetTextEvent = procedure(Sender: TcxDataSummaryItem; const AValue: Variant; AIsFooter: Boolean; var AText: string) of object;

property OnGetText: TcxDataSummaryItemGetTextEvent;

Description

The Sender parameter provides access to the summary object.

The AValue parameter refers to the summary value.

The AIsFooter parameter returns True when the summary value is displayed either in a footer panel or a group footer panel.

Return the summary value’s display text via the AText parameter.  By default, this string is initially formatted as specified by the FormatValue function.


TcxDataSummaryItems
TcxDataSummaryItems Object

Hierarchy          Properties          Methods          Events          See Also

Represents a collection of summaries.

Unit

cxCustomData

TcxDataSummaryItems = class(TCollection);

Description

TcxDataSummaryItems is a collection of single summaries, each of which is represented by the TcxDataSummaryItem class.  The TcxDataSummaryItem object associates an item with the summary type (sum, average, maximum, etc.).  Use the Items property to access an individual summary.

The TcxDataFooterSummaryItems and TcxDataGroupSummaryItems classes are derived from TcxDataSummaryItems.  They implement group summaries and footer summaries respectively.  Use the TcxCustomDataController.Summary property in order to set both group summaries and footer summaries for your grid.

The OnSummary event allows you to change the default behavior of summary calculation.  Use this event when you want to exclude specific values from the summary result or replace individual element values with another ones.


TcxDataSummaryItems Hierarchy
Hierarchy

TCollection

     |


Properties for TcxDataSummaryItems
TcxDataSummaryItems Properties

TcxDataSummaryItems          Legend

In TcxDataSummaryItems

DataController

Items

Summary


Methods for TcxDataSummaryItems
TcxDataSummaryItems Methods

TcxDataSummaryItems          Legend

In TcxDataSummaryItems

Add

Create

DefaultFormat

DeleteItems

IndexOfItemLink

ItemOfItemLink


Events for TcxDataSummaryItems
TcxDataSummaryItems Events

TcxDataSummaryItems          Legend

In TcxDataSummaryItems

OnSummary


TcxDataSummaryItems.DataController

TcxDataSummaryItems           See Also

Determines the data controller to which the current collection belongs.

property DataController: TcxCustomDataController;

Description

Read the DataController property to access the data controller, which contains the current collection.  The DataController property retrieves the same value as the DataController property of the Summary object.

ReadOnly Property


TcxDataSummaryItems.Items

TcxDataSummaryItems           See Also

Specifies the collection of summaries.

property Items[Index: Integer]: TcxDataSummaryItem;

Description

Use the Items property to access an individual summary by its index.  Summaries are represented by the TcxDataSummaryItem class.  You can set an item for your summary, its type, to format output strings and their position (only for group summaries) using the returned object.


TcxDataSummaryItems.Summary

TcxDataSummaryItems           See Also

Specifies the TcxDataSummary object to which the current collection of summaries belongs.

property Summary: TcxDataSummary;

Description

Read the Summary property to access the TcxDataSummary object, which contains the current collection of summaries.  TcxDataSummary combines all summaries that are set for the grid control.

ReadOnly Property


TcxDataSummaryItems.Add

TcxDataSummaryItems           See also

Adds a new element to the collection of summaries.

Overloaded Variants

type

  TcxSummaryKind = (skNone, skSum, skMin, skMax, skCount, skAverage);

  TcxSummaryPosition = (spGroup, spFooter);

function Add: TcxDataSummaryItem; overload;

function Add(AItemLink: TObject; APosition: TcxSummaryPosition; AKind: TcxSummaryKind; const AFormat: string = ''): TcxDataSummaryItem; overload;

Description

The first overloaded variant of this method creates a new instance of the TcxDataSummaryItem class and adds it to the collection.

The second variant of the Add method allows you to initialize the ItemLink, Position, Kind, and Format properties of the created summary object via the AItemLink, APosition, AKind, and AFormat parameters, respectively.

Use the Items property to access the collection of summaries.


TcxDataSummaryItems.Create

TcxDataSummaryItems           See Also

Creates a new TcxDataSummaryItems class instance.

type

  TcxDataSummaryItemClass = class of TcxDataSummaryItem;

constructor Create(ASummary: TcxDataSummary; AItemClass: TcxDataSummaryItemClass); virtual;

Description

The constructor creates a collection of summaries.  Each summary represents an object of the AItemClass class.  The ASummary parameter specifies a TcxDataSummary class object which becomes the owner of the collection.


TcxDataSummaryItems.DefaultFormat

TcxDataSummaryItems           See Also

Retrieves the default format string for the specified value type and summary type.

function DefaultFormat(AVarType: TVarType; ASummaryKind: TcxSummaryKind; AIsFooter: Boolean): string; virtual;

Description

The DefaultFormat function retrieves the pattern to format a summary value.  The type of the value is defined by the AVarType parameter.  ASummaryKind specifies the summary type.  The AIsFooter parameter defines whether a summary is drawn within the footer panel or within the group panel.  DefaultFormat retrieves the following format strings in accordance with the argument values passed:

Summary Kind	Float values	Date/time values	Currency values
	Footer Panel	Group Panel	Footer Panel	Group Panel	Footer Panel	Group Panel
skSum	'0.00;-0.00'	'SUM=0.00;SUM=-0.00'	‘’	'SUM='	'%s;-%s'	'SUM=%s;SUM=-%s'
skMin	'MIN=0.00;MIN=-0.00'	'MIN=0.00;MIN=-0.00'	'MIN='	'MIN='	'MIN=%s;MIN=-%s'	'MIN=%s;MIN=-%s'
skMax	'MAX=0.00;MAX=-0.00'	'MAX=0.00;MAX=-0.00'	'MAX='	'MAX='	'MAX=%s;MAX=-%s'	'MAX=%s;MAX=-%s'
skCount	'0'	'COUNT=0'	‘0’	'COUNT=0'	'0'	'COUNT=0'
skAverage	'AVG=0.00;AVG=-0.00'	'AVG=0.00;AVG=-0.00'	'AVG='	'AVG='	'AVG=%s;AVG=-%s'	'AVG=%s;AVG=-%s'

The DefaultFormat method is called to determine the format pattern if the Format property of your summary is set to an empty string.


TcxDataSummaryItems.DeleteItems

TcxDataSummaryItems           See also

Removes the collection element displayed at the specified position and associated with a specific item.

type

  TcxSummaryPosition = (spGroup, spFooter);

procedure DeleteItems(AItemLink: TObject; APosition: TcxSummaryPosition);

Description

The AItemLink parameter references the item.  Refer to the description of the ItemLink property for additional information.

The APosition parameter specifies the panel where the collection element is displayed.  Refer to the description of the Position property for more information.


TcxDataSummaryItems.IndexOfItemLink

TcxDataSummaryItems           See also

Determines the position of the collection element which references a specific item.

function IndexOfItemLink(AItemLink: TObject): Integer;

Description

The IndexOfItemLink function returns the index of the collection element which references a specific item via the ItemLink property.  If the current collection does not contain the TcxDataSummaryItem object which references AItemLink, the function returns –1.  The items collection is maintained by the Items property.

You can use the ItemOfItemLink method to retrieve the TcxDataSummaryItem object itself instead of its index.


TcxDataSummaryItems.ItemOfItemLink

TcxDataSummaryItems           See also

Determines the TcxDataSummaryItem object which references a specific item.

function ItemOfItemLink(AItemLink: TObject): TcxDataSummaryItem;

Description

The ItemOfItemLink function returns the TcxDataSummaryItem object contained in the current collection which references AItemLink via the ItemLink property.  If the current collection does not contain such an object, the function returns nil.  The items collection is maintained by the Items property.

You can use the IndexOfItemLink method to retrieve the index of the appropriate TcxDataSummaryItem object instead of the object itself.


TcxDataSummaryItems.OnSummary

TcxDataSummaryItems           See Also          Example1          Example2

Occurs when calculating a specific summary value.

type

  TcxSummaryEvent = procedure(ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments; var OutArguments: TcxSummaryEventOutArguments) of object;

property OnSummary: TcxSummaryEvent;

Description

Calculation of a summary involves iteration through item elements within a group and evaluation of a specific number (the number of item elements, sum, maximum of their values etc.).  If a footer summary is calculated, the group will contain all records within the grid control.

The OnSummary event occurs for every item element within a group.  Write an OnSummary event handler to change the default behavior of summary calculation.  For instance, you can exclude NULL values from the calculation (count only non-NULL elements) or replace an element value with another value.  The Arguments and OutArguments parameters allow you to identify the currently calculated summary and change the default behavior.

The ASender parameter specifies the summary collection, which contains the TcxDataSummaryItem summary being calculated.


TcxSummaryEventArguments

See also

Represents input arguments of the OnSummary event.

type

  TcxSummaryEventArguments = record

    RecordIndex: Integer;

    SummaryItem: TcxDataSummaryItem;

  end;

Description

Calculation of a summary involves iteration of item elements within a group and evaluation of a specific number (the number of item elements, sum, maximum of their values etc.).  The OnSummary event occurs for every item element within a group.

The TcxSummaryEventArguments type describes input arguments of the OnSummary event.  The following table describes the type fields:

Field	Meaning
RecordIndex	Specifies the record index which contains a specific item element.  The record index can be used to identify a record in a data controller using the TcxCustomDataController.Values property.
SummaryItem	Identifies the currently calculated summary of the TcxDataSummaryItem type.

Output arguments of the OnSummary event are provided by the TcxSummaryEventOutArguments type.


TcxSummaryEventOutArguments

See also

Represents output arguments of the OnSummary event.

type

  TcxSummaryEventOutArguments = record

    Value: Variant;

    SummaryValue: Variant;

    CountValue: Integer;

    Done: Boolean;

  end;

Description

Calculation of a summary involves iteration of item elements within a group and evaluation of a specific number (the number of item elements, sum, maximum of their values etc.).  The OnSummary event occurs for every item element within a group.

The TcxSummaryEventArguments type describes input arguments of the OnSummary event.  The following table describes type fields:

Field	Meaning
Value	Specifies the value of the item element for which the OnSummary event occurred.
SummaryValue	Identifies the intermediate summary value which was calculated in previous iterations. Assume, a sum of elements is calculated.  In the second iteration the SummaryValue contains the first element value.  In the third iteration SummaryValue specifies the sum of values of two previous elements, etc. SummaryValue is evaluated internally based on the summary type (sum, maximum of values, number of elements etc.) and the element value provided by the Value field.
CountValue	Determines the number of records for which the OnSummary event has already occurred to calculate a specific summary of the TcxDataSummaryItem type.
Done	Specifies whether the current Value should be ignored.  If True, Value is not used to calculate a summary value.  By default, Done is always set to False and all element values are involved in summary calculation.

Input arguments of the OnSummary event are provided by the TcxSummaryEventArguments type.


TcxCustomDataSource
TcxCustomDataSource Object

Hierarchy          Properties          Methods             See also            Example

Represents a custom data source for a grid control.

Unit

cxCustomData

TcxCustomDataSource = class(TObject);

Description

The TcxCustomDataSource class provides the base functionality to implement a user-defined data source.  You can inherit your own class from TcxCustomDataSource to force your grid to display arbitrary data.  To do so, several methods must be overridden.  As a rule, you have to implement your custom data source when it is necessary to display information from an aggregate data structure within a grid control (for instance, a tree structure, a cluster of linked objects, a list, etc.).  To set a custom data source for a grid control, use the CustomDataSource property.  When a data controller retrieves data from a custom data source it is operating in provider mode.

The main methods that you should override are GetRecordCount, GetValue, SetValue, InsertRecord, AppendRecord and DeleteRecord.

The GetRecordCount method returns the number of records the grid control should display.  The GetValue and SetValue methods enable the retrieving and setting of the values for the specified record and item (column).  Other methods are called by the data controller, when a user inserts, appends and deletes a specific record.

Read the following notes carefully to understand the most important issues when implementing a custom data source.

Let’s consider a structure of objects, each of which contains several fields (for instance, ID and Name) to be displayed in a grid control.

Every field is displayed in a separate column.  The first issue is that you have to uniquely identify these columns.  The item index (the visible index of a column) can be used as an item handle (a value that uniquely identifies a column) only if a user does not change column order.  By default the TcxCustomDataSource class does not solve the problem of changing column order: the GetItemHandle method simply returns the passed item index as an item handle.  To solve this problem in a derived class you have to override the GetItemHandle method.

You can use the column’s DataBinding.Data property to recognize a column.  For instance, you can use this property as you wish to set a unique value (integer, pointer or some other).

//Delphi

with AGridTableView do

  begin

    with CreateColumn as TcxGridColumn do

      begin

        //...

        Caption := 'ID';

        DataBinding.Data := Pointer(0);

      end;

    with CreateColumn as TcxGridColumn do

      begin

        //...

        Caption := 'Name';

        DataBinding.Data := Pointer(1);

      end;

    //...

  end;

// C++ Builder

TcxGridColumn *AColumn = (TcxGridColumn *)(AGridTableView -> CreateColumn());

AColumn -> Caption = "ID";

AColumn -> DataBinding -> Data = Pointer(0);

//...

AColumn = (TcxGridColumn *)(AGridTableView -> CreateColumn());

AColumn -> Caption = "Name";

AColumn -> DataBinding -> Data = Pointer(1);

//...

You can retrieve an item handle by reading a value of the TcxGridColumn.DataBinding, or TcxGridColumn.DataBinding.Data property in the GetItemHandle method.

// Delphi

function TUserDataSource.GetItemHandle(AItemIndex: Integer): TcxDataItemHandle;

var GridColumn: TcxCustomGridTableItem;

begin

  GridColumn :=
    TcxCustomGridTableItem(DataController.GetItem(AItemIndex));

  Result := TcxDataItemHandle(GridColumn.DataBinding);

end;

// C++ Builder

void* __fastcall TUserDataSource::GetItemHandle(int AItemIndex) {

  TcxCustomGridTableItem *GridColumn = (TcxCustomGridTableItem*)
    DataController->GetItem(AItemIndex);

  return GridColumn->DataBinding;

}

An item handle retrieved by GetItemHandle is passed to the GetValue, GetInfoForCompare and GetDisplayText methods.  It identifies the actual column required for data returned from the corresponding field of an object.

The second issue relates to record manipulations: they must also be uniquely identified.  The record index is the visible position of a record.  Since sorting records can change their record indexes they cannot be used as identifiers, but every record in a grid control has a record handle which is used as a unique identifier.  Before data is obtained from a custom data source for the first time, the data controller invokes the GetRecordHandle method for each record in the custom data source and stores the record handle retrieved.  By default, GetRecordHandle simply returns the passed record index as a record handle.

The following image displays record indexes and record handles before and after sorting in descending order.

You can override the default behavior of the GetRecordHandle method and provide, for instance, pointers to specific objects as record handles.


TcxCustomDataSource Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomDataSource
TcxCustomDataSource Properties

TcxCustomDataSource          Legend

In TcxCustomDataSource

DataController


Methods for TcxCustomDataSource
TcxCustomDataSource Methods

TcxCustomDataSource          Legend

In TcxCustomDataSource

AppendRecord

DataChanged

DeleteRecord

GetDefaultItemID

GetDisplayText

GetInfoForCompare

GetItemHandle

GetRecordHandle

GetRecordHandleByIndex

GetRecordCount

GetRecordId

GetRecordIndexByHandle

GetValue

InsertRecord

IsNativeCompare

IsRecordIdSupported

SetRecordCount

SetValue


TcxCustomDataSource.DataController

TcxCustomDataSource

Specifies the data controller which obtains records from the current data source.

property DataController: TcxCustomDataController;

Description

Use the DataController property to define the data controller object which retrieves data from the current data source.

ReadOnly Property


TcxCustomDataSource.DataChanged

TcxCustomDataSource           See Also

Notifies a data controller of data changes in the current data source.

procedure DataChanged; virtual;

Description

Call this method after data provided by the custom data source has been changed (when you insert or delete records).  The DataChanged method forces the grid control to re-read data from the data source.


TcxCustomDataSource.GetDefaultItemID

TcxCustomDataSource

Returns the unique identifier of a column at the specified position.

function GetDefaultItemID(AItemIndex: Integer): Integer; virtual;

Description

The GetDefaultItemID function returns the unique identifier of a view item (a column) at the position specified by the AItemIndex parameter (its current visible position amongst the other view items).  See the TcxCustomDataSource class to learn more about item indexes.

Call this function to identify a view item (a column) at a specific position.


TcxCustomDataSource.GetDetailHasChildren

TcxCustomDataSource

Indicates whether the specified record has child records.

function GetDetailHasChildren(ARecordIndex, ARelationIndex: Integer): Boolean; virtual;

Description

Override the GetDetailHasChildren method to specify whether a record has child records in a particular detail.  The master record is identified via the ARecordIndex parameter.  The ARelationIndex parameter specifies the zero-based index of the master-detail relationship in the current data controller.

This method should return True if the specified record has child records, otherwise it should return False.  As implemented in the TcxCustomDataSource class, the method returns False always.


TcxCustomDataSource.GetDisplayText

TcxCustomDataSource           See also

Returns the text representation of a value in a specific record/column.

function GetDisplayText(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle): string; virtual;

Description

The GetDisplayText function returns the text representation of a value in a specific record/column.  The ARecordHandle parameter identifies the record handle (a unique identifier of a record) in the current data source.  The AItemHandle parameter determines the item handle (a value that uniquely identifies the column and thus the field from which to return the text to display).  See the TcxCustomDataSource class to obtain detailed information on record and item handles.

Before calling GetDisplayText, the GetRecordHandleByIndex and GetItemHandle methods are invoked.  They return the record handle and the item handle respectively, which are passed as arguments to the GetDisplayText method.


TcxCustomDataSource.GetInfoForCompare

TcxCustomDataSource           See also          Example

Locates data in memory for a specific record/column.

function GetInfoForCompare(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle;
var PValueBuffer: PChar): Boolean; virtual;

Description

The GetInfoForCompare method allows you to implement a faster comparison operation for values in a custom data source.  In this instance, you must also override the IsNativeCompare function which returns True.

The ARecordHandle parameter identifies the record handle (a unique identifier of a record) in the current data source.  The AItemHandle parameter determines the item handle (a value that uniquely identifies the column and thus the field from which to return the text to display).  See the TcxCustomDataSource class to obtain detailed information on record and item handles.

Before calling GetInfoForCompare, the GetRecordHandleByIndex and GetItemHandle methods are invoked.  They return the record handle and the item handle respectively which are passed as arguments to the GetInfoForCompare method.

The GetInfoForCompare method returns the pointer in memory at which the value for a specific record/column is located.  The comparison procedure determines the type of values to compare by reading the TcxGridColumn.DataBinding.ValueTypeClass property.

The function returns True if the pointer to a specific value is located.  Otherwise, it returns False.


TcxCustomDataSource.GetItemHandle

TcxCustomDataSource           See also

Returns the item handle for a column at a specified position.

function GetItemHandle(AItemIndex: Integer): TcxDataItemHandle; virtual;

Description

The GetItemHandle method returns the item handle for a specific item index.  See the TcxCustomDataSource class to learn more about item indexes and handles.

This method is always called whenever it is necessary to determine an item handle in order to pass to other methods of the TcxCustomDataSource class.


TcxCustomDataSource.GetRecordCount

TcxCustomDataSource           See Also

Specifies the number of records in the current data source.

function GetRecordCount: Integer; virtual;

Description

The GetRecordCount function returns the number of records to display in a grid control.  If you insert or delete records, you must call the DataChanged method.


TcxCustomDataSource.GetRecordHandle

TcxCustomDataSource

Returns the record handle for a specific record’s index before the data controller retrieves data from the data source for the first time.

function GetRecordHandle(ARecordIndex: Integer): TcxDataRecordHandle; virtual;

Description

By default, the GetRecordHandle method retrieves the same value as the ARecordIndex parameter.  The GetRecordHandle method is called for every record in the data source before the data controller retrieves data from it.  The number of records is determined by the GetRecordCount function.  See the TcxCustomDataSource class to learn more about record indexes and handles.

Record handles retrieved by this method are stored in an internal array along with record indexes.  When displaying data, record handles are retrieved from this array for specific record indexes by the GetRecordHandleByIndex method.


TcxCustomDataSource.GetRecordHandleByIndex

TcxCustomDataSource           See also

Returns the record handle for a specific record’s index when the grid control displays data from the current data source.

function GetRecordHandleByIndex(ARecordIndex: Integer): TcxDataRecordHandle;

Description

The GetRecordHandleByIndex method retrieves a record handle by a specific record index.  See the TcxCustomDataSource class for details on record indexes and handles.  By default, this method returns the record handle, produced by GetRecordHandle and stored in an internal array.  The reverse operation is performed by the GetRecordIndexByHandle method.


TcxCustomDataSource.GetRecordId

TcxCustomDataSource

Returns a value uniquely identifying a record.

function GetRecordId(ARecordHandle: TcxDataRecordHandle): Variant; virtual;

Description

Use the GetRecordId method to obtain the unique identifier for a dataset record.  The ARecordHandle parameter specifies the handle of a dataset record whose identifier is obtained.

The return value of this method is used when saving or restoring the expansion and selection state of the records (see the SaveKeys and RestoreKeys methods descriptions).  The record identifiers, unlike the record handles and indexes, are not changed when the number and order of records within the data set changes (see the TcxCustomDataSource class description for information on record indexes and record handles).

Override the IsRecordIdSupported and GetRecordId methods when implementing custom datasource (provider mode of the Express DataController).


TcxCustomDataSource.GetRecordIndexByHandle

TcxCustomDataSource           See also

Returns the record index for a specific record handle when the grid control displays data from the current data source.

function GetRecordIndexByHandle(ARecordHandle: TcxDataRecordHandle): Integer;

Description

The GetRecordIndexByHandle method retrieves the record index for a specific record handle.  See the TcxCustomDataSource class to obtain detailed information on record indexes and handles.  The GetRecordIndexByHandle method performs the reverse of the GetRecordHandleByIndex operation.


TcxCustomDataSource.GetValue

TcxCustomDataSource           See also

Returns a value in a specific record/column.

function GetValue(ARecordHandle: TcxDataRecordHandle;
AItemHandle: TcxDataItemHandle): Variant; virtual;

Description

The GetValue function returns a value in a specific record/column.  The ARecordHandle parameter identifies the record handle (a unique identifier of a record) in the current data source.  The AItemHandle parameter determines the item handle (a value that uniquely identifies the column and thus the field from which to return the text to display).  See the TcxCustomDataSource class to obtain detailed information on record and item handles.

Before calling GetValue, the GetRecordHandleByIndex and GetItemHandle methods are invoked.  They return the record handle and the item handle respectively to be passed as arguments to the GetValue method.


TcxCustomDataSource.IsNativeCompare

TcxCustomDataSource           See also

Specifies whether fast comparison operations are supported by the current data source.

function IsNativeCompare: Boolean; virtual;

Description

The IsNativeCompare function returns True if fast comparison operations are supported by a custom data source.  In this instance, the GetInfoForCompare method provides direct access in memory to the value of a specific record/column.

If the function returns False, then values to compare are obtained via the GetValue method.  This operation is more time consuming as it involves conversions of Variant types.


TcxCustomDataSource.IsRecordIdSupported

TcxCustomDataSource          See Also

Indicates whether the record identifiers are supported.

function IsRecordIdSupported: Boolean; virtual;

Description

Use the IsRecordIdSupported method to determine whether the record identifiers are supported by the current data source.  These identifiers, unlike the record handles and indexes, are not changed when the number and order of records within the data set changes (see the TcxCustomDataSource class description for information on record indexes and record handles).

Call the GetRecordId method to obtain the record’s identifier via the record handle.


TcxCustomDataSource.AppendRecord

TcxCustomDataSource          See Also           Example

Appends a new record to the current custom data source.

function AppendRecord: TcxDataRecordHandle; virtual;

Description

The AppendRecord function is called when a user:

•	appends a new record within a custom data source, for instance, by using the data controller’s Append method.  In a grid control, the method is called when the user presses the down arrow key when focus is on the last record and the view’s OptionsData.Appending property is set to True.

•	inserts a new record into an empty data source.  A record can be inserted by using the data controller’s InsertRecord method.  In a grid control, a user can insert a record by pressing the INSERT key within a grid view.

You should implement AppendRecord to add a new record at the end of your custom data source.  You must also return the handle of the new record, which will be further used as the record’s unique identifier.  See the TcxCustomDataSource class description for information on record handles.

When implementing the AppendRecord method, you should call the DataChanged method to notify the data controller of data changes.


TcxCustomDataSource.DeleteRecord

TcxCustomDataSource          See Also

Deletes a record from a custom data source.

procedure DeleteRecord(ARecordHandle: TcxDataRecordHandle); virtual;

Description

The DeleteRecord method is called when a record must be deleted from a custom data source.  For instance, the method is called by the data controller’s DeleteRecord method.

In a grid control, a user is able to delete a record by pressing the DEL key if the view’s OptionsData.Deleting property is set to True.  This calls the DeleteRecord method.

You must implement the DeleteRecord method to delete corresponding data from your custom data source.  After deleting, you should invoke the DataChanged method to notify the data controller of the changes made.

Records are identified by the ARecordHandle parameter.  Refer to the TcxCustomDataSource class description for information on record handles.


TcxCustomDataSource.InsertRecord

TcxCustomDataSource          See Also           Example

Inserts a new record in a custom data source above a specific record.

function InsertRecord(ARecordHandle: TcxDataRecordHandle): TcxDataRecordHandle; virtual;

Description

The InsertRecord method is called when a user inserts a new record within the current custom data source, for instance, by using the data controller’s InsertRecord function.

In a grid control, records are inserted in a view when the end user presses the INS key.  This functionality is enabled if the view’s OptionsData.Inserting property is set to True.  Otherwise, pressing the INS key performs no action.

When implementing the InsertRecord method, you should insert a new empty record within your custom data source and then call the DataChanged method.  You should also return the handle of the new record (a unique value which will be used later as this record’s identifier).

The ARecordHandle parameter specifies the handle of the record above which a new record should be inserted.  See the TcxCustomDataSource class description for information on record handles.


TcxCustomDataSource.SetRecordCount

TcxCustomDataSource          See Also

Sets the number of records in the current data source.

procedure SetRecordCount(ARecordCount: Integer); virtual;

Description

Implement the SetRecordCount method to enable a user to explicitly specify the number of records within the current custom data source.  SetRecordCount is called when the data controller’s RecordCount property is assigned a value in provider mode.

The ARecordCount parameter specifies the new value assigned to RecordCount.

After you change the number of records in your custom data source, call the DataChanged method, which notifies the data controller of the changes made and forces it to reload data.


TcxCustomDataSource.SetValue

TcxCustomDataSource          See Also

Sets a value in a specific record/item.

procedure SetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle; const AValue: Variant); virtual;

Description

You should implement the SetValue method to enable a user to modify cell values in provider mode.  SetValue is called when you set a value for a specific record/item via the data controller’s Values property.

In a grid control, SetValue is called when the end user changes a cell value within a grid view.  The new value is passed as the AValue parameter.

You should override the SetValue method to insert new data into a specific field of your custom data source.

The record to be modified is specified by the ARecordHandle parameter.  It represents the value used to uniquely identify the record among other records.  AItemHandle determines the item handle (a value which uniquely identifies the item and thus the field to modify).

Before calling SetValue, the GetRecordHandleByIndex and GetItemHandle methods are invoked.  They return the record handle and the item handle respectively to be passed as arguments to the SetValue method.


TcxDataRecordHandle type

Represents a record handle.

Unit

cxCustomData

type

  TcxDataRecordHandle = Pointer;

Description

A record handle uniquely identifies a record in the custom data source provided by a TcxCustomDataSource instance.  A record handle can be an integer value or a pointer to the object from which to return data.  See the TcxCustomDataSource class to obtain detailed information on record handles.


TcxDataItemHandle type

Represents an item handle.

Unit

cxCustomData

type

  TcxDataItemHandle = Pointer;

Description

An item handle uniquely identifies the grid column for which to return a value in a specific record from a TcxCustomDataSource instance.  See the TcxCustomDataSource class to obtain detailed information on item handles.


Using provider mode
Using provider mode: Base class structure

See also

The following topics describe how to implement a custom data source providing price list records to display within a grid:

1. Base class structure

2. TPriceList

3. TUserDataSource

4. Creating columns

5. Full code

In the example, the grid control is populated with data from the TPriceList object, which supports the collection of TListEntry elements.  TListEntry elements are displayed as records in our grid control.  Every grid column presents data from a specific TListEntry field.  The TUserDataSource class provides the grid with data from TPriceList.

1. Base class structure

Three main types are defined:

•	TListEntry represents a single record in the list.  Every record contains the Description, OnHand, and Price fields, which will be displayed within three grid columns.

//Delphi

  PListEntry = ^TListEntry;

  TListEntry = packed record

    Description: string;

    OnHand: Integer;

    Price: Currency;

  end;

//C++ Builder

struct TListEntry {

  String Description;

  int OnHand;

  Currency Price;

};

typedef  ::TListEntry* PListEntry;

•	TPriceList is the list of TListEntry records.

//Delphi

  TPriceList = class

  private

    FRecords: TList;

  public

    constructor Create;

    destructor Destroy; override;

    procedure Add(ADescription: string; AOnHand: Integer;
    APrice: Currency);

    procedure Clear;

  end;

//C++ Builder

class TPriceList

{

public:

  TPriceList();

  ~TPriceList();

  void Add(String ADescription, int AOnHand, Currency APrice);

  void Clear();

  TList *FRecords;

};

•	TUserDataSource implements a custom data source for your grid control by deriving methods of the TcxCustomDataSource class.

//Delphi

  TUserDataSource = class(TcxCustomDataSource)

  private

    FPriceList: TPriceList;

    function GetDataBinding(AItemIndex: Integer):

    TcxGridItemDataBinding;

  protected

    function GetInfoForCompare(ARecordHandle: TcxDataRecordHandle;

    AItemHandle: TcxDataItemHandle; var PValueBuffer: PChar):

    Boolean; override;

    function GetItemHandle(AItemIndex: Integer): TcxDataItemHandle;

    override;

    function GetRecordCount: Integer; override;

    function GetValue(ARecordHandle: TcxDataRecordHandle;AItemHandle:

    TcxDataItemHandle): Variant; override;

    function IsNativeCompare: Boolean; override;

  public

    constructor Create(APriceList: TPriceList);

  end;

//C++ Builder

class TUserDataSource  : public TcxCustomDataSource

{

private:

 TPriceList *FPriceList;

 TcxGridItemDataBinding* GetDataBinding(int AItemIndex);

protected:

  bool __fastcall GetInfoForCompare(void * ARecordHandle,
  void * AItemHandle, char * &PValueBuffer);

  void* __fastcall GetItemHandle(int AItemIndex);

  int __fastcall GetRecordCount();

  Variant __fastcall GetValue(void * ARecordHandle,
  void * AItemHandle);

  bool __fastcall IsNativeCompare();

public:

  TUserDataSource(TPriceList *APriceList);

};

In the next section the TPriceList class implementation is outlined.


Using provider mode: TPriceList

See also

1. Base class structure

2. TPriceList

3. TUserDataSource

4. Creating columns

5. Full code

2. TPriceList

The implementation of the TPriceList class is simple.  An empty list is created in the constructor.  The Add method adds a new record and initializes it with specified parameters.

//Delphi

{ TPriceList }

constructor TPriceList.Create;

begin

  FRecords := TList.Create;

end;

destructor TPriceList.Destroy;

begin

  Clear;

  FRecords.Free;

  inherited Destroy;

end;

procedure TPriceList.Add(ADescription: string; AOnHand: Integer; APrice: Currency);

var

  P: PListEntry;

begin

  New(P);

  FRecords.Add(P);

  P^.Description := ADescription;

  P^.OnHand := AOnHand;

  P^.Price := APrice;

end;

procedure TPriceList.Clear;

begin

  while FRecords.Count > 0 do

  begin

    Dispose(PListEntry(FRecords[FRecords.Count - 1]));

    FRecords.Delete(FRecords.Count - 1);

  end;

end;

//C++ Builder

// TPriceList

TPriceList::TPriceList()

{

  FRecords = new TList;

}

TPriceList::~TPriceList()

{

  Clear();

  delete FRecords;

}

void TPriceList::Add(String ADescription, int AOnHand, Currency APrice)

{

  ::PListEntry P = new ::TListEntry;

  FRecords->Add(P);

  P->Description = ADescription;

  P->OnHand = AOnHand;

  P->Price = APrice;

}

void TPriceList::Clear()

{

  while (FRecords->Count > 0)

  {

    delete FRecords->Items[FRecords->Count - 1];

    FRecords->Delete(FRecords->Count - 1);

  }

}

The next section shows the implementation of the TUserDataSource class.


Using provider mode: TUserDataSource

See also

1. Base class structure

2. TPriceList

3. TUserDataSource

4. Creating columns

5. Full code

3. TUserDataSource

The TUserDataSource class overrides several TcxCustomDataSource methods.

A grid column displays data from a specific field of the TListEntry type.  To uniquely identify a column in the GetValue and GetInfoForCompare methods, use its DataBinding.Data property.  When your column is created (see below), its DataBinding.Data property is initialized with a unique value.  The overridden GetItemHandle method returns the DataBinding property value, which is internally passed to the GetValue and GetInfoForCompare methods as an item handle.

GetInfoForCompare retrieves a pointer to the memory address where the required value resides.  This function allows you to implement fast sorting operations. Finally, the IsNativeCompare function must be set to True in this instance.

//Delphi

{Constants used for column identification}

const

  DescriptionID = 0;

  OnHandID = 1;

  PriceID = 2;

//C++ Builder

const

  DescriptionID = 0,

  OnHandID = 1,

  PriceID = 2;

//Delphi

{ TUserDataSource }

constructor TUserDataSource.Create(APriceList: TPriceList);

begin

  inherited Create;

  FPriceList := APriceList;

end;

{

Returns the TcxGridColumn.DataBinding property for a specified visible index of a column. This property is initialized when a grid column is created.

}

function TUserDataSource.GetDataBinding(AItemIndex: Integer): TcxGridItemDataBinding;

begin

  Result := TcxCustomGridTableItem(DataController.GetItem(AItemIndex)).DataBinding;

end;

{

Returns TcxGridColumn.DataBinding as an item handle for a specified visible index of a column

}

function TUserDataSource.GetItemHandle(AItemIndex: Integer):
TcxDataItemHandle;

begin

  Result := TcxDataItemHandle(GetDataBinding(AItemIndex));

end;

{

Returns a pointer to the memory address at which the value of the desired field resides. AItemHandle is an item handle retrieved by the GetItemHandle method.

}

function TUserDataSource.GetInfoForCompare(
ARecordHandle: TcxDataRecordHandle;
AItemHandle: TcxDataItemHandle; var PValueBuffer: PChar): Boolean;

var

  ADataBinding: TcxGridItemDataBinding;

begin

  ADataBinding := TcxGridItemDataBinding(AItemHandle);

  with PListEntry(FPriceList.FRecords[Integer(ARecordHandle)])^ do

  begin

    case Integer(ADataBinding.Data) of

      DescriptionID:

        PValueBuffer := @Description;

      OnHandID:

        PValueBuffer := @OnHand;

      PriceID:

        PValueBuffer := @Price;

    end;

  end;

  Result := True;

end;

{

Returns the number of records to display in a grid control.

}

function TUserDataSource.GetRecordCount: Integer;

begin

  Result := FPriceList.FRecords.Count;

end;

{

Returns a specific field value from the TListEntry object. ARecordHandle identifies a record in the list. AItemHandle is an item (column) handle retrieved by the GetItemHandle method.

}

function TUserDataSource.GetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle): Variant;

var

  ADataBinding: TcxGridItemDataBinding;

  ARecordIndex: Integer;

begin

  ADataBinding := TcxGridItemDataBinding(AItemHandle);

  ARecordIndex := Integer(ARecordHandle);

  with TListEntry(FPriceList.FRecords[ARecordIndex]^) do

  begin

    case Integer(ADataBinding.Data) of

      DescriptionID:

        Result := Description;

      OnHandID:

        Result := OnHand;

      PriceID:

        Result := Price;

    end;

  end;

end;

{

Since the TUserDataSource provides the GetInfoForCompare procedure, the IsNativeCompare function should return True.

}

function TUserDataSource.IsNativeCompare: Boolean;

begin

  Result := True;

end;

//C++ Builder

//TUserDataSource

TUserDataSource::TUserDataSource(TPriceList *APriceList) : TcxCustomDataSource()

{

  FPriceList = APriceList;

}

/*

Returns the TcxGridColumn.DataBinding property for a specified visible index of a column. This property is initialized when a grid column is created.

*/

TcxGridItemDataBinding* TUserDataSource::GetDataBinding(int AItemIndex)

{

  return ((TcxCustomGridTableItem*)DataController->

    GetItem(AItemIndex))->DataBinding;

}

/*

Returns TcxGridColumn.DataBinding as an item handle for a specified visible index of a column

*/

void* __fastcall TUserDataSource::GetItemHandle(int AItemIndex)

{

  return (TcxDataItemHandle*)GetDataBinding(AItemIndex);

}

/*

Returns a pointer to the memory address at which the value of the desired field resides. AItemHandle is an item handle retrieved by the GetItemHandle method.

*/

bool __fastcall TUserDataSource::GetInfoForCompare(void * ARecordHandle, void * AItemHandle, char * &PValueBuffer)

{

  TcxGridItemDataBinding * ADataBinding =

  (TcxGridItemDataBinding*)AItemHandle;

  int ARecordIndex = (int)ARecordHandle;

  ::PListEntry APEntry = (::PListEntry)(*FPriceList->FRecords)

  [ARecordIndex];

  switch (int(ADataBinding->Data))

  {

    case DescriptionID:

      PValueBuffer = (char*)&APEntry->Description;

      break;

    case OnHandID:

      PValueBuffer = (char*)&APEntry->OnHand;

      break;

    case PriceID:

      PValueBuffer = (char*)&APEntry->Price;

      break;

  }

  return true;

}

/*

Returns the number of records to display in a grid control

*/

int __fastcall TUserDataSource::GetRecordCount()

{

  return FPriceList->FRecords->Count;

}

/*

Returns a specific field value from the TListEntry object. ARecordHandle identifies a record in the list. AItemHandle is an item (column) handle retrieved by the GetItemHandle method.

*/

Variant __fastcall TUserDataSource::GetValue(void * ARecordHandle, void * AItemHandle)

{

  TcxGridItemDataBinding *ADataBinding =

    (TcxGridItemDataBinding*)AItemHandle;

  int ARecordIndex = (int)ARecordHandle;

  ::PListEntry APEntry =

    (::PListEntry)(*FPriceList->FRecords) [ARecordIndex];

  switch (int(ADataBinding->Data))

  {

    case DescriptionID:

      return APEntry->Description;

    case OnHandID:

      return APEntry->OnHand;

    case PriceID:

      return APEntry->Price;

  }

}

/*

Since the TUserDataSource provides the GetInfoForCompare procedure, the IsNativeCompare function should return True.

*/

bool __fastcall TUserDataSource::IsNativeCompare()

{

  return true;

}

The creation of grid columns and the initialization of the TcxGridColumn.DataBinding.Data property is provided in the next topic.


Using provider mode: Creating columns

See also

1. Base class structure

2. TPriceList

3. TUserDataSource

4. Creating columns

5. Full code

4. Creating columns

The GenerateColumns method creates columns in a grid control, and this presents data from the TPriceList object.  It also assigns every column a unique value via the TcxGridColumn.DataBinding.Data property used to identify it in the GetValue and GetInfoForCompare methods.

GenerateColumns sets the type for values in columns via the TcxGridColumn.DataBinding. ValueTypeClass property.

//Delphi

procedure GenerateColumns(AGridTableView: TcxGridTableView);

begin

  with AGridTableView do

  begin

    OptionsSelection.HideFocusRect := False;

    OptionsSelection.MultiSelect := True;

    ClearItems;

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Description';

      DataBinding.ValueTypeClass := TcxStringValueType;

      DataBinding.Data := Pointer(DescriptionID);

      Width := 100;

    end;

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'OnHand';

      DataBinding.ValueTypeClass := TcxIntegerValueType;

      DataBinding.Data := Pointer(OnHandID);

      Width := 100;

    end;

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Price';

      DataBinding.ValueTypeClass := TcxCurrencyValueType;

      DataBinding.Data := Pointer(PriceID);

      Width := 100;

    end;

  end;

end;

//C++ Builder

void GenerateColumns(TcxGridTableView *AGridTableView)

{

  TcxGridColumn *AColumn;

  AGridTableView->OptionsSelection->HideFocusRect = false;

  AGridTableView->OptionsSelection->MultiSelect = true;

  AGridTableView->ClearItems();

  AColumn = AGridTableView->CreateColumn();

  AColumn->Caption = "Description";

  AColumn->DataBinding->ValueTypeClass = __classid (TcxStringValueType);

  AColumn->DataBinding->Data = (void*)DescriptionID;

  AColumn->Width = 100;

  AColumn = AGridTableView->CreateColumn();

  AColumn->Caption = "OnHand";

  AColumn->DataBinding->ValueTypeClass = __classid (TcxIntegerValueType);

  AColumn->DataBinding->Data = (void*)OnHandID;

  AColumn->Width = 100;

  AColumn = AGridTableView->CreateColumn();

  AColumn->Caption = "Price";

  AColumn->DataBinding->ValueTypeClass = __classid (TcxCurrencyValueType);

  AColumn->DataBinding->Data = (void*)PriceID;

  AColumn->Width = 100;

}

The next section includes the complete code used in this example.


Using provider mode: Complete Code

See also

1. Base class structure

2. TPriceList

3. TUserDataSource

4. Creating columns

5. Full code

5. Full code

The full code used to create a custom data source is listed below.

//Delphi

unit Unit1;

interface

uses

  SysUtils, Types, Classes, Graphics, Controls, Forms, Dialogs,

  StdCtrls, ExtCtrls,

  cxCustomData, cxDataStorage, cxGrid, cxGridCustomTableView, cxGridTableView;

type

  TForm1 = class(TForm)

    procedure FormCreate(Sender: TObject);

  private

    FGrid: TcxGrid;

    FTableView: TcxGridTableView;

    procedure LoadValues();

  public

    property Grid: TcxGrid read FGrid;

  end;

var

  Form1: TForm1;

implementation

{$R *.dfm}

type

  { User Objects }

  PListEntry = ^TListEntry;

  TListEntry = packed record

    Description: string;

    OnHand: Integer;

    Price: Currency;

  end;

  TPriceList = class

  private

    FRecords: TList;

  public

    constructor Create;

    destructor Destroy; override;

    procedure Add(ADescription: string; AOnHand: Integer;

    APrice: Currency);

    procedure Clear;

  end;

  TUserDataSource = class(TcxCustomDataSource)

  private

    FPriceList: TPriceList;

    function GetDataBinding(AItemIndex: Integer):

    TcxGridItemDataBinding;

  protected

    function GetInfoForCompare(ARecordHandle: TcxDataRecordHandle;

    AItemHandle: TcxDataItemHandle; var PValueBuffer: PChar):

    Boolean; override;

    function GetItemHandle(AItemIndex: Integer): TcxDataItemHandle;

    override;

    function GetRecordCount: Integer; override;

    function GetValue(ARecordHandle: TcxDataRecordHandle;AItemHandle:

    TcxDataItemHandle): Variant; override;

    function IsNativeCompare: Boolean; override;

  public

    constructor Create(APriceList: TPriceList);

  end;

var

  PriceList: TPriceList;

{ TPriceList }

constructor TPriceList.Create;

begin

  FRecords := TList.Create;

end;

destructor TPriceList.Destroy;

begin

  Clear;

  FRecords.Free;

  inherited Destroy;

end;

procedure TPriceList.Add(ADescription: string; AOnHand: Integer; APrice: Currency);

var

  P: PListEntry;

begin

  New(P);

  FRecords.Add(P);

  P^.Description := ADescription;

  P^.OnHand := AOnHand;

  P^.Price := APrice;

end;

procedure TPriceList.Clear;

begin

  while FRecords.Count > 0 do

  begin

    Dispose(PListEntry(FRecords[FRecords.Count - 1]));

    FRecords.Delete(FRecords.Count - 1);

  end;

end;

{ TUserDataSource }

constructor TUserDataSource.Create(APriceList: TPriceList);

begin

  inherited Create;

  FPriceList := APriceList;

end;

function TUserDataSource.GetDataBinding(AItemIndex: Integer): TcxGridItemDataBinding;

begin

  Result := TcxCustomGridTableItem(DataController.GetItem(AItemIndex)).DataBinding;

end;

function TUserDataSource.GetInfoForCompare(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle; var PValueBuffer: PChar): Boolean;

var

  ADataBinding: TcxGridItemDataBinding;

begin

  ADataBinding := TcxGridItemDataBinding(AItemHandle);

  PValueBuffer := PChar(Integer(FPriceList.

  FRecords[Integer(ARecordHandle)]) +

  Integer(ADataBinding.Data));

  Result := True;

end;

function TUserDataSource.GetItemHandle(AItemIndex: Integer): TcxDataItemHandle;

begin

  Result := TcxDataItemHandle(GetDataBinding(AItemIndex));

end;

function TUserDataSource.GetRecordCount: Integer;

begin

  Result := FPriceList.FRecords.Count;

end;

function TUserDataSource.GetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle): Variant;

var

  P: PChar;

  ADataBinding: TcxGridItemDataBinding;

begin

  ADataBinding := TcxGridItemDataBinding(AItemHandle);

  P := PChar(Integer(FPriceList.FRecords[Integer(ARecordHandle)]) +

  Integer(ADataBinding.Data));

  Result := ADataBinding.ValueTypeClass.GetValue(P);

end;

function TUserDataSource.IsNativeCompare: Boolean;

begin

  Result := True;

end;

{ routines }

procedure GenerateColumns(AGridTableView: TcxGridTableView);

var

  AListEntry: TListEntry;

begin

  with AGridTableView do

  begin

    OptionsSelection.HideFocusRect := False;

    OptionsSelection.MultiSelect := True;

    ClearItems;

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Description';

      DataBinding.ValueTypeClass := TcxStringValueType;

      DataBinding.Data := Pointer(0);

      Width := 100;

    end;

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'OnHand';

      DataBinding.ValueTypeClass := TcxIntegerValueType;

      DataBinding.Data := Pointer(Integer(@AListEntry.OnHand) -

      Integer(@AListEntry));

      Width := 100;

    end;

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Price';

      DataBinding.ValueTypeClass := TcxCurrencyValueType;

      DataBinding.Data := Pointer(Integer(@AListEntry.Price) -

      Integer(@AListEntry));

      Width := 100;

    end;

  end;

end;

procedure TForm1.LoadValues();

begin

  PriceList.Add('Dive kayak', 24, 3999.95);

  PriceList.Add('Underwater Diver Vehicle', 5, 1680.00);

  PriceList.Add('Regulator System', 165, 250.00);

  PriceList.Add('Personal Dive Sonar', 46, 235.00);

  PriceList.Add('Depth/Pressure Gauge', 128, 206.00);

  FTableView.DataController.CustomDataSource.DataChanged;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  FGrid := TcxGrid.Create(Self);

  with FGrid do

  begin

    FTableView := CreateView(TcxGridTableView) as TcxGridTableView;

    Levels.Add.GridView := FTableView;

    GenerateColumns(FTableView);

    FTableView.OptionsView.Footer := True;

    with FTableView.DataController.Summary.FooterSummaryItems.Add do

    begin

      Kind := skCount;

      ItemLink := FTableView.Columns[0];

    end;

    Align := alClient;

    Parent := Self;

  end;

  FTableView.DataController.CustomDataSource :=

  TUserDataSource.Create(PriceList);

  LoadValues();

end;

initialization

  PriceList := TPriceList.Create;

finalization

  PriceList.Free;

end.

//C++ Builder

//Unit1.h

#ifndef Unit1H

#define Unit1H

//-------------------------------------

#include <Classes.hpp>

#include <Controls.hpp>

#include <StdCtrls.hpp>

#include <Forms.hpp>

#include "cxgrid.hpp"

#include "cxGridTableView.hpp"

#include "cxCustomData.hpp"

//-------------------------------------

//User Objects

struct TListEntry {

  String Description;

  int OnHand;

  Currency Price;

};

typedef  ::TListEntry* PListEntry;

//-------------------------------------

class TPriceList

{

public:

  TPriceList();

  ~TPriceList();

  void Add(String ADescription, int AOnHand, Currency APrice);

  void Clear();

  TList *FRecords;

};

//-------------------------------------

class TUserDataSource  : public TcxCustomDataSource

{

private:

  TPriceList *FPriceList;

  TcxGridItemDataBinding* GetDataBinding(int AItemIndex);

protected:

  bool __fastcall GetInfoForCompare(void * ARecordHandle, void * AItemHandle, char * &PValueBuffer);

  void* __fastcall GetItemHandle(int AItemIndex);

  int __fastcall GetRecordCount();

  Variant __fastcall GetValue(void * ARecordHandle, void * AItemHandle);

  bool __fastcall IsNativeCompare();

public:

  TUserDataSource(TPriceList *APriceList);

};

//-------------------------------------

class TForm1 : public TForm

{

__published:// IDE-managed Components

private:	// User declarations

  TcxGrid *FGrid;

  TcxGridTableView *FTableView;

  TPriceList *FPriceList;

  void LoadValues();

public:	// User declarations

  __fastcall TForm1(TComponent* Owner);

  __fastcall ~TForm1();

};

//-------------------------------------

extern PACKAGE TForm1 *Form1;

//-------------------------------------

#endif

//Unit1.cpp

//-------------------------------------

#include <vcl.h>

#pragma hdrstop

#include "Unit1.h"

//-------------------------------------

#pragma package(smart_init)

#pragma resource "*.dfm"

TForm1 *Form1;

//-------------------------------------

//Constants used for column identification

const

  DescriptionID = 0,

  OnHandID = 1,

  PriceID = 2;

//-------------------------------------

// TPriceList

TPriceList::TPriceList()

{

  FRecords = new TList;

}

TPriceList::~TPriceList()

{

  Clear();

  delete FRecords;

}

void TPriceList::Add(String ADescription, int AOnHand, Currency APrice)

{

  ::PListEntry P = new ::TListEntry;

  FRecords->Add(P);

  P->Description = ADescription;

  P->OnHand = AOnHand;

  P->Price = APrice;

}

void TPriceList::Clear()

{

  while (FRecords->Count > 0)

  {

    delete FRecords->Items[FRecords->Count - 1];

    FRecords->Delete(FRecords->Count - 1);

  }

}

//-------------------------------------

//TUserDataSource

TUserDataSource::TUserDataSource(TPriceList *APriceList) : TcxCustomDataSource()

{

  FPriceList = APriceList;

}

/*

Returns the TcxGridColumn.DataBinding property for a specified visible index of a column. This property is initialized when a grid column is created.

*/

TcxGridItemDataBinding* TUserDataSource::GetDataBinding(int AItemIndex)

{

  return ((TcxCustomGridTableItem*)DataController->GetItem(AItemIndex))->DataBinding;

}

/*

Returns TcxGridColumn.DataBinding as an item handle for a specified visible index of a column

*/

void* __fastcall TUserDataSource::GetItemHandle(int AItemIndex)

{

  return (TcxDataItemHandle*)GetDataBinding(AItemIndex);

}

/*

Returns a pointer to the memory address at which the value of the desired field resides. AItemHandle is an item handle retrieved by the GetItemHandle method.

*/

bool __fastcall TUserDataSource::GetInfoForCompare(void * ARecordHandle, void * AItemHandle, char * &PValueBuffer)

{

  TcxGridItemDataBinding * ADataBinding = (TcxGridItemDataBinding*)AItemHandle;

  int ARecordIndex = (int)ARecordHandle;

  ::PListEntry APEntry = (::PListEntry)(*FPriceList->FRecords)[ARecordIndex];

  switch (int(ADataBinding->Data))

  {

    case DescriptionID:

      PValueBuffer = (char*)&APEntry->Description;

      break;

    case OnHandID:

      PValueBuffer = (char*)&APEntry->OnHand;

      break;

    case PriceID:

      PValueBuffer = (char*)&APEntry->Price;

      break;

  }

  return true;

}

/*

Returns the number of records to display in a grid control

*/

int __fastcall TUserDataSource::GetRecordCount()

{

  return FPriceList->FRecords->Count;

}

/*

Returns a specific field value from the TListEntry object. ARecordHandle identifies a record in the list. AItemHandle is an item (column) handle retrieved by the GetItemHandle method.

*/

Variant __fastcall TUserDataSource::GetValue(void * ARecordHandle, void * AItemHandle)

{

  TcxGridItemDataBinding *ADataBinding = (TcxGridItemDataBinding*)AItemHandle;

  int ARecordIndex = (int)ARecordHandle;

  ::PListEntry APEntry = (::PListEntry)(*FPriceList->FRecords)[ARecordIndex];

  switch (int(ADataBinding->Data))

  {

    case DescriptionID:

      return APEntry->Description;

    case OnHandID:

      return APEntry->OnHand;

    case PriceID:

      return APEntry->Price;

  }

}

/*

Since the TUserDataSource provides the GetInfoForCompare procedure, the IsNativeCompare function should return True.

*/

bool __fastcall TUserDataSource::IsNativeCompare()

{

  return true;

}

//-------------------------------------

//Routines

void GenerateColumns(TcxGridTableView *AGridTableView)

{

  TcxGridColumn *AColumn;

  AGridTableView->OptionsSelection->HideFocusRect = false;

  AGridTableView->OptionsSelection->MultiSelect = true;

  AGridTableView->ClearItems();

  AColumn = AGridTableView->CreateColumn();

  AColumn->Caption = "Description";

  AColumn->DataBinding->ValueTypeClass = __classid (TcxStringValueType);

  AColumn->DataBinding->Data = (void*)DescriptionID;

  AColumn->Width = 100;

  AColumn = AGridTableView->CreateColumn();

  AColumn->Caption = "OnHand";

  AColumn->DataBinding->ValueTypeClass = __classid (TcxIntegerValueType);

  AColumn->DataBinding->Data = (void*)OnHandID;

  AColumn->Width = 100;

  AColumn = AGridTableView->CreateColumn();

  AColumn->Caption = "Price";

  AColumn->DataBinding->ValueTypeClass = __classid (TcxCurrencyValueType);

  AColumn->DataBinding->Data = (void*)PriceID;

  AColumn->Width = 100;

}

//-------------------------------------

void TForm1::LoadValues()

{

  FPriceList->Add("Dive kayak", 24, 3999.95);

  FPriceList->Add("Underwater Diver Vehicle", 5, 1680.00);

  FPriceList->Add("Regulator System", 165, 250.00);

  FPriceList->Add("Personal Dive Sonar", 46, 235.00);

  FPriceList->Add("Depth/Pressure Gauge", 128, 206.00);

  FTableView->DataController->CustomDataSource->DataChanged();

}

__fastcall TForm1::TForm1(TComponent* Owner)

        : TForm(Owner)

{

  FPriceList = new ::TPriceList();

  FGrid = new TcxGrid(this);

  FGrid->Align = alClient;

  FGrid->Parent = this;

  FTableView = (TcxGridTableView*)(FGrid->CreateView(__classid(TcxGridTableView)));

  FGrid->Levels->Add()->GridView = FTableView;

  GenerateColumns(FTableView);

  FTableView->OptionsView->Footer = true;

  TcxDataSummaryItem *AItem = FTableView->DataController->Summary->FooterSummaryItems->Add();

  AItem->Kind = skCount;

  AItem->ItemLink = FTableView->Columns[0];

  FTableView->OptionsData->Appending = false;

  FTableView->OptionsData->Inserting = false;

  FTableView->DataController->CustomDataSource = new TUserDataSource(FPriceList);

  LoadValues();

}

__fastcall TForm1::~TForm1() {

  delete FPriceList;

}

//-------------------------------------


cxDBData Unit Overview
cxDBData Unit

Classes

TcxDBDataController

TcxDBDataFilterCriteria

TcxDBDataModeController

TcxDBDataSummaryItem


TcxDBDataController
TcxDBDataController Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data controller that manages data from TDataSet.

Unit

cxDBData

TcxDBDataController = class(TcxCustomDataController);

Description

The TcxDBDataController class derives from TcxCustomDataController implementing working with a user-defined data source and performing data filtration, calculation of summaries and group operations.

TcxDBDataController extends this functionality by enabling operations for TDataSet descendants.  To provide data for your grid control, you can use the DataSource property.  You cannot use TcxDBDataController in provider mode by setting the inherited CustomDataSource property.  To create a master-detail relationship between datasets, you should create a data controller for each dataset and specify the master and detail key field names via the MasterKeyFieldNames and DetailKeyFieldNames properties of the detail data controller.

In order to provide synchronization between the master and the detail data controller, it is required to set key field names via the KeyFieldNames property.

The DataModeController is used to manage the synchronization between data displayed in the data controller and the corresponding dataset.  It also controls the way data is obtained by the detail data controller linked to a parameterized query dataset.


TcxDBDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |


Properties for TcxDBDataController
TcxDBDataController Properties

TcxDBDataController          Legend

In TcxDBDataController

DataModeController

DataSource

DetailKeyFieldNames

Filter

KeyFieldNames

MasterKeyFieldNames

Derived from TcxCustomDataController

CustomDataSource

DisplayTexts

EditOperations

EditState

Filter

FilteredIndexByRecordIndex

FilteredRecordCount

FilteredRecordIndex

FocusedRecordIndex

FocusedRowIndex

Groups

IsEditing

IsPattern

MultiSelect

Options

RecordCount

RowCount

Search

Summary

Values


Methods for TcxDBDataController
TcxDBDataController Methods

TcxDBDataController          Legend

In TcxDBDataController

BeginLocate

ChangeFieldName

EndLocate

GetItemByFieldName

GetItemField

GetItemFieldName

GetRecordId

GetSelectedBookmark

LocateByKey

Derived from TcxCustomDataController

Append

AppendRecord

BeginFullUpdate

BeginUpdate

Cancel

ChangeDetailExpanding

ChangeRowSelection

CheckFocusedSelected

ClearBookmark

ClearDetailLinkObject

ClearDetails

ClearSelection

ClearSorting

CollapseDetails

DeleteFocused

DeleteRecord

DeleteSelection

Edit

EndFullUpdate

EndUpdate

FindRecordIndexByText

FocusDetails

ForEachRow

GetDetailDataController

GetMasterDataController

GetMasterRecordIndex

GetPatternDataController

GetRowDisplayText

GetRowIndexByRecordIndex

GetRowInfo

GetRowValue

GetSelectedCount

GetSelectedRowIndex

GotoBookmark

GotoFirst

GotoLast

GotoNext

GotoPrev

Insert

InsertRecord

IsBOF

IsBookmarkAvailable

IsDetailMode

IsEOF

IsGridMode

IsRowSelected

LoadFromStream

MakeRecordVisible

Post

RefreshExternalData

SaveBookmark

SaveToStream

SelectAll

SelectRows

SetEditValue

SetValue

SyncSelected


Events for TcxDBDataController
TcxDBDataController Events

TcxDBDataController          Legend

In TcxDBDataController

OnDetailHasChildren

Derived from TcxCustomDataController

OnAfterCancel

OnAfterDelete

OnAfterInsert

OnAfterPost

OnBeforeCancel

OnBeforeDelete

OnBeforeInsert

OnBeforePost

OnCompare

OnDataChanged

OnDetailCollapsed

OnDetailCollapsing

OnDetailExpanded

OnDetailExpanding

OnFilterRecord

OnGroupingChanged

OnRecordChanged

OnSortingChanged


TcxDBDataController.DataModeController

TcxDBDataController           See Also

Represents a data mode controller that manages synchronization and information displayed by the detail data controller.

property DataModeController: TcxDBDataModeController;

Description

The DataModeController property allows you to establish synchronization between data in the data controller and in the corresponding TDataSet.  It also manages data retrieved by the detail data controller linked to a parameterized query dataset.


TcxDBDataController.DataSource

TcxDBDataController

Specifies the link to the dataset where the grid control finds its data.

property DataSource: TDataSource;

Description

Use the DataSource property to specify the data source component from which data is retrieved by the data controller in order to display within your grid control.


TcxDBDataController.DetailKeyFieldNames

TcxDBDataController           See Also

Identifies one or more field names in the dataset used by the current detail data controller

property DetailKeyFieldNames: string;

Description

To establish master-detail relationships between two datasets, you have to create a data controller for each and set detail & master key field names via the DetailKeyFieldNames and MasterKeyFieldNames properties of the detail controller.  Thus you link two datasets by specific fields.  The detail data controller will represent the data corresponding to a specific record in the master data controller.

Let’s examine two tables: Customers and Orders.  The Orders table stores information on orders made by different customers.  Both tables contain the CustNo field, which uniquely identifies customers.  Assume you want to display orders made by customers by navigating through the Customers table. In this case the Customers table is the master table and Orders is the detail table.  Create data controllers for the Customers & Orders tables and set the DetailKeyFieldNames & MasterKeyFieldNames properties of the detail data controller to ‘CustNo’.  The MasterKeyFieldNames property identifies the CustNo field in the Customers table and the DetailKeyFieldNames property identifies the CustNo field in the Orders table.

To link two tables by several fields, you need to specify their names in the DetailKeyFieldNames and MasterKeyFieldNames strings, separating them by a semicolon.

If the detail data controller is bound to a dataset other than a parameterized query, you have to sort the records by the fields identified by the DetailKeyFieldNames property.  In this case, a detail data controller will correctly retrieve all the corresponding records.  Otherwise, not all records can be located and retrieved from the detail dataset.  To sort a dataset represented by a TTable or TCustomADODataSet component, use its IndexFieldNames property, for instance.


TcxDBDataController.Filter

TcxDBDataController           See Also

Defines a set of filter conditions applied to a grid control.

property Filter: TcxDBDataFilterCriteria;

Description

Use the Filter property to specify the filter criteria for a grid control.  Filter criteria describe a set of filter conditions combined by logical operators.  You can add, remove filter conditions for specific items, customize the list of values for a filter condition and control the filtering process.  After you add filter conditions, you have to apply them by setting the Active property to True.

The Filter property of the TcxDBDataFilterCriteria type allows you to automatically apply the current filter conditions to the corresponding TDataSet object.


TcxDBDataController.KeyFieldNames

TcxDBDataController           See Also

Specifies one or more key field names separated by a semicolon.

property KeyFieldNames: string;

Description

The KeyFieldNames property specifies the semicolon-separated list of key field names, which uniquely identify each dataset record.  You should set key field names in the following cases:

•	if you want to perform in-sync operations on TDataSet in a detail data controller such as editing and adding records;

•	if you need to delete several selected records from the corresponding dataset;

•	if you want to speed up navigation when data in your grid control is synchronized with TDataSet.


TcxDBDataController.MasterKeyFieldNames

TcxDBDataController           See Also

Specifies a list of dataset fields in a master dataset to establish master-detail relationship between two datasets.

property MasterKeyFieldNames: string;

Description

To establish master-detail relationships between two datasets you have to create a data controller for each of them and set detail and master key field names via the DetailKeyFieldNames and MasterKeyFieldNames properties of the detail controller.  Thus you link two datasets by specific fields.  The detail data controller will represent only data that corresponds to a specific record in the master data controller.

Let’s examine two tables: Customers and Orders.  The Orders table stores information on orders that are made by different customers.  Both tables contain the CustNo field, which uniquely identifies customers.  Assume you want to display orders made by customers by navigating through the Customers table. In this case the Customers table is the master table and Orders is the detail table.  Create data controllers for the Customers & Orders tables and set the DetailKeyFieldNames & MasterKeyFieldNames properties of the detail data controller to ‘CustNo’.  The MasterKeyFieldNames property identifies the CustNo field in the Customers table and the DetailKeyFieldNames property identifies the CustNo field in the Orders table.

To link two tables by several fields, you need to specify them in the DetailKeyFieldNames and MasterKeyFieldNames strings, separating them by a semicolon.

If the detail data controller is bound to a dataset other than a parameterized query, you have to sort the records by the fields identified by the DetailKeyFieldNames property.  In this case, a detail data controller will correctly retrieve all the corresponding records.  Otherwise, not all records can be located and retrieved from the detail dataset.  To sort a dataset represented by a TTable or TCustomADODataSet component, use its IndexFieldNames property, for instance.


TcxDBDataController.BeginLocate

TcxDBDataController          See also         Example

Prevents the data controller from reloading data when you move the cursor within a dataset via the Locate, First and Last methods.

procedure BeginLocate;

Description

The BeginLocate and EndLocate methods work together.  Use these methods to prevent the data controller from reloading data when moving the cursor within the dataset with the help of TDataSet methods (Locate, First and Last).

The Locate method lets you search the dataset for a record meeting the specified criteria.  This method (as well as First and Last) changes the active dataset record and implicitly sends a change notification to the data controller.  The same notification is sent when you use TDataSet methods/properties to modify field values and insert and delete records.

On receiving the change notification, the data controller reloads records from the dataset, since it does not exactly know what has caused the notification.

When you just want to make another record active and do not want to change field values in the dataset, data reloading is unnecessary.  Also, this operation can require significant time for huge datasets.  In this case, you can consider using the BeginLocate and EndLocate methods to enclose call(s) to the Locate, First or Last methods.  After BeginLocate is called, but before EndLocate is called, the data controller assumes that you will use dataset methods only to locate specific records and that you will not change them.  On receiving the change notification, the data controller will not reload data.  However, it will reflect the new position of the active record.

BeginLocate does not disable the events related to changing the active record.  For instance, in ExpressQuantumGrid, the view’s OnFocusedRecordChanged event still occurs when changing the active dataset record.

After EndLocate is called, reloading dataset data does not occur automatically.  EndLocate enables default data reloading each time a change notification is received.

Note that every call of BeginLocate must correspond to an EndLocate call. To ensure that EndLocate is always called for BeginLocate even if an exception occurs, use a try...finally block.

If you need to iterate through records to change them, you should use the dataset’s DisableControls and EnableControls methods instead to prevent excessive updates of the data controller.


TcxDBDataController.ChangeFieldName

TcxDBDataController          See Also

Binds a specific item to a data field.

procedure ChangeFieldName(AItemIndex: Integer; const AFieldName: string);

Description

Call the ChangeFieldName method to bind the item which is addressed by the AItemIndex parameter to the data field whose name is specified by the AFieldName parameter.  The AItemIndex parameter specifies the value of the TcxCustomGridTableItem.Index property.  For instance, when working in a table view, the AItemIndex parameter determines the position of the TcxGridDBColumn object within the collection of owner columns.  When working in a card view, the AItemIndex parameter determines the position of the card row (of the TcxGridDBCardViewRow class) within the collection of owner card rows.


TcxDBDataController.EndLocate

TcxDBDataController          See also         Example

Enables data reloading suspended by the BeginLocate method.

procedure EndLocate;

Description

The BeginLocate and EndLocate methods work together.  Use these methods to avoid data reloading by the data controller when moving the cursor within the dataset with the help of TDataSet methods (Locate, First and Last).

EndLocate enables default data reloading each time a change notification is received.

See the BeginLocate topic for more information.


TcxDBDataController.FindRecordIndexByKey

TcxDBDataController          See Also

Finds the record which contains the specified key field values.

function FindRecordIndexByKey(const AKeyFieldValues: Variant): Index;

Description

The FindRecordIndexByKey function searches for the record with the specified key field value(s) and returns its index.  The AKeyFieldValues parameter specifies a variant or an array of variant values corresponding to the key field(s) set via the KeyFieldNames property.

If the record doesn’t exist or no key field names are assigned, FindRecordIndexByKey function returns -1.

The FindRecordIndexByKey method does not force the reloading of dataset data, since it searches the data controller’s internal buffer.


TcxDBDataController.GetItemByFieldName

TcxDBDataController          See Also

Returns the item which corresponds to a specific field.

function GetItemByFieldName(const AFieldName: string): TObject;

Description

The GetItemByFieldName function returns the item which corresponds to the field whose name is specified by the AFieldName parameter.  For instance, when working in a table view, the item represents an instance of the TcxGridDBColumn class.  When working in a card view, the item is a card row and represents an instance of the TcxGridDBCardViewRow class.

If the item that corresponds to the specified field is not found, the GetItemByFieldName function returns nil.


TcxDBDataController.GetItemField

TcxDBDataController          See Also

Returns the field which corresponds to a specific item.

function GetItemField(AItemIndex: Integer): TField;

Description

The GetItemField function returns the field which corresponds to the item that is addressed by the AItemIndex parameter.  The AItemIndex parameter specifies the value of the TcxCustomGridTableItem.Index property.  For instance, when working in a table view, the AItemIndex parameter determines the position of the TcxGridDBColumn object within the collection of owner columns.  When working in a card view, the AItemIndex parameter determines the position of the card row (of the TcxGridDBCardViewRow class) within the collection of owner card rows.


TcxDBDataController.GetItemFieldName

TcxDBDataController          See Also

Returns the name of the field which corresponds to a specific item.

function GetItemFieldName(AItemIndex: Integer): string;

Description

The GetItemFieldName function returns the name of the field which corresponds to the item that is addressed by the AItemIndex parameter.  The AItemIndex parameter specifies the value of the TcxCustomGridTableItem.Index property.  For instance, when working in a table view, the AItemIndex parameter determines the position of the TcxGridDBColumn object within the collection of owner columns.  When working in a card view, the AItemIndex parameter determines the position of the card row (of the TcxGridDBCardViewRow class) within the collection of owner card rows.


TcxDBDataController.GetRecordId

TcxDBDataController          See also         Example

Returns the key field value(s) for a data record.

function GetRecordId(ARecordIndex: Integer): Variant;

Description

The GetRecordId function returns the key field value(s) of the record identified by the ARecordIndex parameter.  This parameter specifies the record index, i.e. its position within the underlying dataset.

GetRecordId returns the key field values specified by the KeyFieldNames property.  If the KeyFieldNames property contains several key field names, GetRecordId returns an array of variants corresponding to each key field.

Note that if key field names are not assigned, the function returns NULL.

Key field values uniquely identify each dataset record.  Once you obtain the key field values, you can subsequently locate the record again, for instance, using the LocateByKey method.  This is useful when you want to change a set of records (for instance, selected records).  The safest approach is to store the key field values of the records to process and then loop through these records using the stored key field values.  See example.


TcxDBDataController.GetSelectedBookmark

TcxDBDataController          See also           Example

Returns a bookmark for a particular selected record when the data controller is in grid mode.

function GetSelectedBookmark(Index: Integer): TBookmarkStr;

Description

Use the GetSelectedBookmark function to access selected records when grid mode is applied.

In grid mode, the data controller automatically creates bookmarks once you select records via the ChangeRowSelection, SelectAll or SelectRows methods.  You can retrieve those bookmarks using the GetSelectedBookmark function.  The Index parameter addresses theselected record by its position within the collection of selected records.  Index can vary from 0 to GetSelectedCount – 1.

A bookmark is an object marking a particular dataset record.  This can be used to jump to this record later via the dataset’s Bookmark property.  Assigning a bookmark to the TDataSet.Bookmark property changes the current dataset record.

To iterate selected rows (data records and grouping rows) in provider, unbound and default bound modes, use the GetSelectedRowIndex method instead.

To iterate selected rows, you can also use the ForEachRow method.  This can be applied in all loading modes.

A bookmark created by the SaveBookmark method does not affect bookmarks for selected records and vice versa.  Bookmarks accessible via the GetSelectedBookmark function are created automatically, which enables you to iterate through selected records.  The SaveBookmark method allows you to mark a position in the data controller and then jump to it using the GotoBookmark method.


TcxDBDataController.LocateByKey

TcxDBDataController          See also

Finds and focuses the record containing the specified key field values.

function LocateByKey(const AKeyFieldValues: Variant): Boolean;

Description

The LocateByKey function locates the record with the specified key field value(s).  The AKeyFieldValues parameter should specify a variant or an array of variant values corresponding to the key field(s) set via the KeyFieldNames property.

The function returns True when the appropriate record is found and focused (in ExpressQuantumGrid, the view’s OnFocusedRecordChanged event is fired when changing the focused record).  If the record doesn’t exist or no key field names are assigned, LocateByKey returns False.

The LocateByKey method does not force the reloading of dataset data, since it searches its internal buffer.

The dataset’s Locate method also allows you to locate records with specific criteria.  However, each call of Locate forces the data controller to reload data from the dataset, thus slowing down performance, especially for large datasets.  To prevent data reloading when moving the cursor within the dataset, you can enclose call(s) to Locate within the BeginLocate and EndLocate methods.


TcxDBDataController.OnDetailHasChildren

TcxDBDataController

Fires when a grid view needs to determine whether a row’s detail is empty.

type

  TcxDBDataDetailHasChildrenEvent = procedure(Sender: TcxDBDataController; ARecordIndex, ARelationIndex: Integer; const AMasterDetailKeyFieldNames: string; const AMasterDetailKeyValues: Variant; var HasChildren: Boolean) of object;

property OnDetailHasChildren: TcxDBDataDetailHasChildrenEvent;

Description

The OnDetailHasChildren event is raised by grid views that have details and work in grid mode or whose details are bound to a parameterized dataset (see the DataModeController.GridMode and DataModeController.DetailInSQLMode property descriptions for details).  You only need to handle this event if you need to provide the appropriate functionality for a view’s OptionsView.ExpandButtonsForEmptyDetails option.  If this option is disabled, the view needs to determine which master records have empty details associated with them.  You must specify this manually by handling the OnDetailHasChildren event.

The OnDetailHasChildren event’s Sender parameter identifies the data controller that raised the event.  The ARecordIndex parameter specifies the master record whose detail is to be tested for the presence of data.  If there are several details associated, use the ARelationIndex parameter to identify the detail being processed.  The AMasterDetailKeyFieldNames parameter passes the names of fields in the detail table that are used to establish the master detail relationship.  If there are several fields used for this purpose, their names are separated by semicolon.  The AMasterDetailKeyFieldValues parameter returns the variant array holding values in those fields.  Use these values to locate those records belonging to the detail dataset that correspond to the specified master record.  If there are any detail records found, set the HasChildren parameter to True.  This means that the view will display the expand button for the master row being processed.  If no detail records have been found, set the parameter to False.  The master row’s expand button will not be displayed in this case.


TcxDBDataModeController
TcxDBDataModeController Object

Hierarchy          Properties          Methods          Events          See also

Represents a data mode controller, which manages data synchronization with a linked dataset.

Unit

cxDBData

TcxDBDataModeController = class(TPersistent);

Description

The TcxDBDataModeController class provides properties and events to synchronize data in a data controller (the TcxDBDataController class) with data of a linked dataset.  Use the TcxDBDataController.DataModeController property to gain access to the corresponding data mode controller.

If the DataController property identifies a detail data controller and its DataSource property is linked to a parameterized query dataset (TQuery, for instance), you need to set the DetailInSQLMode property to True.

When you expand the detail level, which displays data from a parameterized query dataset, the query is reopened with new parameter values.  This is performed automatically by the ReopenSQL method of the TcxDBProviderDetailFilterAdapter or TcxADOProviderDetailFilterAdapter class (you must add the cxADOAdapters unit to the uses section of your form if you want this to work for ADO queries).  However, you can provide your own implementation via the OnDetailFirst event.  In this event, you have to supply your query with any necessary parameter valuesand reopen it.  When you navigate through records of such a detail controller or move from one detail controller to another, the data controller must know whether to reopen the underlying query or not.  This is also performed automatically by the IsCurrentQuery method of the TcxDBProviderDetailFilterAdapter or TcxADOProviderDetailFilterAdapter class.  But you can write an OnDetailIsCurrentQuery event handler to implement it in a custom manner.  If the query should be reopened, the ReopenSQL method of the TcxDBProviderDetailFilterAdapter or TcxADOProviderDetailFilterAdapter class is called or the OnDetailFirst event is generated.


TcxDBDataModeController Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxDBDataModeController
TcxDBDataModeController Properties

TcxDBDataModeController          Legend

In TcxDBDataModeController

DataController

DetailInSQLMode

GridMode

GridModeBufferCount

SmartRefresh

SyncMode


Methods for TcxDBDataModeController
TcxDBDataModeController Methods

TcxDBDataModeController          Legend

In TcxDBDataModeController

Assign

Create


Events for TcxDBDataModeController
TcxDBDataModeController Events

TcxDBDataModeController          Legend

In TcxDBDataModeController

OnDetailFirst

OnDetailIsCurrentQuery


TcxDBDataModeController.DataController

TcxDBDataModeController           See also

Specifies the data controller for which the current data mode controller is applied.

property DataController: TcxDBDataController;

Description

Use the DataController member to access properties of the data controller with which the current data mode controller is associated.

ReadOnly Property


TcxDBDataModeController.DetailInSQLMode

TcxDBDataModeController           See Also

Determines whether the detail data controller is linked to a parameterized query dataset.

property DetailInSQLMode: Boolean;

Description

Set the DetailInSQLMode property to True to indicate that the corresponding detail DataController is linked to a parameterized query dataset (TQuery, for instance).

Parameters of a query must correspond to the detail key field names set using the DataController.DetailKeyFieldNames property.

When opening a specific detail, the query must be re-opened with the parameters set to values obtained from a corresponding master data controller record.  This can be performed automatically for BDE and ADO queries if the parameter names are the same as the detail key field names (DataController.DetailKeyFieldNames).  Note that you must add the cxADOAdapters unit to the uses section of your form if you want this to work for ADO queries.

The OnDetailFirst event allows you to set query parameters and re-open the query manually, but this is not a common practice.  Refer to its description for more information.

Important Note:	When in Grid mode, detail data controllers cannot be linked to a parameterized query dataset, i.e. in this mode, the master data controller’s DetailInSQLMode property should be set to False.

The default value of the DetailInSQLMode property is False.


TcxDBDataModeController.GridMode

TcxDBDataModeController          See Also

Determines whether the data controller works in Grid mode.

property GridMode: Boolean;

Description

The GridMode property determines whether the data controller works in Grid mode.  When in Grid mode, the data controller loads a fixed number of dataset records according to the GridModeBufferCount property.

In Grid mode, the data controller’s performance is better, but features such as automatic sorting, filtering and summary calculations are disabled.  You have to write appropriate event handlers (OnSortingChanged, Filter.OnBeforeChange, OnAfterSummary) to perform these actions.  To enable data filtering in grid mode, you can use the AutoDataSetFilter property as well as the OnBeforeChange event.  Setting the AutoDataSetFilter property to True automatically applies the changed filter criteria to the dataset’s Filter property.  See the AutoDataSetFilter and OnBeforeChange descriptions for more details.

Grid mode is automatically switched off when grouping is applied to a grid view. In this case (and also if the GridMode property value is False), the data controller switches to default mode.  In this mode, all dataset records are loaded to the data controller and automatic sorting, filtering and summary calculations are available.  The SmartRefresh property is also in effect when the data controller is in default mode.

Important Note:	If you enable Grid mode for a master/detail relationship, both views must be in Grid mode, else data will not be displayed correctly.  When in Grid mode, detail data controllers cannot be linked to a parameterized query dataset (TQuery, for instance), i.e. in Grid mode, the master data controller’s DetailInSQLMode property should be set to False.

The default value of the GridMode property is False.


TcxDBDataModeController.GridModeBufferCount

TcxDBDataModeController          See Also

Specifies the number of dataset records loaded from a dataset in a single operation.

property GridModeBufferCount: Integer;

Description

Use the GridModeBufferCount property to specify the number of dataset records loaded from a dataset to the data controller at once.  This option is active only when the data controller is in Grid mode.

By default, GridModeBufferCount is set to 0.  This indicates that controls incorporating a data controller need to calculate the size of the buffer automatically based on the screen resolution and record height.  ExpressQuantumGrid, for instance, calculates the size of the buffer by determining the number of records that can be displayed within the screen window.

If GridModeBufferCount is set to a value greater than 0, the buffer size is determined by this value.

The default value of the GridModeBufferCount property is 0.


TcxDBDataModeController.SmartRefresh

TcxDBDataModeController          See Also

Determines whether to reload all dataset records or only the changed ones.

property SmartRefresh: Boolean;

Description

Use the SmartRefresh property to determine the manner in which data controller records are updated.  This option is active only if the following conditions are met:

•	Data controller is in default mode (the DataController.DataModeController.GridMode property is set to False).

•	The key field for the dataset is specified.

•	Data modifications are done by the ExpressQuantumGrid.

If the SmartRefresh property is set to True, the data controller reloads only the changed records.  Otherwise, the data controller reloads all dataset records.

Note:	If a data controller is in Smart Refresh mode and dataset records are managed via the data controller, the records are automatically updated.  If dataset records are modified via the dataset’s methods or by external controls, you need to manually call the UpdateItems method to reload all records with new data.

The default value of the SmartRefresh property is False.


TcxDBDataModeController.SyncMode

TcxDBDataModeController

Specifies whether synchronization between the grid control and the corresponding TDataSet is enabled.

property SyncMode: Boolean;

Description

If SyncMode is set to True, the current record in a grid control is always synchronized with the current record in the corresponding TDataSet.  Whenever you move focus to another record in the grid control, the current TDataSet record also changes to point to the same data, and vice versa.  When the current TDataSet record changes, focus also moves to the corresponding record in the grid control.

The default value of the SyncMode property is True.


TcxDBDataModeController.Assign

TcxDBDataModeController

Copies the properties of a specific data mode controller to the current object.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method to copy properties of the data mode controller specified by the Source parameter to the current object.


TcxDBDataModeController.Create

TcxDBDataModeController

Creates an instance of the TcxDBDataModeController class for a specific data mode controller.

constructor Create(ADataController: TcxDBDataController);

Description

The constructor creates an instance of the TcxDBDataModeController class for a specific data controller.  ADataController is used to initialize the DataController property.


TcxDBDataModeController.OnDetailFirst

TcxDBDataModeController           See also         Example

Occurs before reopening the parameterized query linked to a detail data controller.

type

  TcxDBDataModeControllerDetailFirstEvent = procedure(Sender: TcxDBDataModeController; ADataSet: TDataSet; const AMasterDetailKeyFieldNames: string; const AMasterDetailKeyValues: Variant; var AReopened: Boolean) of object;

property OnDetailFirst: TcxDBDataModeControllerDetailFirstEvent;

Description

This event is only used in rare cases.  The TcxDBProviderDetailFilterAdapter and TcxADOProviderDetailFilterAdapter classes can perform default actions for setting SQL SELECT parameters and reopening BDE and ADO queries respectively.  If you use an ADO query, you just need to manually add the cxADOAdapters unit to the uses section of your form (for BDE queries this is not required).

Use the OnDetailFirst event to set the parameters of the parameterized query linked to a detail data controller and reopen it if needed.  This event is generated when you expand the level displaying data from the current detail data controller and when moving focus from one detail data controller to another.  The AReopened parameter determines whether the query needs to be re-opened.  Set it to True if the query was reopened.  If no changes were made, you need to set AReopened to False.

Sender specifies the TcxDBDataModeController object belonging to the detail data controller which displays the query data.

ADataSet specifies the parameterized query dataset.

AMasterDetailKeyFieldNames specifies the DetailKeyFieldNames property value of a detail data controller.

AMasterDetailKeyValues specifies a single value or an array of values for detail key fields identified by the AMasterDetailKeyFieldNames parameter.

The following image shows a fragment of the grid control with two details at level 1:

If you expand Detail 1, the OnDetailFirst event is generated with AMasterDetailKeyFieldNames set to ‘CustNo’ and AMasterDetailKeyValues set to 3042.  If the parameterized query defined by ADataSet already presents data with parameter 3042, the query should not be reopened.  In this case, you just have to call the First method for the ADataSet argument.  If the query’s parameter is other than 3042, you should set a new parameter and reopen the query (set Active to True).

If you expand Detail 2, the AMasterDetailKeyFieldNames and AMasterDetailKeyValues parameters of the OnDetailFirst event are ‘CustNo’ and 3051 respectively.

Refer to the example linked to this topic.


TcxDBDataModeController.OnDetailIsCurrentQuery

TcxDBDataModeController           See also          Example

Occurs when navigating through records of the detail data controller linked to a parameterized dataset.

type

  TcxDBDataModeControllerDetailIsCurrentQueryEvent = function(Sender: TcxDBDataModeController; ADataSet: TDataSet; const AMasterDetailKeyFieldNames: string; const AMasterDetailKeyValues: Variant) : Boolean of object;

property OnDetailIsCurrentQuery: TcxDBDataModeControllerDetailIsCurrentQueryEvent;

Description

This event is only used in rare cases.  The TcxDBProviderDetailFilterAdapter and TcxADOProviderDetailFilterAdapter classes implement functions using the OnDetailIsCurrentQuery event for BDE and ADO queries respectively.  If you use an ADO query, you just need to manually add the cxADOAdapters unit to the uses section of your form (for BDE queries this is not required).

The OnDetailIsCurrentQuery event is generated when navigating through records of the detail data controller linked to a parameterized dataset or when shifting from one detail controller to another at the same level.

The following image shows a fragment of the grid control with two details at level 1:

The OnDetailIsCurrentQuery event is generated when moving focus from one record to another within Detail 1 or Detail 2.  If you navigate through records within one detail, you do not need to reopen the underlying query since it already selected the required data.  But if you move focus from Detail 1 to Detail 2, you will need to reopen the query so that it selects new data.

If the query should be reopened, the OnDetailIsCurrentQuery event handler must return False, which indicates that a user has moved focus to another detail.  Otherwise, True must be returned.  The query is re-opened internally either by the ReopenSQL method of the TcxDBProviderDetailFilterAdapter or TcxADOProviderDetailFilterAdapter class or by the OnDetailFirst event handler.

Sender specifies the TcxDBDataModeController object, which belongs to the detail data controller displaying query data.

ADataSet specifies the parameterized query dataset.

AMasterDetailKeyFieldNames specifies the DetailKeyFieldNames property value of a detail data controller.

AMasterDetailKeyValues specifies a single value or an array of values for detail key fields identified by the AMasterDetailKeyFieldNames parameter.

The CustNo field in the image above establishes a master-detail relationship.  In this instance, AMasterDetailKeyFieldNames is ‘CustNo’ for both details.  When you navigate through records within Detail 1, the AMasterDetailKeyValues parameter specifies 3042.  When moving focus to Detail 2 AMasterDetailKeyValues specifies 3051.

See the example of the OnDetailIsCurrentQuery event handler at the top of this topic.


TcxDBDataSummaryItem
TcxDBDataSummaryItem Object

Hierarchy          Properties          Methods          Events          See Also

Represents a single summary to calculate against a specific field.

Unit

cxDBData

TcxDBDataSummaryItem = class(TcxDataSummaryItem);

Description

The TcxDBDataSummaryItem class extends the functionality provided by the TcxDataSummaryItem class.  It enables operations on the TDataSet object.  TcxDBDataSummaryItem allows you to specify a dataset field from the corresponding data controller against which a summary is calculated.  The summary result will be positioned based on the item specified by the ItemLink property.  If you do not assign a field to the FieldName property, the summary will be evaluated against values of the item specified by the ItemLink property.

TcxDBDataSummaryItem is an element of the collection represented by the TcxDataSummaryItems class.  TcxDataSummaryItems is the base class for TcxDataFooterSummaryItems and TcxDataGroupSummaryItems which implement footer summaries and group summaries respectively.

To add a summary, use the TcxCustomDataController.Summary property.


TcxDBDataSummaryItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxCustomDataSummaryItem

     |

TcxDataSummaryItem

     |


Properties for TcxDBDataSummaryItem
TcxDBDataSummaryItem Properties

TcxDBDataSummaryItem          Legend

In TcxDBDataSummaryItem

FieldName

Derived from TcxDataSummaryItem

DataController

Format

Kind

Position

Sorted

SummaryItems

Derived from TcxCustomDataSummaryItem

DataController

ItemLink


Methods for TcxDBDataSummaryItem
TcxDBDataSummaryItem Methods

TcxDBDataSummaryItem          Legend

Derived from TcxDataSummaryItem

Assign

FormatValue

Derived from TcxCustomDataSummaryItem

Assign

BeginUpdate

EndUpdate


Events for TcxDBDataSummaryItem
TcxDBDataSummaryItem Events

TcxDBDataSummaryItem          Legend

Derived from TcxDataSummaryItem

OnGetText


TcxDBDataSummaryItem.FieldName

TcxDBDataSummaryItem           See Also

Defines the field name from which values are retrieved to calculate a summary.

property FieldName: string;

Description

The FieldName property allows you to calculate a summary by one item and position its result based on another item.  Use the FieldName property to assign the field name in the corresponding dataset against which the summary is calculated.  If you do not specify the field name, the summary is calculated against values of the item referenced by the ItemLink property.  The summary result is always placed at the position corresponding to the item referenced by the ItemLink property.


TcxDBDataFilterCriteria
TcxDBDataFilterCriteria Object

Hierarchy          Properties          Methods          Events

Represents a filter criteria object which works with TDataSet.

Unit

cxDBData

TcxDBDataFilterCriteria = class(TcxDataFilterCriteria);

Description

TcxDBDataFilterCriteria extends the functionality of the TcxDataFilterCriteria class by enabling operations on the TDataSet object.


TcxDBDataFilterCriteria Hierarchy
Hierarchy

TPersistent

     |

TcxFilterCriteria

     |

TcxDataFilterCriteria

     |


Properties for TcxDBDataFilterCriteria
TcxDBDataFilterCriteria Properties

TcxDBDataFilterCriteria          Legend

In TcxDBDataFilterCriteria

AutoDataSetFilter

IgnoreOrigin

Derived from TcxDataFilterCriteria

Active

DataController

Derived from TcxFilterCriteria

DateTimeFormat

FilterCaption

FilterText

MaxValueListCount

Options

PercentWildcard

Root

StoreItemLinkNames

SupportedLike

TranslateBetween

TranslateIn

TranslateLike

UnderscoreWildcard


Methods for TcxDBDataFilterCriteria
TcxDBDataFilterCriteria Methods

TcxDBDataFilterCriteria          Legend

Derived from TcxDataFilterCriteria

Create

Destroy

FindItemByItemLink

IsFiltering

RemoveItemByField

Derived from TcxFilterCriteria

AddItem

Assign

BeginUpdate

CancelUpdate

Clear

Create

Destroy

EndUpdate

LoadFromStream

RemoveItemByItemLink

RestoreDefaults

SaveToStream


Events for TcxDBDataFilterCriteria
TcxDBDataFilterCriteria Events

TcxDBDataFilterCriteria          Legend

In TcxDBDataFilterCriteria

OnBeforeChange

OnFormatFilterTextValue

Derived from TcxDataFilterCriteria

OnGetValueList

Derived from TcxFilterCriteria

OnChanged


TcxDBDataFilterCriteria.AutoDataSetFilter

TcxDBDataFilterCriteria           See Also

Specifies whether the current filter is automatically set to the grid's dataset whenever it is changed.

property AutoDataSetFilter: Boolean;

Description

If the AutoDataSetFilter property is set to True, the FilterText property is automatically assigned to the TDataSet.Filter property when filter criteria are changed.  In this instance, the dataset itself filters records.

If this property is set to False, the Filter property is not changed by the grid control.  When filter criteria are changed, the dataset provides data as it did before.  In this case the grid control filters data retrieved from the dataset: it displays records that meet the filter criteria.

The OnBeforeChange event provides more flexibility when applying filter conditions to the underlying dataset.

The default value of the AutoDataSetFilter property is False.


TcxDBDataFilterCriteria.IgnoreOrigin

TcxDBDataFilterCriteria          See Also

Specifies whether to use the TField.FiledName or the TField.Origin property to represent a field in the FilterText property.

property IgnoreOrigin: Boolean;

Description

The IgnoreOrigin property allows you to override the choice of fieldnames used in the FilterText.  IgnoreOrigin specifies whether to use the FiledName or Origin properties of dataset fields when creating the FilterText.

By default, IgnoreOrigin is True and TField.FiledName property values represent fields in the FilterText.  Usually, you can leave it set to True unless there are ambiguous field names in an underlying dataset.  This problem can occur if the dataset represents a query which joins several tables with the same field name, but only if you specify FilterText as a part of the query’s SQL statement via the OnBeforeChange event.

To correctly identify fields in this case, you can assign valid full field names (Products.ID, for instance) to the Origin properties of dataset fields and then set IgnoreOrigin to False.  Now FilterText will be created using the values of the Origin properties instead of field names.

The TField.Origin property specifies the name of the field in its original database table.  It is assigned at design time by the Fields editor when the dataset is a TQuery object.  The Origin property can be changed freely depending on your needs.

For ADO queries, the IgnoreOrigin property usually should be set to True.  ADO queries automatically assign unambiguous filed names when joining tables with same field names.  BDE queries do not process this situation correctly and so you should consider setting IgnoreOrigin to False.

The default value of the IgnoreOrigin property is True.

The following example describes a situation when IgnoreOrigin should be set to False.

Consider the TQuery component which selects data from the Customer and Products tables shipped with ExpressQuantumGrid4 demos:

SELECT * FROM Customer C, Products P

WHERE C.ProductID = P.ID

The Customer table contains the ID and ProductID fields.  The Products table contains the ID field and this corresponds to the ProductID field in the Customer table.

The specified query selects customers from the Customer table and, for every customer, it adds corresponding fields from the Products table to provide information on the products bought.

The following screenshot shows a portion of data loaded by the query (this does not present all fields from the query):

Note that both the Customer and Products tables contain a field with the same name (ID).  In the query result, the ID field of the second table is automatically renamed to ID_1.

You are not able to apply a filter condition using this field name in the SQL statement.  For instance, the following query will generate the error ("Undefined field name ID_1"):

SELECT * FROM Customer C, Products P

WHERE C.ProductID = P.ID

AND ID_1 = 3

By default, IgnoreOrigin is True and this makes the data controller use the TField.FieldName property value to construct FilterText.

Suppose you apply a filter condition to the ID_1 field via the data controller.  The field will be represented by the ID_1 string in FilterText (because IgnoreOrigin is set to True by default).  As shown above, this FilterText cannot be specified as a part of the WHERE clause in a SQL statement.

The filter condition for the SQL statement should be constructed using the full name of the ID_1 field:

SELECT * FROM Customer C, Products P

WHERE C.ProductID = P.ID

AND P.ID = 3

P.ID is a full name for the ID_1 field.  To make the data controller automatically use the correct name (P.ID instead of ID_1) for the FilterText, you need to:

1.	Create persistent fields for fields in the query via the Fields Editor.

For this purpose, double-click the query icon or select the Fields Editor option from the component’s popup menu.  This activates the Fields Editor:

Right click the editor’s client region and select the Add all fields option:

This loads all fields from the query and creates a persistent TField object for each of them.  Now it is possible to customize the field properties.

2.	Change the Origin property of the ID_1 field to "P.ID".  To do this, select the ID_1 field and change its property value in the Object Inspector:

3.	Set the data controller’s IgnoreOrigin property to False.  Now the data controller will automatically use the value of the Origin property instead of FieldName when constructing FilterText.

Note that the data controller will now use the Origin property for all fields when constructing FilterText.  So you need to assign correct names to the Origin property of all the other fields as for the ID_1 field.

After this, the data controller will generate valid FilterText which can be used in a SQL statement.  The following code shows how to change the WHERE clause of a query via the OnBeforeChange event.  It is assumed that the SQL property of the query consists of three lines (the third line is empty) and the SQL command is specified as follows:

SELECT * FROM Customer C, Products P

WHERE C.ProductID = P.ID

In an OnBeforeChange event handler, FilterText is added as a third line to the SQL statement and this combines the existing condition in the query (C.ProductID = P.ID) with the condition set by the user.  For instance, when a user applies the condition "= 3" to the ID_1 field, the query’s SQL property will identify the following command:

SELECT * FROM Customer C, Products P

WHERE C.ProductID = P.ID

AND (P.ID = 3)

//Delphi

procedure TForm1.tvCustomerDataControllerFilterBeforeChange(

  Sender: TcxDBDataFilterCriteria; ADataSet: TDataSet;

  const AFilterText: String);

begin

  with Query1 do

  begin

    DisableControls;

    try

      Active := False;

      if AFilterText <> '' then

        //add condition to the query

        SQL[2] := 'AND ' + AFilterText

      else

        SQL[2] := '';

      Active := True;

    finally

      EnableControls;

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::tvCustomerDataControllerFilterBeforeChange(

      TcxDBDataFilterCriteria *Sender, TDataSet *ADataSet,

      const AnsiString AFilterText)

{

  Query1->DisableControls();

  try {

    Query1->Active = false;

    if (AFilterText != "") {

      //add condition to the query

      Query1->SQL->Strings[2] = "AND " + AFilterText;

    } else {

      Query1->SQL->Strings[2] = "";

    }

    Query1->Active = true;

  } __finally {

    Query1->EnableControls();

  }

}


TcxDBDataFilterCriteria.OnBeforeChange

TcxDBDataFilterCriteria           See Also          Example

Occurs after changing filter criteria, but before updating data in the corresponding data controller.

type

  TcxDBDataFilterBeforeChangeEvent = procedure(
    Sender: TcxDBDataFilterCriteria; ADataSet: TDataSet;
    const AFilterText: string) of object;

property OnBeforeChange: TcxDBDataFilterBeforeChangeEvent;

Description

In default loading mode (GridMode is disabled), a data controller loads all records into memory from the linked dataset.  Whenever filter criteria are changed, the data controller filters records by itself.

If you handle the OnBeforeChange event, the data controller does not filter records.  It is assumed that your OnBeforeChange event handler applies new filter conditions to the underlying dataset.  The Sender parameter specifies the FilterCriteria object whose filter conditions have been changed.  The ADataSet parameter represents the TDataSet object to which filter criteria should be applied.  New filter conditions are provided by the AFilterText parameter.

There is another way to delegate filter operations to the underlying dataset.  Set the AutoDataSetFilter property to True to make the dataset, rather than the data controller, filter records.  In this case, the FilterText property value is assigned to the dataset’s Filter every time filter criteria are changed.

Compared with automatic dataset filtering, the OnBeforeChange event is more flexible as it allows you to completely control the filter text and the manner in which it is applied to the dataset.

Note that AutoDataSetFilter and OnBeforeChange work independently.  When filter criteria are changed, the OnBeforeChange event is fired first.  Then, if the AutoDataSetFilter property is set to True, new filter conditions are automatically applied to the dataset as described above, thus discarding your dataset filter set in the OnBeforeChange event handler.  So, if you want to filter data yourself via the OnBeforeChange event, you usually have to set AutoDataSetFilter to False.

In Grid Mode, filtering by the data controller is disabled.  You must filter data either by enabling the automatic filtering via the AutoDataSetFilter property or by handling the OnBeforeChange event.


TcxDBDataFilterCriteria.OnFormatFilterTextValue

TcxDBDataFilterCriteria

Enables you to format the values within the filter string that is applied to a dataset.

type

  TcxDBDataFilterFormatFilterTextValueEvent = procedure(Sender: TcxDBDataFilterCriteria; const AValue: Variant; var ADisplayValue: string) of object;

property OnFormatFilterTextValue: TcxDBDataFilterFormatFilterTextValueEvent;

Description

If the AutoDataSetFilter property value is True, applying the filter criteria to a control results in filtering the underlying dataset.  This means that the text stored in the FilterText property is assigned to the dataset’s Filter property.  In some cases, the format of values in the constructed string may not match the format required by the dataset.  This case is not usual and may appear only on particular dataset types and with particular value types.  To resolve this, handle the OnFormatFilterTextValue event and provide manual value formatting so that it matches the format required by the dataset.

The OnFormatFilterTextValue event is raised for each value within the constructed filter string.  The filter criteria that generated this filter string can be obtained via the Sender parameter.  The value to be formatted is passed as the AValue parameter.  The desired formatted string should be assigned to the ADisplayValue parameter.  Initially, this parameter contains the text formatted using the default mechanism.


cxFilter Unit Overview
cxFilter Unit

Classes

TcxCustomFilterCriteriaItem

TcxFilterCriteria

TcxFilterCriteriaItem

TcxFilterCriteriaItemList

TcxFilterValueList

Other Types

PcxFilterValueItem

TcxFilterBoolOperatorKind

TcxFilterCriteriaOption

TcxFilterCriteriaOptions

TcxFilterOperatorKind

TcxFilterValueItem

TcxFilterValueItemKind

Global Variables

cxFilterIncludeTodayInLastNextDaysList


TcxCustomFilterCriteriaItem
TcxCustomFilterCriteriaItem Object

Hierarchy          See Also

Represents the base functionality for the TcxFilterCriteriaItem and TcxFilterCriteriaItemList classes.

Unit

cxFilter

TcxCustomFilterCriteriaItem = class(TObject);

Description

The TcxCustomFilterCriteriaItem class provides functionality common to classes implementing simple and aggregate filter conditions.  A simple filter condition is realized by the TcxFilterCriteriaItem class.  The TcxFilterCriteriaItemList class implements an aggregate filter condition.


TcxCustomFilterCriteriaItem Hierarchy
Hierarchy

TObject

     |


TcxFilterCriteria
TcxFilterCriteria Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for grid filtering facilities.

Unit

cxFilter

TcxFilterCriteria = class(TPersistent);

Description

The TcxFilterCriteria class is an abstract class which provides the base filtering facilities for a grid control.  Filter criteria for a grid control can consist of several filter conditions combined by logical operators (and, or).  In turn, a filter condition can represent either a simple comparison operation or an aggregate condition consisting of other simple (or aggregate) conditions combined by logical operators.  Thus, you can build complex filter criteria to filter data.  The following condition illustrates a complex filter:

(CustNo > 12) AND (LastOrder = ’12/31/2000’ OR LastOrder = ‘12/31/2001’)

There are three filter items:

1.	CustNo > 12

2.	LastOrder = ’12/31/2000’

3.	LastOrder = ‘12/31/2001’

To represent such a condition, two lists are used.  The first list stores simple conditions 2 and 3.  These conditions are combined by the OR operator.  The second list is the root one.  It points to the simple condition 1 and the condition defined by the first list.  Conditions in the second list are combined by the AND operator.

Use the Root property to access the root list of filter conditions for the TcxFilterCriteria object.  A list of filter conditions is represented by the TcxFilterCriteriaItemList class.  A simple condition (filter item) is implemented by the TcxFilterCriteriaItem object.

The TcxDataFilterCriteria class is an immediate descendant of the TcxFilterCriteria class.  It introduces new properties, methods and events which extend the filtering capabilities.


TcxFilterCriteria Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxFilterCriteria
TcxFilterCriteria Properties

TcxFilterCriteria          Legend

In TcxFilterCriteria

DateTimeFormat

FilterCaption

FilterText

MaxValueListCount

Options

PercentWildcard

Root

StoreItemLinkNames

SupportedLike

TranslateBetween

TranslateIn

TranslateLike

UnderscoreWildcard


Methods for TcxFilterCriteria
TcxFilterCriteria Methods

TcxFilterCriteria          Legend

In TcxFilterCriteria

AddItem

Assign

BeginUpdate

CancelUpdate

Clear

Create

Destroy

EndUpdate

LoadFromStream

RemoveItemByItemLink

RestoreDefaults

SaveToStream


Events for TcxFilterCriteria
TcxFilterCriteria Events

TcxFilterCriteria          Legend

In TcxFilterCriteria

OnChanged


TcxFilterCriteria.FilterCaption

TcxFilterCriteria           See Also

Determines the text representation of the filter criteria when displayed in the filter status bar.

property FilterCaption: string;

Description

The FilterCaption property is used to display the current (applied) filter conditions within the filter status bar.

FilterCaption	(State = CA) AND (PurchaseDate = 01-Mar-1976)

FilterText	(State = 'CA') AND (PurchaseDate = '01-Mar-1976')

You can activate the fcoShowOperatorDescription flag in the Options property to replace operator symbols with their text representations.  In this instance, the FilterCaption property will specify the following string:

(State equals CA) AND (PurchaseDate equals 01-Mar-1976)

ReadOnly Property


TcxFilterCriteria.FilterText

TcxFilterCriteria           See Also

Specifies filter criteria for a grid control.

property FilterText: string;

Description

When filtering is applied to a grid, only nodes that meet filter conditions are displayed.  The FilterText property contains a string that describes filter conditions.  Unlike the FilterCaption property, the FilterText property can be applied to a dataset or an SQL statement.

To add a filter condition to the filter criteria, use the Root property.

FilterCaption 	(State = CA) AND (PurchaseDate = 01-Mar-1976)

FilterText	(State = 'CA') AND (PurchaseDate = '01-Mar-1976')


TcxFilterCriteria.MaxValueListCount

TcxFilterCriteria           See Also

Limits the number of rows in the popup list, which contains values to set a filter condition for a specific item.

property MaxValueListCount: Integer;

Description

A user can press the down-arrow button to the right of the grid column caption to activate the popup list with values for filter criteria.  If a user selects an element from this list, a filter condition is constructed and applied to the corresponding item.

The MaxValueListCount property limits the number of rows to load in order to populate this list.  It is a good idea to specify MaxValueListCount for large databases.  By default, MaxValueListCount is 0 meaning that all records from a data table are looked through to fetch unique values.  Use MaxValueListCount to ensure acceptable time for populating this list.

The popup list is encapsulated by the TcxFilterValueList class.  The derived TcxDataFilterValueList class provides the Load method, which populates the list with values from the corresponding item.  Before the popup list is displayed, the TcxDataFilterCriteria.OnGetValueList event is generated which enables you to customize the list as required.

The default value of the MaxValueListCount property is 0.


TcxFilterCriteria.Options

TcxFilterCriteria           See Also

Specifies options controlling filtering and the display of filter text.

property Options: TcxFilterCriteriaOptions;

Description

The TcxFilterCriteriaOption enumerator describes the different filtration options.

The default value of the Options property is [].


TcxFilterCriteria.PercentWildcard

TcxFilterCriteria           See Also             Example

Specifies the character used to represent any number of symbols in the filter condition of the foLike type.

property PercentWildcard: Char;

Description

When comparing string values, it is possible to use this symbol to represent any number of characters in the filter condition of the foLike type.  You can assign any character to be used as a wildcard.

The default value of the PercentWildcard property is '%'.


TcxFilterCriteria.Root

TcxFilterCriteria           See Also           Example

Specifies the list of filter conditions constituting the filter criteria.

property Root: TcxFilterCriteriaItemList;

Description

The Root property specifies the list of filter conditions (simple or aggregate) combined by a logical operator.

ReadOnly Property


TcxFilterCriteria.StoreItemLinkNames

TcxFilterCriteria          See Also

Specifies whether item names are used to identify items in the filter criteria stored in a memory stream.

property StoreItemLinkNames: Boolean;

Description

By default, a filter condition is stored in a memory stream along with the unique identifier and name assigned to the item, which this filter condition is based on.  This prohibits you from applying filter criteria to data provided by another data controller (via the destination data controller’s Assign method).

To override the default behavior, do one of the following:

•	pass True as the Assign method’s AIgnoreItemNames parameter;

•	before calling this method, set the destination data controller’s Filter.StoreItemLinkNames property to False.


TcxFilterCriteria.SupportedLike

TcxFilterCriteria          See Also

Specifies whether the Like and Not Like operators are available within the filter building dialog.

property SupportedLike: Boolean;

Description

Use the SupportedLike property to determine whether the Like and Not Like operators are available to an end-user within the filter building dialog.

Set this property to False if the dataset does not support these operators, but the cxDBDataFilterCriteria.AutoDataSetFilter property is set to True.

The default value of the SupportedLike property is True.


TcxFilterCriteria.TranslateBetween

TcxFilterCriteria

Specifies whether the Between and Not Between operators in a filter condition are replaced with comparison and logical operators.

property TranslateBetween: Boolean;

Description

Use the TranslateBetween property to determine whether the Between and Not Between operators are replaced with their comparison and logical equivalents.

An example of the FilterText property value depending on the TranslateBetween settings is demonstrated below:

TranslateBetween is False	TranslateBetween is True
(RUNTIME BETWEEN 140 AND 160)	((140<=RUNTIME) AND (RUNTIME<=160))

The default value of the TranslateBetween property is False.


TcxFilterCriteria.TranslateIn

TcxFilterCriteria

Specifies whether the In and Not In operators in a filter condition are replaced with comparison and logical operators.

property TranslateIn: Boolean;

Description

Use the TranslateIn property to determine whether the In and Not In operators are replaced with their comparison and logical equivalents.

An example of the FilterText property value depending on the TranslateIn settings is demonstrated below:

TranslateIn is False	TranslateIn is True
(RUNTIME IN (140,160))	((RUNTIME=140) OR (RUNTIME=160))

The default value of the TranslateIn property is False.


TcxFilterCriteria.TranslateLike

TcxFilterCriteria          See Also

Specifies whether the Not Like operator in a filter condition is replaced with the inverted logical expression of the Like operator.

property TranslateLike: Boolean;

Description

Use the TranslateLike property to determine whether the Not Like operator is replaced with the inverted logical expression of the Like operator.

An example of the FilterText property’s value which depends on the TranslateLike setting is demonstrated below.

TranslateLike is False	TranslateLike is True
(NAME NOT LIKE ‘US’)	(NOT (NAME LIKE ‘US’))

The default value of the TranslateLike property is False.


TcxFilterCriteria.UnderscoreWildcard

TcxFilterCriteria           See Also            Example

Specifies the symbol used to represent any single character in the filter condition of the foLike type.

property UnderscoreWildcard: Char;

Description

When comparing string values it is possible to use this symbol to represent any single character in the filter condition of the foLike type.

The default value of the UnderscoreWildcard property is '_'.


TcxFilterCriteria.AddItem

TcxDataFilterCriteria         See Also

Adds a new simple filter condition to the specified filter condition list.

function AddItem(AParent: TcxFilterCriteriaItemList; AItemLink: TObject; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; const ADisplayValue: string): TcxFilterCriteriaItem; virtual;

Description

The AddItem method adds a new simple filter condition to the list specified by the AParent parameter.  If AParent is NIL, a new filter condition is inserted in the root list, which is provided by the Root property.  AItemLink defines the item for which the condition is applied.

The AddItem method returns an object of the TcxFilterCriteriaItem class representing a simple condition.  The AOperatorkind, AValue, ADisplayValue parameters are used to initialize the OperatorKind, Value, and DisplayValue properties of the object created respectively.


TcxFilterCriteria.Assign

TcxFilterCriteria          See Also

Copies the Source filter condition to the current TcxFilterCriteria object.

{$IFNDEF CLR}

procedure Assign(Source: TPersistent; AIgnoreItemNames: Boolean = False); reintroduce; virtual;

{$ELSE}

procedure Assign(Source: TPersistent); override;

{$ENDIF}

Description

By default, a filter condition is stored in a memory stream along with the unique identifier and name assigned to the item, which this filter condition is based on.  This prohibits you from applying filter criteria to data provided by another data controller (via the destination data controller’s Assign method).

To override the default behavior, do one of the following:

•	pass True as the AIgnoreItemNames parameter;

•	before calling the Assign method, set the destination data controller’s Filter.StoreItemLinkNames property to False.


TcxFilterCriteria.BeginUpdate

TcxFilterCriteria           See Also             Example

Prevents the TcxFilterCriteria object from updating until the CancelUpdate or EndUpdate method is called.

procedure BeginUpdate;

Description

Call the BeginUpdate method before you add a series of filter conditions.  After all changes are made, you should call the EndUpdate method.  If no changes have been made, you can call the CancelUpdate method.


TcxFilterCriteria.CancelUpdate

TcxFilterCriteria           See Also

Enables updating the TcxFilterCriteria object after the BeginUpdate method is called.

procedure CancelUpdate;

Description

After the BeginUpdate method is called your grid control does not receive notifications as filter criteria change.  When changes to filter criteria are complete, you should call the EndUpdate method.  If no changes are made, you can call the CancelUpdate method.  Unlike the EndUpdate method, the CancelUpdate method does not send notification to the grid control.


TcxFilterCriteria.Clear

TcxFilterCriteria

Removes filter conditions of the TcxFilterCriteria object.

procedure Clear;

Description

The Clear method removes the filter conditions provided by the Root property and sets the BoolOperatorKind property of the Root object to its default value.  After the Clear method is called, the TcxFilterCriteria object specifies that no filter conditions are in effect.


TcxFilterCriteria.Create

TcxFilterCriteria           See Also

Creates a new TcxFilterCriteria object and initializes its properties to default values.

constructor Create;

Description

The constructor creates an empty list of filter conditions specified by the Root property and initializes the TcxFilterCriteria object’s properties to their default values.  Use the Root property to add filter conditions.


TcxFilterCriteria.Destroy

TcxFilterCriteria           See Also

Destroys an instance of the TcxFilterCriteria class.

destructor Destroy; override;

Description

The destructor destroys the list of filter conditions specified by the Root property and frees all resources allocated by the TcxFilterCriteria object.  Do not call Destroy directly; call Free instead.


TcxFilterCriteria.EndUpdate

TcxFilterCriteria           See Also            Example

Enables updating the TcxFilterCriteria object after the BeginUpdate method has been called.

procedure EndUpdate;

Description

The EndUpdate method should be called after all changes have been made to the filter criteria.  It sends notification to the grid control about the filter changes.  If no changes have been made after calling the BeginUpdate method, use CancelUpdate instead.


TcxFilterCriteria.LoadFromStream

TcxFilterCriteria

Restores the filter settings from a stream.

procedure LoadFromStream(AStream: TStream); virtual;

Description

Use the LoadFromStream method to restore the filter settings from a stream.  This method restores the filter settings even if the dataset is not filtered (no FilterCriteria is defined) when a restore is performed.

The restored settings include:

•	the FilterText property value,

•	the index of the filtered item,

•	the DataController.Filter properties, whose values differ from the default.


TcxFilterCriteria.RemoveItemByItemLink

TcxFilterCriteria           See Also

Removes all filter conditions for a specific grid item.

procedure RemoveItemByItemLink(AItemLink: TObject);

Description

The grid item is identified by a link passed as the AItemLink parameter.

During filter condition removal, aggregate conditions containing a single condition are automatically converted to simple conditions.


TcxFilterCriteria.RestoreDefaults

TcxFilterCriteria           See Also

Restores options and wildcards to their default values.

procedure RestoreDefaults; virtual;

Description

Call the RestoreDefaults method to restore the Options, PercentWildcard, and UnderscoreWildcard properties to their default values.


TcxFilterCriteria.SaveToStream

TcxFilterCriteria

Stores the filter settings in a stream.

procedure SaveToStream(AStream: TStream); virtual;

Description

Use the SaveToStream method to store the filter settings to a stream.  This method saves:

•	the FilterText property value,

•	the name of the filtered item,

•	the DataController.Filter properties, whose values differ from the default.


TcxFilterCriteria.OnChanged

TcxFilterCriteria           See Also

This event fires after filtration criteria have changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnChanged: TNotifyEvent;

Description

TcxFilterCriteria class descendants generate this event after applying new filter conditions to data provided by a data controller.  The event is also fired when you activate or disable the filtering feature using the TcxDataFilterCriteria.Active property.

The Sender parameter represents the FilterCriteria object which generates the event.

Explore the example where TcxGrid and TcxFilterControl controls are placed on a form.  The grid control displays data within the tvCustomers view.  The filter control is linked to this view via the TcxFilterControl.LinkComponent property and this enables displaying the filter criteria applied to the view within the filter control.

However, the filter control is not automatically updated when you change the filter for the view, for instance, when you select the value from the filter dropdown list.  You need to manually update the filter criteria provided in the filter control using the OnChanged event.  The following code shows the OnChanged event to invoke the UpdateFilter method of the filter control.

//Delphi

procedure TForm1.tvCustomersDataControllerFilterChanged(Sender: TObject);

begin

  cxFilterControl1.UpdateFilter;

end;

//C++ Builder

void __fastcall TForm1::tvCustomersDataControllerFilterChanged(TObject *Sender) {

  cxFilterControl1->UpdateFilter();

}


TcxFilterCriteria.DateTimeFormat

TcxFilterCriteria          See Also

Specifies the pattern for formatting date/time values.

property DateTimeFormat: string;

Description

The DateTimeFormat property identifies a formatting string used to convert date/time values to text representation when constructing FilterText.  The FilterText property represents a string built from the current filter criteria.  This string can be applied to a dataset or an SQL statement if needed.

The TcxDBDataFilterCriteria class provides the AutoDataSetFilter property which enables you to automatically apply FilterText to a connected dataset (for query datasets, the "WHERE " + FilterText clause is added to the SQL statement).

Some datasets require date/time values be formatted in a specific manner when a filter is applied.  For this purpose, use the DateTimeFormat property.  If DateTimeFormat identifies an empty string, date/time values are formatted by the VarToStr function (VarToStr uses the system settings).  Otherwise, the FormatDateTime function is used and the DateTimeFormat property value is passed as the format pattern.  To know about format specifiers, refer to the FormatDateTime function description in the Delphi/C++ Builder help system.


TcxFilterCriteriaItem
TcxFilterCriteriaItem Object

Hierarchy          Properties          Methods       See Also

Represents a simple condition in the filter criteria list.

Unit

cxFilter

TcxFilterCriteriaItem = class(TcxCustomFilterCriteriaItem);

Description

A simple condition is an operation of comparison (CustomerID < 1000, Name LIKE ‘McD%’, Month <> ‘November’).

To define a condition you must specify:

•	the item for which a filter condition is applied (the TcxFilterCriteriaItem.ItemLink property);

•	the comparison operator (the OperatorKind property);

•	the value with which data is compared (the Value property).

Simple conditions are used in an aggregate filter condition, which represents a list of conditions (simple or aggregate) combined by one logical operator.  The TcxFilterCriteriaItemList class implements an aggregate filter condition.


TcxFilterCriteriaItem Hierarchy
Hierarchy

TObject

     |

TcxCustomFilterCriteriaItem

     |


Properties for TcxFilterCriteriaItem
TcxFilterCriteriaItem Properties

TcxFilterCriteriaItem          Legend

In TcxFilterCriteriaItem

DisplayValue

OperatorKind

Value


Methods for TcxFilterCriteriaItem
TcxFilterCriteriaItem Methods

TcxFilterCriteriaItem          Legend

In TcxFilterCriteriaItem

Create

Destroy


TcxFilterCriteriaItem.DisplayValue

TcxFilterCriteriaItem           See Also

Specifies the text representation of the Value property when displayed in the filter status bar.

property DisplayValue: string;

Description

Use the DisplayValue property to specify the text representation of the Value property.  DisplayValue will be displayed in the filter status bar when the current filter condition is applied to your grid control.


TcxFilterCriteriaItem.OperatorKind

TcxFilterCriteriaItem           See Also

Specifies the operator for the current simple filter condition.

property OperatorKind: TcxFilterOperatorKind;

Description

Use the OperandKind property to set an operator for the current comparison operation.  The value with which data is compared is defined by the Value property.


TcxFilterCriteriaItem.Value

TcxFilterCriteriaItem           See Also

Identifies the value with which item values are compared.

property Value: Variant;

Description

Use the Value property to set a value with which item values are compared when the current filter condition becomes active.  The operator of the comparison operation is specified by the OperatorKind property.


TcxFilterCriteriaItem.Create

TcxFilterCriteriaItem

Creates a simple filter condition in a specific filter criteria list.

constructor Create(AOwner: TcxFilterCriteriaItemList; AItemLink: TObject; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; const ADisplayValue: string); virtual;

Description

The constructor creates a simple filter condition and inserts it into the filter criteria list specified by the AOwner argument.  The AItemLink parameter specifies the item for which this filter condition is applied.  To identify an item you can use an object of the TcxGridColumn class.  Other arguments are used to initialize TcxFilterCriteriaItem properties: AOperatorKind specifies the operator for a filter condition, AValue represents the value with which to compare, ADisplayValue defines the text representation of the AValue parameter.


TcxFilterCriteriaItem.Destroy

TcxFilterCriteriaItem

Destroys a TcxFilterCriteriaItem object instance.

destructor Destroy; override;

Description

The destructor frees all resources allocated by the TcxFilterCriteriaItem object.  Do not call Destroy directly; call Free instead.


TcxFilterCriteriaItemList
TcxFilterCriteriaItemList Object

Hierarchy          Properties          Methods            See Also             Example

Represents the list of filter conditions combined by a logical operator.

Unit

cxFilter

TcxFilterCriteriaItemList = class(TcxCustomFilterCriteriaItem);

Description

The TcxFilterCriteriaItemList represents a list of filter conditions combined by one logical operator.  Conditions are accessible via the Items property and the logical operator is defined by the BoolOperatorKind property.  Conditions can be of two types:

•	a simple condition consisting of a single  comparison (for instance " > 12", " = ‘VISA’ ", " LIKE ‘Mc%’ ", etc.).  The TcxFilterCriteriaItem class represents a single condition.

•	an aggregate condition, which specifies a list of simple (or aggregate) conditions combined by one logical operator.  The TcxFilterCriteriaItemList class represents an aggregate condition.

Two lists are constructed for the following filter criteria:

(CustNo < 1000) AND ((Name LIKE ‘A%’) OR (Name LIKE ‘Z%’))

The first list combines two simple conditions (Name LIKE ‘A%’) and (Name LIKE ‘Z%’) with the OR operator.  The second list combines a simple condition (CustNo < 1000) and the aggregate condition provided by the first list with the AND operator.  The second list is called the root list.

To add a simple condition to the filter criteria list you can use the AddItem method.  To add an aggregate condition to the criteria list use the AddItemList method.

Both the TcxFilterCriteriaItemList and TcxFilterCriteriaItem classes are derived from one base class – TcxCustomFilterCriteriaItem.

Filter criteria for a grid control are defined by the TcxFilterCriteria class.  It provides the TcxFilterCriteria.Root property of the TcxFilterCriteriaItemList type, which you use to construct the filter conditions.


TcxFilterCriteriaItemList Hierarchy
Hierarchy

TObject

     |

TcxCustomFilterCriteriaItem

     |


Properties for TcxFilterCriteriaItemList
TcxFilterCriteriaItemList Properties

TcxFilterCriteriaItemList          Legend

In TcxFilterCriteriaItemList

BoolOperatorKind

Count

Criteria

Items


Methods for TcxFilterCriteriaItemList
TcxFilterCriteriaItemList Methods

TcxFilterCriteriaItemList          Legend

In TcxFilterCriteriaItemList

AddItem

AddItemList

Clear

Create

Destroy


TcxFilterCriteriaItemList.BoolOperatorKind

TcxFilterCriteriaItemList           See Also

Defines the logical operator used to combine filter conditions in the current list.

property BoolOperatorKind: TcxFilterBoolOperatorKind;

Description

Use the BoolOperatorKind property to set a logical operator by which filter conditions are combined. Filter conditions are provided by the indexed Items property.

The default value of the BoolOperatorKind property is fboAnd.


TcxFilterCriteriaItemList.Count

TcxFilterCriteriaItemList           See Also

Specifies the number of conditions (both simple and aggregate) in the current filter condition list.

property Count: Integer;

Description

Use the Count property to determine the number of conditions in the current list of filter conditions.  Filter conditions are provided by the indexed Items property.

ReadOnly Property


TcxFilterCriteriaItemList.Criteria

TcxFilterCriteriaItemList           See Also

Specifies the filter criteria object to which the current filter conditions belong.

property Criteria: TcxFilterCriteria;

Description

Use the Criteria property to reference the instance to which the current list of filter conditions belongs.

ReadOnly Property


TcxFilterCriteriaItemList.Items

TcxFilterCriteriaItemList           See Also

Specifies the list of filter conditions in the current filter criteria list.

property Items: TcxCustomFilterCriteriaItem;

Description

The Items property provides the list of conditions combined by one logical operator specified by the BoolOperatorKind property.  Conditions in this list can be either simple (presented by the TcxFilterCriteriaItem class) or aggregate (presented by a TcxFilterCriteriaItemList instance).  The TcxFilterCriteriaItem and TcxFilterCriteriaItemList classes are both derived from the TcxCustomFilterCriteriaItem class.

ReadOnly Property


TcxFilterCriteriaItemList.AddItem

TcxFilterCriteriaItemList           See Also            Example

Adds a simple condition to the current filter criteria list.

function AddItem(AItemLink: TObject; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; const ADisplayValue: string): TcxFilterCriteriaItem;

Description

The AddItem method adds a new simple condition to the current list provided by the TcxFilterCriteriaItemList object.  A simple condition contains a single comparison operation.  The AItemLink parameter specifies the item for which the new filter condition is created.  The comparison operator is defined by the AOperatorKind parameter and the comparison value is passed in the AValue parameter.  You can supply a string via the ADisplayValue parameter and this will be displayed in the filter status bar when the filter condition is applied to your grid control.  Parameters passed to the AddItem method are used to initialize properties of the TcxFilterCriteriaItem object.


TcxFilterCriteriaItemList.AddItemList

TcxFilterCriteriaItemList           See Also             Example

Adds a new aggregate condition to the current filter criteria list.

function AddItemList(ABoolOperatorKind: TcxFilterBoolOperatorKind): TcxFilterCriteriaItemList;

Description

The AddItemList method adds a new aggregate condition to the current list provided by the TcxFilterCriteriaItemList object.  After the aggregate condition is added, you can populate it with other conditions (simple or aggregate).  Conditions in this list will be combined using the operator specified by the ABoolOperatorKind parameter.


TcxFilterCriteriaItemList.Clear

TcxFilterCriteriaItemList           See Also

Removes all filter conditions from the current list.

procedure Clear;

Description

Use the Clear method to remove all filter conditions from the current TcxFilterCriteriaItemList object.


TcxFilterCriteriaItemList.Create

TcxFilterCriteriaItemList           See Also

Creates a new aggregate condition in a specific filter condition list.

constructor Create(AOwner: TcxFilterCriteriaItemList; ABoolOperatorKind: TcxFilterBoolOperatorKind);

Description

The constructor creates a new aggregate condition (a list of conditions).  The created aggregate condition is inserted as an item into the AOwner list.  The ABoolOperatorKind parameter specifies the logical operator to initialize the BoolOperatorKind property of a new TcxFilterCriteriaItemList object.

If AOwner is set to NIL, the constructor creates a root list of conditions, which is not inserted into another one.  Call the AddItem (AddItemList) method to add a simple (aggregate) condition to the list.


TcxFilterCriteriaItemList.Destroy

TcxFilterCriteriaItemList

Destroys a TcxFilterCriteriaItemList class instance.

destructor Destroy; override;

Description

The destructor frees all memory allocated by the TcxFilterCriteriaItemList object.  Do not call Destroy directly; call Free instead.


TcxFilterValueList
  TcxFilterValueList Object

Hierarchy          Properties          Methods            See Also           Example

Represents a list of values for a filter condition.

Unit

cxFilter

TcxFilterValueList = class(TObject);

Description

When a user clicks the down-arrow in a column caption to select the filter criteria, the popup list appears.  This list is populated with values from the TcxFilterValueList object.  The following image demonstrates this popup list:

If a user selects an element in the list, specific actions are performed in accordance with the type of the selected element.  To access the collection of elements use the indexed Items property.  Every element is an object of the TcxFilterValueItem record type.  The TcxFilterValueItem.Kind field specifies the type of an element.  Element types are defined by the TcxFilterValueItemKind enumerator.

TcxDataFilterValueList is a descendant of the TcxFilterValueList class.  It provides the Load method, called when a user presses the down-arrow button.  This method populates the list with elements.  The number of items added by the Load method is determined by the TcxFilterCriteria.MaxValueListCount property.

The following table describes item types of the TcxFilterValueItemKind enumerator.

Value	Meaning
fviAll	Selecting an element of this type removes the filter conditions set for the corresponding item from the filter criteria. ‘(All)’ is the default string representing an element of this type. An element of the fviAll type is always added to the list.
fviCustom	Selecting an element of this type displays a filter dialog which allows you to visually define filter criteria. ‘(Custom…)’ is the default string representing an element of this type. An element of the fviCustom type is always added to the list.
fviBlanks	Applies a filter condition of the following type: ItemValue IS NULL to an item.  Only records that contain NULL values in this item are selected.  If the TcxFilterCriteria.Options property contains the fcoSoftNull flag, empty strings are considered as NULL and are also selected by this filter. ‘(Blanks)’ is the default string representing an element of this type. An element of the fviBlanks type is added to the list only if the item contains any NULL  value or an empty string (if TcxFilterCriteria.Options contains the fcoSoftNull flag).
fviNonBlanks	Applies a filter condition of the following type: ItemValue IS NOT NULL to an item.  Only records that contain non-NULL values in this item are selected.  If the TcxFilterCriteria.Options property contains the fcoSoftNull flag, empty strings are considered as NULL and are not selected by this filter. ‘(NonBlanks)’ is the default string representing an element of this type. An element of the fviNonBlanks type is added to the list only if the item contains any non-NULL field or a non-empty string (if TcxFilterCriteria.Options contains the fcoSoftNull flag).
fviUser	Selecting an element of this type generates the TcxGridColumn.OnUserFiltering event.  A user can write a handler of this event to construct an aggregate filter condition. In the image above, ‘Filter TODAY’ is an element of the fviUser type. A user can add an element of the fviUser type in the TcxDataFilterCriteria.OnGetValueList event.
fviValue	Inserts a filter condition of the following type: Item = ‘SomeValue’ to the grid filter criteria.  ‘SomeValue’ is a value of the element that a user selected.  ‘Item’ identifies the item for which a user activates the popup list.  This element’s value is defined by the TcxFilterValueItem.Value field.  In the image above, the elements ‘4/12/1988’ and ‘4/17/1988’ are of the fviValue type. Unique values from the item are added to the list as elements of the fviValue type.  The total number of elements to load is specified by the TcxFilterCriteria.MaxValueListCount property.  When working with a large database it is a good idea to limit the number of elements in the list in order to avoid scanning all its records before displaying the list.
fviMRU	An element of this type represents an item from the most recently used list.  By default, this list is displayed at the top of the popup list.  Most recently used items are divided from the rest of the elements by an element of the fviMRUSeparator type. In the image above, the top element (‘4/12/1988’) is of the fviMRU type. As with an element of the fviValue type, selecting an element of the fviMRU type inserts a filter condition based on the element’s value which is specified by the TcxFilterValueItem.Value field.  Refer to the description of the fviValue type for more information.
fviMRUSeparator	An element that separates the most recently used items (of the fviMRU type) from the rest of the elements of the popup list. Selecting an element of the fviMRUSeparator type does nothing.
fviSpecial	An element of the fviSpecial type is relevant only for items that display date/time values.  Selecting this element adds a filter condition to determine whether values fall into a specific date range. In the image above, the elements ‘Yesterday’, ‘Today’, ‘Tomorrow’, ‘1988’, …, ‘1996’ are of the fviSpecial type.

When a user selects an element from the list, a new filter condition replaces existing filter conditions for this item.

You can use the TcxDataFilterCriteria.OnGetValueList event to customize the list of values for a filter condition.  For instance, you can add or delete elements from the list.  This event is generated every time a user clicks the down-arrow button on the column caption.


TcxFilterValueList Hierarchy
Hierarchy

TObject

     |


Properties for TcxFilterValueList
TcxFilterValueList Properties

TcxFilterValueList          Legend

In TcxFilterValueList

Count

Criteria

Items

SortByDisplayText


Methods for TcxFilterValueList
TcxFilterValueList Methods

TcxFilterValueList          Legend

In TcxFilterValueList

Add

Clear

Create

Delete

Destroy

FindItemByKind

FindItemByValue


TcxFilterValueList.Count

TcxFilterValueList           See Also

Contains the number of elements in a list.

property Count: Integer;

Description

Use the Count property to obtain the number of elements in a list.  Elements are provided by the Items property.

ReadOnly Property


TcxFilterValueList.Criteria

TcxFilterValueList           See Also

Defines the filter criteria, which can be changed by a user when an element is selected from the current list.

property Criteria: TcxFilterCriteria;

Description

When a user selects an element from the current list for a specific item, a new filter condition is constructed and added to the filter criteria.  This filter condition replaces any previous filter conditions set for the item.  Use the Criteria property to determine the filter criteria applied to your grid control.

ReadOnly Property


TcxFilterValueList.Items

TcxFilterValueList           See Also

Specifies the array of elements in a list.

property Items[Index: Integer]: PcxFilterValueItem;

Description

Use the Items property to locate a specific element by its index.  Every element represents a pointer to the TcxFilterValueItem record type.  The TcxFilterValueItem.Kind field identifies the kind of an element.  To find an element by its type or value, you can use the TcxFilterValueList.FindItemByKind or TcxFilterValueList.FindItemByValue methods respectively.

The number of elements in a list is specified by the Count property.

ReadOnly Property


TcxFilterValueList.SortByDisplayText

TcxFilterValueList           See Also

Specifies whether elements in the value list are sorted by the elements’ display text.

property SortByDisplayText: Boolean;

Description

Set the SortByDisplayText property to True to sort elements in the value list by display text.  The display text of an element is accessible via the DisplayText field of the TcxFilterValueItem object.

If SortByDisplayText is False, list elements are sorted by values.  Items in the list are displayed in the following order.  The first item in the list is fviAll, the second item is fviCustom, then come fviBlanks, fviNonBlanks, and fviUser.  Items of the fviValue type are placed at the end.  The SortByDisplayText property controls the order of fviValue items.


TcxFilterValueList.Add

TcxFilterValueList           See Also            Example

Adds a new element to the current value list.

type

  TcxFilterValueItemKind = (fviAll, fviCustom, fviBlanks, fviNonBlanks, fviUser, fviValue, fviMRU, fviMRUSeparator, fviSpecial);

procedure Add(AKind: TcxFilterValueItemKind; const AValue: Variant; const ADisplayText: string; ANoSorting: Boolean); virtual;

Description

To add an element to the list you must specify its type, the value to be stored, and the text with which this element will be displayed in the popup list.  The AKind, AValue, ADisplayText parameters are used to initialize the fields of the TcxFilterValueItem object representing an element.

The ANoSorting parameter specifies the position at which a specific element is inserted.  If ANoSorting is True, the element is inserted at the end of the list.  Otherwise, it is inserted so as to maintain the existing elements’ sort order.  By default, elements are sorted by values.  You can set the SortByDisplayText property to True to sort elements by their display texts.


TcxFilterValueList.Clear

TcxFilterValueList           See Also

Removes all elements from the current value list.

procedure Clear; virtual;

Description

The Clear method removes all elements from the list.  To delete a specific element use the Delete method.


TcxFilterValueList.Create

TcxFilterValueList

Creates an instance of the TcxFilterValueList object.

constructor Create(ACriteria: TcxFilterCriteria); virtual;

Description

The constructor creates a new list of filter condition values for the specified filter criteria.  After the list is created it does not contain any elements.  The ACriteria parameter specifies the filter criteria, which will be changed when a user selects an element from the current list.

The descendant of the TcxFilterValueList class, TcxDataFilterValueList, provides the Load method, called right before displaying the popup list.  This method populates the list with elements.  The number of items added by the Load method is determined by the TcxFilterCriteria.MaxValueListCount property.


TcxFilterValueList.Delete

TcxFilterValueList             See Also           Example

Deletes an element at a specified position from the current list.

procedure Delete(AIndex: Integer);

Description

The Delete method deletes an element at the position specified by the AIndex parameter.  Use the FindItemByKind and FindItemByValue functions to determine the index of a specific element.  You can remove all elements from the list at once via the Clear method.


TcxFilterValueList.Destroy

TcxFilterValueList

Destroys an instance of the TcxFilterValueList class.

destructor Destroy; override;

Description

The destructor deletes a TcxFilterValueList object instance and frees all resources allocated for it.  Do not call Destroy directly; call Free instead.


TcxFilterValueList.FindItemByKind

TcxFilterValueList             See Also            Example

Locates the list element of a specific type and value.

Overloaded Variants

type

  TcxFilterValueItemKind = (fviAll, fviCustom, fviBlanks, fviNonBlanks, fviUser, fviValue, fviMRU, fviMRUSeparator, fviSpecial);

function FindItemByKind(AKind: TcxFilterValueItemKind; const AValue: Variant): Integer; overload;

function FindItemByKind(AKind: TcxFilterValueItemKind): Integer; overload;

Description

The first overloaded variant locates an item element of the type and value specified by the AKind and AValue parameters, respectively.  If this function fails to locate an element of the specified type and value, it returns –1.  If Null is passed as the value of the AValue parameter, the FindItemByKind function returns the position of the first list element of a specific type.

Note:	This variant is useful for locating elements of the fviUser, fviValue and fviSpecial types.

The second variant locates the first list element of the type specified by the AKind parameter and calls the first overloaded variant by passing Null as the AValue parameter.

Note:	To find specific elements of the fviValue type, you should use the FindItemByValue function.


TcxFilterValueList.FindItemByValue

TcxFilterValueList            See Also          Example

Locates the first list element with a specific value.

function FindItemByValue(const AValue: Variant): Integer;

Description

The FindItemByValue method returns the position of an element with the value defined by the AValue parameter.  If the function fails to locate such an element, it returns –1.


PcxFilterValueItem
PcxFilterValueItem type

Represents a pointer to the TcxFilterValueItem record type.

Unit

cxFilter

PcxFilterValueItem = ^TcxFilterValueItem;

Description

The PcxFilterValueItem type represents a pointer to the TcxFilterValueItem record.  This type describes an element of the TcxFilterValueList collection.


TcxFilterBoolOperatorKind
TcxFilterBoolOperatorKind type

Represents an operation that combines filter conditions in the filter criteria for a grid control.

Unit

cxFilter

TcxFilterBoolOperatorKind = (fboAnd, fboOr, fboNotAnd, fboNotOr);

Description

The TcxFilterBoolOperatorKind type enumerates operations used to combine filter conditions to construct aggregate filter criteria for a grid control.  Use the TcxFilterCriteriaItemList.BoolOperatorKind property to set the operation combining filter conditions in the list.

Value	Meaning
fboAnd	Defines the logical OR operation for filter conditions.
fboOr	Defines the logical AND operation for filter conditions.
fboNotAnd	Combines conditions using the logical AND operator and then negates the result.
fboNotOr	Combines conditions using the logical OR operator and then negates the result.


TcxFilterCriteriaOption
TcxFilterCriteriaOption type

Enumerates different options for filtering data.

Unit

cxFilter

TcxFilterCriteriaOption = (fcoCaseInsensitive, fcoShowOperatorDescription, fcoSoftNull, fcoSoftCompare, fcoIgnoreNull);

Description

The TcxFilterCriteriaOption represents an enumeration of values that control data filtering.  The following table describes the possible options.  Filter options are supported by the TcxFilterCriteria.Options property.

Value	Meaning
fcoCaseInsensitive	Specifies whether filtering is case sensitive.  When this flag is active in the TcxFilterCriteria.Options property, filtering does not distinguish upper and lowercase characters.
fcoShowOperatorDescription	If set, replaces operator symbols with their corresponding text representation. For instance, the ‘=’ operator is replaced with the ‘equals’ string.  Operator descriptions are defined in the cxFilterConsts.pas source file.
fcoSoftNull	If set, empty strings are considered as NULL values when comparing.
fcoSoftCompare	If set, no exception is thrown when comparing values of incompatible types.
fcoIgnoreNull	If set, NULL values are ignored when comparing and are excluded from the filtered results.


TcxFilterCriteriaOptions
TcxFilterCriteriaOptions type

Represents a set of options to filter data.

Unit

cxFilter

TcxFilterCriteriaOptions = set of TcxFilterCriteriaOption;

Description

Filtering options are described by the TcxFilterCriteriaOption enumeration.  Use the TcxFilterCriteria.Options property to access  the current filtering options of a grid control.


TcxFilterOperatorKind
TcxFilterOperatorKind type

See Also

Represents an enumeration of operators for a single filter condition.

Unit

cxFilter

TcxFilterOperatorKind = (foEqual, foNotEqual, foLess, foLessEqual,

    foGreater, foGreaterEqual, foLike, foNotLike,

    foBetween, foNotBetween,

    foInList, foNotInList,

    foYesterday, foToday, foTomorrow, fcoLast7Days,

    foLastWeek, foLast14Days, foLastTwoWeeks, foLast30Days, foLastMonth, foLastYear, foInPast,

    foThisWeek, foThisMonth, foThisYear,

    foNextWeek, foNext14Days, foNextTwoWeeks, foNext30Days, foNextMonth, foNextYear, foInFuture);

Description

The TcxFilterOperatorKind type enumerates operators used in a simple filter condition of the TcxFilterCriteriaItem class.  A simple filter condition consists of a single comparison operation.  The operator for the comparison operation is provided by the TcxFilterCriteriaItem.OperatorKind property.  The item values are compared according to the TcxFilterCriteriaItem.Value property.

Comparison operators check whether two expressions match.  The following table lists possible operators:

Value	Meaning
foEqual	Operator ‘=’ Equal to Example
foNotEqual	Operator ‘<>’ Not equal to
foLess	Operator ‘<’ Less than
foLessEqual	Operator ‘<=’ Less than or equal to
foGreater	Operator ‘>’ Greater than
foGreaterEqual	Operator ‘>=’ Greater than or equal to
foLike	Operator ‘LIKE’ TRUE if the operand matches a pattern. With the LIKE operator you can use ‘%’ and ‘_’ wildcards.  The ‘%’ wildcard substitutes any number of characters.  The ‘_’ character is used to represent any single character.  You can assign another characters to be used as wildcards via the TcxFilterCriteria.PercentWildcard and TcxFilterCriteria.UnderscoreWildcard properties. For instance, the operator "LIKE 'Mc%' " returns true for all strings that begin with the letters ‘Mc’ and contain any number of characters.
foNotLike	Operator ‘NOT LIKE’ TRUE if the operand does not match a pattern. See the description of the foLike value.
foBetween	Operator ‘BETWEEN’ TRUE if the operand is between two inclusive values.  These values are specified as an array of variants using the TcxFilterCriteriaItem.Value property. To create the variant array, you can use the VarBetweenArrayCreate function (declared in the cxVariants unit) or the standard VarArrayCreate function. Example
foNotBetween	The negation of the ‘BETWEEN’ operator TRUE if the operand does not belong to a range.  The bounds of the range are specified by the TcxFilterCriteriaItem.Value property.  It holds an array of variants.  To create an array of variants for the foNotBetween operator (as well as for foBetween), see the VarBetweenArrayCreate function (declared in the cxVariants unit) or the standard VarArrayCreate function. Refer to the example provided for the foBetween operator.
foInList	The membership test operator. TRUE if the operand is in the value list provided by the TcxFilterCriteriaItem.Value property.  To create a list of values, see the VarArrayCreate function, for instance. Example
foNotInList	The negation of the foInList operator. TRUE if the operand is not a member of the value list provided by the TcxFilterCriteriaItem.Value property.  To create a list of values, see the VarArrayCreate function, for instance. Refer to the example provided for the foNotInList operator.
foYesterday	Applied to date values. TRUE if the operand is equal to yesterday’s date. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored. Example
foToday	Applied to date values. TRUE if the operand is equal to the current date. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foTomorrow	Applied to date values. TRUE if the operand is equal to tomorrow’s date. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLast7Days	Applied to date values. TRUE if the operand falls within the last seven days.  By default, today’s date is included into the range as specified by the cxFilterIncludeTodayInLastNextDaysList global variable. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLastWeek	Applied to date values. TRUE if the operand falls within the previous week. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLast14Days	Applied to date values. TRUE if the operand falls within the last fourteen days.  By default, today’s date is included into the range as specified by the cxFilterIncludeTodayInLastNextDaysList global variable. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLastTwoWeeks	Applied to date values. TRUE if the operand falls within the previous two weeks. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLast30Days	Applied to date values. TRUE if the operand falls within the last thirty days.  By default, today’s date is included into the range as specified by the cxFilterIncludeTodayInLastNextDaysList global variable. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLastMonth	Applied to date values. TRUE if the operand falls within the previous month. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foLastYear	Applied to date values. TRUE if the operand falls within the previous year. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foInPast	Applied to date values. TRUE if the operand falls within the past dates. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foThisWeek	Applied to date values. TRUE if the operand falls within the current week. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foThisMonth	Applied to date values. TRUE if the operand falls within the current month. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foThisYear	Applied to date values. TRUE if the operand falls within the current year. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNext7Days	Applied to date values. TRUE if the operand falls within the next seven days.  By default, today’s date is included into the range as specified by the cxFilterIncludeTodayInLastNextDaysList global variable. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNextWeek	Applied to date values. TRUE if the operand falls within the next week. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNext14Days	Applied to date values. TRUE if the operand falls within the next fourteen days.  By default, today’s date is included into the range as specified by the cxFilterIncludeTodayInLastNextDaysList global variable. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNextTwoWeeks	Applied to date values. TRUE if the operand falls within the next two weeks. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNext30Days	Applied to date values. TRUE if the operand falls within the next thirty days.  By default, today’s date is included into the range as specified by the cxFilterIncludeTodayInLastNextDaysList global variable. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNextMonth	Applied to date values. TRUE if the operand falls within the next month. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foNextYear	Applied to date values. TRUE if the operand falls within the next year. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.
foInFuture	Applied to date values. TRUE if the operand falls within the future dates. The value and display text provided by the TcxFilterCriteriaItem.Value and TcxFilterCriteriaItem.DisplayValue properties respectively are ignored.


TcxFilterValueItem
TcxFilterValueItem type

Represents an element in the list of the TcxFilterValueList class.

Unit

cxFilter

TcxFilterValueItem = record

    Kind: TcxFilterValueItemKind;

    Value: Variant;

    DisplayText: string;

end;

Description

The TcxFilterValueList class represents a list of values for filter conditions.  A pointer that refers to the TcxFilterValueItem record type presents each element in this list.

The following table describes TcxFilterValueItem fields.

Field	Meaning
Kind	Specifies the type of an element.  The TcxFilterValueItemKind type enumerates possible values for this field.
Value	Specifies the value for an element.
DisplayText	Contains the text representation of an element.


TcxFilterValueItemKind
TcxFilterValueItemKind type

Enumerates element types in the TcxFilterValueList list.

Unit

cxFilter

type

  TcxFilterValueItemKind = (fviAll, fviCustom, fviBlanks, fviNonBlanks, fviUser, fviValue, fviMRU, fviMRUSeparator, fviSpecial);

Description

The TcxFilterValueList class represents a list of values for filter conditions.  Elements from this list are used to populate the popup list of filter conditions.  A user activates the list by clicking the down-arrow button in the column caption.  By selecting an element from the list, a user changes the filter condition for the current column.  Refer to the description of the TcxFilterValueList class to learn about meanings of TcxFilterValueItemKind values.


cxFilterIncludeTodayInLastNextDaysList
cxFilterIncludeTodayInLastNextDaysList global variable

Specifies whether today’s date is included into the value range of date operators.

Unit

cxFilter

var

  cxFilterIncludeTodayInLastNextDaysList: Boolean = True;

Description

This variable specifies whether today’s date is included into the value range of date operators that calculate the range relative to today’s date, such as foLast7Days, foLast14Days, foLast30Days, foNext7Days, foNext14Days and foNext30Days.  When the cxFilterIncludeTodayInLastNextDaysList variable is set to True, today’s date is included into the value range.

Refer to the description of the TcxFilterOperatorKind type for details on these operators.


cxFilterControl Unit Overview
cxFilterControl Unit

Classes

TcxCustomFilterControl

TcxFilterControl

Interfaces

IcxFilterControl


Notification_ALink
Note

The requested topic cannot be found.  This may be due to using the Developer Express help system standalone.  Make sure to run it from the Delphi help system.


TcxCustomFilterControl
TcxCustomFilterControl Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for filter controls.

Unit

cxFilterControl

TcxCustomFilterControl = class(TcxControl, IcxMouseTrackingCaller)

Description

The TcxCustomFilterControl class is the base class for the TcxFilterControl or TcxDBFilterControl classes representing filter controls used for composing and applying a set of filter conditions to the bound object.  The linked object represents either an object implementing the IcxFilterControl interface – typically a grid table view (for the TcxFilterControl), or a dataset (for the TcxDBFilterControl).

The TcxCustomFilterControl class provides properties, methods and events defining the common functionality of filter controls.  The Criteria property introduced in the TcxCustomFilterControl class represents the filter criteria specified by a filter control.  The filter criteria contain a list of filter conditions.  The FilterText property contains a string that describes the defined filter conditions.  Filter conditions created in a filter control at runtime can be saved to and then loaded from either a specific file or stream.  For this purpose you can use the SaveToFile, SaveToStream, LoadFromFile, LoadFromStream methods.

You can specify font characteristics for different elements of a filter control by using a set of specific properties (FontBoolOperator, FontCondition, FontItem, FontValue).

Do not create instances of the TcxCustomFilterControl class.  Use its descendants such as TcxFilterControl or TcxDBFilterControl instead.


TcxCustomFilterControl Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxCustomFilterControl
TcxCustomFilterControl Properties

TcxCustomFilterControl          Legend

In TcxCustomFilterControl

Color

Criteria

FilterLink

FilterText

FontBoolOperator

FontCondition

FontItem

FontValue

NullString

ShowLevelLines

SortItems

WantTabs

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomFilterControl
TcxCustomFilterControl Methods

TcxCustomFilterControl          Legend

In TcxCustomFilterControl

ApplyFilter

BuildFromCriteria

Clear

Create

Destroy

LoadFromFile

LoadFromStream

Localize

SaveToFile

SaveToStream

Derived from TcxControl

InvalidateRect


Events for TcxCustomFilterControl
TcxCustomFilterControl Events

TcxCustomFilterControl          Legend

In TcxCustomFilterControl

OnApplyFilter


TcxCustomFilterControl.Color

TcxCustomFilterControl

Specifies the background color of a filter control.

property Color: TColor;

Description

The default value of the Color property is clBtnFace.


TcxCustomFilterControl.Criteria

TcxCustomFilterControl          See Also

Provides access to the filter criteria defined by a filter control.

property Criteria: TcxFilterControlCriteria;

Description

For the TcxFilterControl object, which is destined to operate with any IcxFilterControl-supported objects (typically, grid table views), the Criteria property is of great importance.  When applying filtering with the help of the ApplyFilter method, the value of the Criteria property is assigned to the Criteria property of the object linked to the filter control via the LinkComponent property.  As a result, the filter conditions defined in a filter control are automatically applied to data of the linked object.  Also, when calling the UpdateFilter method, the Criteria property value is updated – it takes the value of the linked object’s Criteria property.

As for the TcxDBFilterControl object, the Criteria property represents an implementation of the Criteria property declared by the IcxFilterControl interface.  The TcxDBFilterControl object is forced to support this interface itself, since a dataset object to which a data bound filter control is linked via the DataSet property does not provide native means for this purpose.

Note:	Call the BuildFromCriteria method to update filter conditions displayed by the filter control when the Criteria property is modified in code.

ReadOnly Property


TcxCustomFilterControl.FilterLink

TcxCustomFilterControl

Indicates the target object to which the specified filter conditions are applied.

property FilterLink: IcxFilterControl;

Description

The FilterLink property is used internally to gain access to a specific linked object to which filter conditions should be applied.

For the TcxFilterControl, the FilterLink property returns a pointer to the IcxFilterControl interface supported by an object (typically, a grid table view object) to which a filter control is linked.  The linked object is specified by the LinkComponent property.

Since the TcxDBFilterControl object supports the IcxFilterControl interface by itself, its FilterLink property returns a reference to that supported interface.

ReadOnly Property


TcxCustomFilterControl.FontBoolOperator

TcxCustomFilterControl          See Also

Specifies font settings for logical operators.

property FontBoolOperator: TFont;

Description

Use the FontBoolOperator property to specify font characteristics used to display logical operators (AND, OR, NOT AND, NOT OR) within a filter control.  A filter control uses logical operators to combine defined filter conditions.

The following picture displays how settings of the FontBoolOperator property affect the control’s appearance.

Note that font styles and effects (i.e. italic, bold, underline) do not affect the appearance of the logical operators within their dropdown list.


TcxCustomFilterControl.FontCondition

TcxCustomFilterControl          See Also

Specifies font settings for comparison operators.

property FontCondition: TFont;

Description

Use the FontCondition property to specify font characteristics used to display comparison operators (such as ‘equals’, ‘is less than or equal to’, ‘is greater than’, ‘like’, etc) within a filter control.

The following picture displays how settings of the FontCondition property affect the control’s appearance.

Note that font styles and effects (i.e. italic, bold, underline) do not affect the appearance of the comparison operators within their dropdown list.


TcxCustomFilterControl.FontItem

TcxCustomFilterControl          See Also

Specifies font settings for items whose data participate in filter operation.

property FontItem: TFont;

Description

Use the FontItem property to specify font characteristics used to display the names of items for which filter conditions are applied.

The following picture displays how settings of the FontItem property affect the control’s appearance.

Note that font styles and effects (i.e. italic, bold, underline) do not affect the appearance of the filter items within their dropdown list.


TcxCustomFilterControl.FontValue

TcxCustomFilterControl          See Also

Specifies font settings for values with which to compare.

property FontValue: TFont;

Description

Use the FontValue property to specify font characteristics used to display values with which item values are compared.

The following picture displays how settings of the FontValue property affect the control’s appearance.


TcxCustomFilterControl.NullString

TcxCustomFilterControl

Specifies the initial text displayed within a new condition.

property NullString: string;

Description

Use the NullString property to specify the text to be displayed as a comparison value after a new condition is added to a filter control.  The NullString property is initialized with the ‘<empty>’ value when creating an instance of the TcxCustomFilterControl object.


TcxCustomFilterControl.ShowLevelLines

TcxCustomFilterControl

Specifies whether level lines are displayed.

property ShowLevelLines: Boolean;

Description

Use the ShowLevelLines property to control displaying level lines within a filter control.  If this property is True (the default behavior), level lines are displayed.

Set the ShowLevelLines property to False to hide level lines within a filter control.

The default value of the ShowLevelLines property is True.


TcxCustomFilterControl.SortItems

TcxCustomFilterControl

Specifies whether the items should be automatically sorted.

property SortItems: Boolean;

Description

Set the SortItems property to True to automatically sort the items in ascending order. Otherwise the items will remain in the order that they were inserted in.

The default value of the SortItems property is False.


TcxCustomFilterControl.WantTabs

TcxCustomFilterControl

Specifies whether a user can tab to elements within a filter control.

property WantTabs: Boolean;

Description

Use the WantTabs property to allow or disallow access to the control’s elements using the Tab key.

If WantTabs is True, an end user can use the Tab key to move focus to elements of a filter control.  In this case, elements of a filter control (such as logical and comparison operators, items and values, specific control elements) are in the internal tab order and can be accessed using the Tab key.

If the WantTabs property is False, a user can't press the Tab key to move through elements of a filter control.  Pressing this key moves focus to the next control in the parent’s tab order.

The default value of the WantTabs property is False.


TcxCustomFilterControl.ApplyFilter

TcxCustomFilterControl          See Also

Applies stated filter conditions to the linked object.

procedure ApplyFilter;

Description

The ApplyFilter method applies filtering to the linked object based upon filter conditions stated in a filter control and then raises the OnApplyFilter event.

For the TcxFilterControl object, which is destined to operate with any IcxFilterControl-supported objects (typically, grid table views), the ApplyFilter method automatically applies the specified filter conditions to the linked object.  When the ApplyFilter method is called, the value of the Criteria property is assigned to the Criteria property of the target object linked to the filter control via the LinkComponent property.  As a result, the filter conditions defined in a filter control are automatically applied to data of the linked object.

For filter controls of the TcxDBFilterControl type, you should manually apply filter conditions to the underlying dataset based upon the FilterText property setting.  The suitable place to perform this task is a handler for the OnApplyFilter event.


TcxCustomFilterControl.BuildFromCriteria

TcxCustomFilterControl          See Also

Recreates filter conditions using the filter criteria specified via the Criteria property.

procedure BuildFromCriteria; virtual;

Description

Call this method to refresh filter conditions displayed by the filter control after the Criteria property has been modified in code.


TcxCustomFilterControl.Clear

TcxCustomFilterControl          See Also

Deletes all the filter conditions.

procedure Clear; virtual;

Description

Use the Clear method to delete all the filter conditions defined in a filter control.  This method removes all condition rows displayed in a filter control and empties the filter criteria (accessed via the Criteria property).  Consequently, the FilterText property is resetted since its value is built based upon the defined filter criteria.


TcxCustomFilterControl.Create

TcxCustomFilterControl          See Also

Creates a new TcxCustomFilterControl class instance.

constructor Create(AOwner: TComponent); override;

Description

The Create method is used to create a new instance of the TcxCustomFilterControl class at runtime.  It sets properties to their default values after calling the inherited constructor.  The AOwner parameter represents the owner of the newly created filter control.

Do not create instances of the TcxCustomFilterControl class.  Instantiate one of its descendant controls instead.


TcxCustomFilterControl.Destroy

TcxCustomFilterControl          See Also

Destroys the TcxCustomFilterControl object.

destructor Destroy; override;

Description

The Destroy method is used to dispose the TcxCustomFilterControl object and free any allocated memory.

Do not create and destroy TcxCustomFilterControl objects in applications.  Manipulate one of its descendant controls instead.


TcxCustomFilterControl.LoadFromFile

TcxCustomFilterControl          See Also

Loads filter conditions data from a file.

procedure LoadFromFile(const AFileName: string);

Description

Use the LoadFromFile method to retrieve filter conditions data from a file specified by the AFileName parameter and load them into a TcxCustomFilterControl object.  The AFileName parameter should reference a file that was saved using the SaveToFile method.


TcxCustomFilterControl.LoadFromStream

TcxCustomFilterControl          See Also

Loads filter conditions data from the specified stream object.

procedure LoadFromStream(AStream: TStream);

Description

Use the LoadFromStream method to retrieve filter conditions data from a stream object specified by the AStream parameter and load them into a TcxCustomFilterControl object.  The stream should contain data previously saved using the SaveToStream method.


TcxCustomFilterControl.Localize

TcxCustomFilterControl

Assigns values of the resource strings to the corresponding text elements of a filter control.

procedure Localize;

Description

Use the Localize method when you need to update values of the text elements displayed within a filter control (such as popup menu items text, control elements text, logical operators, comparison operators, empty value text) based upon the changed values of the corresponding resource strings.

String constants for filter controls are stored as resources in the cxFilterControlStrs unit.  Moving display strings into string resources makes an application easier to localize without rewriting the program.  For localization purposes, you might want to substitute values of specific resource strings.  For this to be done, you should perform the following two steps:

•	Change specific resource strings’ values.

To change a resource string, use the cxSetResourceString procedure available within the cxClasses unit.  This procedure substitutes the value of the resource string during execution only.  Note that a new value does not replace a resource in an executable file.

For instance, you may use the following code lines to specify German equivalents for resource strings representing items of a filter control’s popup menu.

//Delphi

cxSetResourceString(@cxSFilterAddCondition, 'Kondition hinzfügen');

cxSetResourceString(@cxSFilterAddGroup, 'Gruppe hinzfügen');

cxSetResourceString(@cxSFilterClearAll, 'Alles löschen');

cxSetResourceString(@cxSFilterRemoveRow, 'Zeile löschen');

//C++ Builder

cxSetResourceString(&_cxSFilterAddCondition, "Kondition hinzfügen");

cxSetResourceString(&_cxSFilterAddGroup, "Gruppe hinzfügen");

cxSetResourceString(&_cxSFilterClearAll, "Alles löschen");

cxSetResourceString(&_cxSFilterRemoveRow, "Zeile löschen");

•	Call the Localize method.

The Localize method retrieves resource strings settings with the help of the cxGetResourceString function and assigns the obtained values to the corresponding filter control’s text elements.

As a result, when a popup menu is called, it contains items translated into German.


TcxCustomFilterControl.SaveToFile

TcxCustomFilterControl          See Also

Saves filter conditions data to a file.

procedure SaveToFile(const AFileName: string);

Description

Use the SaveToFile method to store filter conditions data to a file specified by the AFileName parameter.  This method is useful if you want to persist filter conditions created at runtime.

The filter conditions can later be reloaded from the file into a filter control using the LoadFromFile method.


TcxCustomFilterControl.SaveToStream

TcxCustomFilterControl          See Also

Saves filter conditions data to a stream object.

procedure SaveToStream(AStream: TStream);

Description

Use the SaveToStream method to save filter conditions data to a stream object specified by the AStream parameter.  This method is useful if you want to persist filter conditions created at runtime.

The filter conditions can later be reloaded from the stream into a filter control using the LoadFromStream method.


TcxCustomFilterControl.OnApplyFilter

TcxCustomFilterControl          See Also

Occurs when applying filter conditions to the linked object.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnApplyFilter: TNotifyEvent;

Description

Write a handler for the OnApplyFilter event to perform specific actions after filter conditions defined in a filter control are applied to the linked object.  For instance, in an event handler you can analyze conditions of filtering applied and add additional filter criterion at the linked object level.  Since a filter control performs filter criteria synchronization with the linked object after the OnApplyFilter event has been handled, it will reflect changes made to linked object’s filter conditions.

If you use a filter control of the TcxDBFilterControl type, you can handle the OnApplyFilter event to modify an SQL statement used to populate a dataset object linked to the filter control via the DataSet property.  The FilterText property value can be used to construct the WHERE clause in the SELECT statement.


TcxCustomFilterControl.FilterText

TcxCustomFilterControl          See Also

Specifies the text representation of the filter criteria defined by a filter control.

property FilterText: string;

Description

The FilterText property contains a string that describes filter conditions defined by a filter control.  Unlike the FilterCaption property, used for display purposes only, a string represented by the FilterText property is composed in compliance with SQL syntax requirements.

Below is an example of FilterText and FilterCaption property values.

FilterText:	(State = 'CA') AND (PurchaseDate = '01-Mar-1976')

FilterCaption:	(State = CA) and (PurchaseDate = 01-Mar-1976)

The FilterText property is particularly important for a filter control of the TcxDBFilterControl type.  Since the value of the FilterText property can be applied to a dataset or an SQL statement, you can use it to force a filter control’s linked dataset (specified by the DataSet property) to filter the records itself.  When the end user creates filter conditions by means of the filter control, the value of the FilterText property is constructed automatically.  Thus, you can simply assign the FilterText property value to the dataset’s Filter property to apply filtering specified by the end user.

//Delphi

with cxDBFilterControl1.DataSet do

begin

  Filter := cxDBFilterControl1.FilterText;

  Filtered := True;

end

If a data aware filter control is bound to a set of data retrieved by a specific SQL query, you can use the FilterText property’s value to compose the required WHERE clause.  This clause can then be added to the SELECT statement in code by providing a handler for the OnApplyFilter event.

ReadOnly Property


TcxCustomFilterControl.FilterCaption

TcxCustomFilterControl          See Also

Determines the text representation of the filter criteria used for display purposes.

property FilterText: string;

Description

The FilterCaption property contains a string, which is a user friendly version of the FilterText property value.  The FilterCaption property can be used to display filter conditions defined by a filter control in the status bar or somewhere else as your application needs dictate.

Below is an example of FilterText and FilterCaption property values.

FilterText:	(State = 'CA') AND (PurchaseDate = '01-Mar-1976')

FilterCaption:	(State = CA) and (PurchaseDate = 01-Mar-1976)

ReadOnly Property


TcxCustomFilterControl.HotTrackOnUnfocused

TcxCustomFilterControl

Specifies whether hot-track effects should be applied to elements of a non-focused filter control.

property HotTrackOnUnfocused: Boolean;

Description

Set the HotTrackOnUnfocused property to False if you do not want to highlight control elements of a filter control when it does not have focus.

If this property is True, control elements will be highlighted on moving the mouse cursor over them regardless of whether the filter control has focus or not.

The default value of the HotTrackOnUnfocused property is True.


TcxFilterControl
 TcxFilterControl Object

Hierarchy          Properties          Methods          Events          See Also

Represents a filter control operating on IcxFilterControl-supported objects (typically, grid table views).

Unit

cxFilterControl

TcxFilterControl = class(TcxCustomFilterControl)

Description

The TcxFilterControl is integrated into the ExpressQuantumGrid4 to provide advanced filter operations for end users at runtime.  It is a part of the Filter building dialog that can be invoked via a click on the Customize button to the right of the filter panel.

The Customize button is displayed if the Filtering.CustomizeDialog property of the grid’s (banded) table view (a TcxGridTableView descendant) is set to True.  The TcxFilterControl allows end users to visually construct complex filter criteria by combining simple filter conditions using logical operators for individual items (columns in grid table views).

You can also use the TcxFilterControl to facilitate managing filter operations for end users when filtering data of any object supported the IcxFilterControl interface.

The TcxCustomFilterControl class implements the most of filter control functionality.  The TcxFilterControl class barely introduces the LinkComponent property which specifies a target object (typically, a table view) to be filtered.

If you need to filter data by means of a dataset, you can use the TcxDBFilterControl instead.  This control links to an object derived from the TDataSet class and allows users to manage filtering of such an object by building specific filter conditions.


TcxFilterControl Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomFilterControl

     |


Properties for TcxFilterControl
TcxFilterControl Properties

TcxFilterControl          Legend

In TcxFilterControl

LinkComponent

Derived from TcxCustomFilterControl

Color

Criteria

FilterLink

FilterText

FontBoolOperator

FontCondition

FontItem

FontValue

NullString

ShowLevelLines

SortItems

WantTabs

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxFilterControl
TcxFilterControl Methods

TcxFilterControl          Legend

In TcxFilterControl

UpdateFilter

Derived from TcxCustomFilterControl

ApplyFilter

BuildFromCriteria

Clear

Create

Destroy

LoadFromFile

LoadFromStream

Localize

SaveToFile

SaveToStream

Derived from TcxControl

InvalidateRect


Events for TcxFilterControl
TcxFilterControl Events

TcxFilterControl          Legend

Derived from TcxCustomFilterControl

OnApplyFilter


TcxFilterControl.LinkComponent

TcxFilterControl

Specifies an object whose data is to be filtered.

property LinkComponent: TComponent;

Description

Use the LinkConponent property of the TcxFilterControl to specify an object, which is linked to the filter control.  The linked object (typically, a table view) should support the IcxFilterControl interface to be able to interact with a filter control properly.

Filter controls of the TcxFilterControl type provide building complex filter conditions and applying them to the linked object specified by the LinkComponent property.


TcxFilterControl.UpdateFilter

TcxFilterControl

Updates the filter criteria of the filter control using the bound component’s filtering conditions.

procedure UpdateFilter;

Description

Use the UpdateFilter method to update the filter criteria of a filter control based upon filter conditions defined and applied at the level of an object specified by the LinkComponent property.  This method retrieves the linked object’s filter criteria via its Criteria property and assigns the obtained value to the Criteria property of the filter control.  As a result, the filter control will display filter conditions applied to the linked object.

Thus, you can use the UpdateFilter method to provide one-way filter criteria synchronization – from the linked object to the filter control.


TcxFilterItem
TcxFilterItem Object

Hierarchy          Properties          Methods          See Also

In filter controls, represents a dataset field that can be involved in filtering.

Unit

cxDBFilterControl

TcxFilterItem = class(TCollectionItem, IcxEditRepositoryItemListener, IUnknown)

Description

Filter controls of the TcxDBFilterControl type use the Items collection to maintain a list of specific explicitly declared filter items.  Such items (if any is declared by you) represent dataset fields, which are available for constructing filter conditions.  The TcxFilterItem class represents an individual item of the Items collection.  It can be accessed via the collection’s Items property.

The TcxFilterItem object introduces the FieldName property, which points to the required field from the linked dataset.  This field will be represented in a filter control using the name specified by the Caption property.

The TcxFilterItem object provides facility to specify the type of editor associated with the filter item.  The specified editor will be used for editing the value to which item’s values are compared.  You can assign a particular editor for a filter value via the Properties property or use the repository mechanism and the RepositoryItem property.


TcxFilterItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxFilterItem
TcxFilterItem Properties

TcxFilterItem          Legend

In TcxFilterItem

Caption

FieldName

Properties

PropertiesClass

RepositoryItem


Methods for TcxFilterItem
TcxFilterItem Methods

TcxFilterItem          Legend

In TcxFilterItem

Create

Destroy

GetProperties


TcxFilterItem.Caption

TcxFilterItem          See Also

Specifies an item’s caption.

property Caption: string;

Description

Use the Caption property to specify the caption of an explicitly declared item.  The text specified by this property is displayed within both the dropdown list of items and the condition rows that refer to the item.


TcxFilterItem.Properties

TcxFilterItem          See Also

Defines settings specific to the editor associated with the item.

property Properties: TcxCustomEditProperties;

Description

Use the Properties object to specify the editor type for editing a value the item data is compared to and define settings specific to the edit control.


TcxFilterItem.PropertiesClass

TcxFilterItem          See Also

Specifies the class of the editor used to edit a value the item data is compared to.

type

  TcxCustomEditPropertiesClass = class of TcxCustomEditProperties;

property PropertiesClass: TcxCustomEditPropertiesClass;

Description

Use the PropertiesClass property to assign a particular editor to edit a value with which to compare.  To assign an editor, set the PropertiesClass to a TcxCustomEditProperties class descendant, such as TcxComboBoxProperties.

Once PropertiesClass is set, the Properties member provides access to available editor settings.

The following code shows how to specify the calculator editor to edit data of the first item.  The QuickClose property is set to True to enable closing the calculator dropdown window when a user presses the ‘=’ keyboard key.

//Delphi

  cxDBFilterControl1.Items[0].PropertiesClass := TcxCalcEditProperties;

  TcxCalcEditProperties(cxDBFilterControl1.Items[0].Properties).QuickClose := True;

The RepositoryItem property also allows you to assign an editor for the item.  If an editor is assigned via RepositoryItem, then PropertiesClass and Properties are ignored.

See the GetProperties method to obtain a reference to edit properties specified by the RepositoryItem or PropertiesClass attribute.  If neither of them is set, the method retrieves properties from the default editor applied for the item.


TcxFilterItem.RepositoryItem

TcxFilterItem          See Also

Specifies the repository item representing the editor for the item’s value.

property RepositoryItem: TcxEditRepositoryItem;

Description

A repository item refers to the editor used to edit comparison value.  If you set an editor for an item via RepositoryItem, the values of Properties and PropertiesClass properties are ignored.  Working with a repository and creating repository items is discussed in the Edit Repository Items topic.

You can determine the properties of the editor specified for the item via the GetProperties method.  It retrieves properties taking into account whether RepositoryItem or PropertiesClass is specified.  If neither of them is set, the method retrieves properties from the default editor applied for the item.


TcxFilterItem.Create

TcxFilterItem          See Also

Creates a new TcxFilterItem class instance.

constructor Create(Collection: TCollection); override;

Description

The Create method is used to create and initialize a new instance of the TcxFilterItem object.

The Collection parameter represents a collection object to which the newly created item belongs.  This collection object in its turn should be belonged to any filter control.


TcxFilterItem.Destroy

TcxFilterItem          See Also

Destroys the TcxFilterItem class instance.

destructor Destroy; override;

Description

The Destroy method is used to destroy the instance of the TcxFilterItem class and release any allocated memory.


TcxFilterItem.GetProperties

TcxFilterItem

Returns properties of an editor used to edit a comparison value of the current item.

function GetProperties: TcxCustomEditProperties;

Description

The GetProperties method returns the properties of the editor used to edit a value the current item’s data is compared to.  You can use the object returned by the GetProperties method to adjust specific settings of the value editor.

By default, a specific editor is assigned to the item’s comparison value based on the type of a field represented by the item.

You can redefine the default editor and specify it explicitly.  This allows you to adjust the editor’s properties at design time.  Use the RepositoryItem or the PropertiesClass property for this purpose.

The GetProperties method returns editor properties regardless of whether the default or an explicitly assigned editor is used.


TcxFilterItem.FieldName

TcxFilterItem          See Also

Specifies the name of a dataset field represented by an item.

property FieldName: string;

Description

Use the FieldName property to specify the name of the linked dataset’s field being referenced by a filter item.

Data aware filter controls are used to filter data of bound datasets.  A dataset object can be linked to a filter control via the DataSet property.  By default, all the dataset’s filterable fields can be involved in building and applying filter conditions, but you can specify a subset of fields to be available for filtering.  For this purpose, you should explicitly declare filter items in the Items collection.  These items will represent the required fields.  The FieldName property of an individual collection item should be set to the name of the corresponding field from the linked dataset.

Note: If any field of the linked dataset contains blanks within its name, a filter item for such a field should be declared explicitly and the FieldName property of the item should contain the corresponding field’s name enclosed in square brackets.


TcxFilterItemCollection
TcxFilterItemCollection Object

Hierarchy          Properties          See Also

In filter controls, represents a collection of dataset fields that are involved in building the filtering condition.

Unit

cxDBFilterControl

TcxFilterItemCollection = class(TOwnedCollection)

Description

Filter controls of the TcxDBFilterControl type use the TcxFilterItemCollection class to maintain a list of specific explicitly declared filter items.  Such items (if any is declared by you) represent dataset fields, which can be involved in building of filter conditions.

A collection of items is accessed via the Items property of a TcxDBFilterControl object.  Each item of the collection is represented by a TcxFilterItem object.  Use the collection’s Items property to access an individual collection item.


TcxFilterItemCollection Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxFilterItemCollection
TcxFilterItemCollection Properties

TcxFilterItemCollection          Legend

In TcxFilterItemCollection

Control

Items


TcxFilterItemCollection.Control

TcxFilterItemCollection

Represents a filter control owning the collection.

property Control: TcxCustomFilterControl;

Description

Use the Control property to obtain a filter control to which the items collection belongs.

ReadOnly Property


TcxFilterItemCollection.Items

TcxFilterItemCollection

Provides indexed access to collection items.

property Items[Index:Integer]: TcxFilterItem;

Description

Use the Items indexed property to access an individual collection item representing a linked dataset field whose data can be involved in filtering.  The collection of such items can be obtained via the Items property of the TcxDBFilterControl.

The accessed item’s index is specified by the Index parameter.  Items are zero-based indexed.  If the Index parameter value is negative or exceeds the maximum available index, an exception is raised.  The last available item index is always one less than the Count property value.


TcxFilterControlOperators
TcxFilterControlOperators type

TcxDBFilterOptions          See Also

Represents a set of comparison operators used in constructing filter conditions.

type

  TcxFilterControlOperator = (fcoNone, fcoEqual, fcoNotEqual, fcoLess, fcoLessEqual, fcoGreater, fcoGreaterEqual, fcoLike, fcoNotLike, fcoBlanks, fcoNonBlanks, fcoBetween, fcoNotBetween, fcoInList, fcoNotInList, fcoYesterday, fcoToday, fcoTomorrow, fcoLast7Days, fcoLastWeek, fcoLast14Days, fcoLastTwoWeeks, fcoLast30Days, fcoLastMonth, fcoLastYear, fcoInPast, fcoThisWeek, fcoThisMonth, fcoThisYear, fcoNext7Days, fcoNextWeek, fcoNext14Days, fcoNextTwoWeeks, fcoNext30Days, fcoNextMonth, fcoNextYear, fcoInFuture);

  TcxFilterControlOperators = set of TcxFilterControlOperator;

Description

The TcxFilterControlOperators type is a set of single operations, used to populate the dropdown list of comparison operators.  A simple filter condition consists of a single comparison operation.  The TcxFilterControlOperator type enumerates operators, which can be used in a simple filter condition.

The values contained in the set are described below:

Value	Meaning
fcoNone	No operator is specified for a filter condition.
fcoEqual	Operator ‘=’ Equal to
fcoNotEqual	Operator ‘<>’ Not equal to
fcoLess	Operator ‘<’ Less than
fcoLessEqual	Operator ‘<=’ Less than or equal to
fcoGreater	Operator ‘>’ Greater than
fcoGreaterEqual	Operator ‘>=’ Greater than or equal to
fcoLike	Operator ‘LIKE’ TRUE if the operand matches a pattern. With the LIKE operator you can use ‘%’ and ‘_’ wildcards.  The ‘%’ wildcard substitutes any number of characters.  The ‘_’ character is used to represent any single character.  You can assign other characters to be used as wildcards via the PercentWildcard and UnderscoreWildcard properties. For instance, the operator "LIKE 'Mc%' " returns TRUE for all strings that begin with the letters ‘Mc’ and contain any number of characters.
fcoNotLike	Operator ‘NOT LIKE’ TRUE if the operand does not match a pattern. See the description of the fcoLike value.
fcoBlanks	Checks whether the tested value is the NULL value (using the IS NULL or = NULL clauses) or an empty string value (using the =‘’ clause). Use the SoftNull property to specify whether empty strings are considered as NULL values or empty string values (‘’) when comparing.
fcoNonBlanks	Checks whether the tested value is not the NULL value (using the IS NOT NULL or <> NULL clauses) or an empty string value (using the <>‘’ clause). Use the SoftNull property to specify whether empty strings are considered as NULL values or empty string values (‘’) when comparing.
fcoBetween	Operator ‘BETWEEN’ TRUE if the operand is between two values inclusively.
fcoNotBetween	The negation of the ‘BETWEEN’ operator TRUE if the operand does not belong within a range.
fcoInList	The membership test operator. TRUE if the operand is in the list of specific values.
fcoNotInList	The negation of the fcoInList operator. TRUE if the operand is not a member of the value list.
fcoYesterday	Applied to date values. TRUE if the operand is equal to yesterday’s date.
fcoToday	Applied to date values. TRUE if the operand is equal to the current date.
fcoTomorrow	Applied to date values. TRUE if the operand is equal to tomorrow’s date.
fcoLast7Days	Applied to date values. TRUE if the operand falls within the last seven days.
fcoLastWeek	Applied to date values. TRUE if the operand falls within the previous week.
fcoLast14Days	Applied to date values. TRUE if the operand falls within the last fourteen days.
fcoLastTwoWeeks	Applied to date values. TRUE if the operand falls within the previous two weeks.
fcoLast30Days	Applied to date values. TRUE if the operand falls within the last thirty days.
fcoLastMonth	Applied to date values. TRUE if the operand falls within the previous month.
fcoLastYear	Applied to date values. TRUE if the operand falls within the previous year.
fcoInPast	Applied to date values. TRUE if the operand falls within the past dates.
fcoThisWeek	Applied to date values. TRUE if the operand falls within the current week.
fcoThisMonth	Applied to date values. TRUE if the operand falls within the current month.
fcoThisYear	Applied to date values. TRUE if the operand falls within the current year.
fcoNext7Days	Applied to date values. TRUE if the operand falls within the next seven days.
fcoNextWeek	Applied to date values. TRUE if the operand falls within the next week.
fcoNext14Days	Applied to date values. TRUE if the operand falls within the next fourteen days.
fcoNextTwoWeeks	Applied to date values. TRUE if the operand falls within the next two weeks.
fcoNext30Days	Applied to date values. TRUE if the operand falls within the next thirty days.
fcoNextMonth	Applied to date values. TRUE if the operand falls within the next month.
fcoNextYear	Applied to date values. TRUE if the operand falls within the next year.
fcoInFuture	Applied to date values. TRUE if the operand falls within the future dates.


cxFilterControlStrs Unit Overview
cxFilterControlStrs Unit

The cxFilterControlStrs unit stores resource strings that represent string constants for filter controls and filter dialogs.  Moving display strings into string resources makes an application easier to localize without rewriting the program.  For localization purposes, you might want to substitute values of specific resource strings.  To change a resource string value you can use the cxSetResourceString procedure available within the cxClasses unit.  This procedure substitutes the value of the resource string during execution only.  Refer to the Resource Strings topic for general information on resource strings.

The following table lists the resource strings used by filter controls.

Resource string name	Value	Description
cxSFilterAddCondition	'Add &Condition'	The caption for the menu item, used to add a simple filter condition in the Filter Building dialog.
cxSFilterAddGroup	'Add &Group'	The caption for the menu item, used to add a group of simple filter conditions in the Filter Building dialog.
cxSFilterBoolOperatorAnd	'AND'	Represents a Boolean AND operator in the Filter Building dialog. The operator is used to combine filter conditions in a group.
cxSFilterBoolOperatorNotAnd	'NOT AND'	Represents a Boolean NOT AND operator in the Filter Building dialog. The operator is used to combine filter conditions in a group.
cxSFilterBoolOperatorNotOr	'NOT OR'	Represents a Boolean NOT OR operator in the Filter Building dialog. The operator is used to combine filter conditions in a group.
cxSFilterBoolOperatorOr	'OR'	Represents a Boolean OR operator in the Filter Building dialog. The operator is used to combine filter conditions in a group.
cxSFilterClearAll	'Clear &All'	Specifies the caption for the menu item used to remove all filter conditions via the Filter Building dialog. To invoke the menu, click the right mouse button on the Filter box in this dialog.
cxSFilterControlDialogActionAp plyCaption	'&Apply'	The caption of the button used to apply filter conditions, set via the Filter Building dialog, to the current view.
cxSFilterControlDialogActionCa ncelCaption	'Cancel'	The caption of the button used to discard changes of filter criteria made by the Filter Building dialog.
cxSFilterControlDialogActionOk Caption	'Ok'	The caption of the button used to apply filter conditions, set via the Filter Building dialog, to the current view.  This button also closes the dialog.
cxSFilterControlDialogActionOp enCaption	'&Open...'	The caption of the button in the Filter Building dialog which activates the Open File dialog. Use this button to load the filter criteria, which were earlier saved to an external file.
cxSFilterControlDialogActionSav eCaption	'&Save As...'	The caption of the button in the Filter Building dialog which activates the Save As dialog. Use this button to save the current filter criteria to an external file.
cxSFilterControlDialogCaption	'Filter builder'	Specifies the caption for the Filter Building dialog.
cxSFilterControlDialogFileExt	'flt'	The default extension for the Open File and Save As dialogs used to load and save filter criteria via the Filter Building form.
cxSFilterControlDialogFileFilter	'Filters (*.flt)|*.flt'	Specifies the file masks (filters) for the Open File and Save As dialogs used to load and save filter criteria via the Filter Building form.
cxSFilterControlDialogNewFile	'untitled.flt'	The Filter Building dialog allows you to save the current filter criteria to an external file. The string specifies the default file name to save filter conditions to.
cxSFilterControlDialogOpenDial ogCaption	'Open an existing filter'	The title of the Open File dialog used to load the file with filter conditions into the Filter Building form.
cxSFilterControlDialogSaveDialo gCaption	'Save the active filter to file'	The title of the Save As dialog used to save the current filter criteria set via the Filter Building form to an external file.
cxSFilterControlNullString	'<empty>'	The string indicates that no value is set when creating a filter condition via the Filter Building dialog.
cxSFilterDialogCaption	'Custom Filter'	The title of the Custom Filter Dialog.
cxSFilterDialogCharactersSeries	'to represent any series of characters'	The string used to form a hint on using the LIKE operator via the Custom Filter dialog. The full string is formed by adding the PercentWildcard char and the cxSFilterDialogUse and cxSFilterDialogCharactersSeries strings.
cxSFilterDialogInvalidValue	'Invalid value'	The error message occurring when entering a value that cannot be accepted by a corresponding dataset field or view cell.
cxSFilterDialogOperationAnd	'AND'	The caption for the AND radio button in the Custom Filter dialog.
cxSFilterDialogOperationOr	'OR'	The caption for the OR radio button in the Custom Filter dialog.
cxSFilterDialogRows	'Show rows where:'	The caption for the static text displayed at the top of the Custom Filter dialog.
cxSFilterDialogSingleCharacter	'to represent any single character'	The string used to form a hint when using the LIKE operator via the Custom Filter dialog. The full string is formed by adding the UnderscoreWildcard char and the cxSFilterDialogUse and cxSFilterDialogSingleCharacter strings.
cxSFilterDialogUse	'Use'	The string used to form hints when using the LIKE operator via the Custom Filter dialog. It is used together with the cxSFilterDialogCharactersSeries and cxSFilterDialogSingleCharacter strings.
cxSFilterErrorBuilding	'Can''t build filter from source'	The error message is generated by the Filter Building dialog when filter criteria loaded from a file cannot be applied to the current view.  This can be the case when filter criteria refer to previously deleted columns. Note: A column in a file is referenced by its position within the view.
cxSFilterFooterAddCondition	'press button to add new condition'	Specifies the caption for the box in the Filter Building dialog used to add a new filter condition to filter criteria. This box is displayed under the last filter condition.
cxSFilterGroupCaption	'applies to the following conditions'	The string follows the Boolean operator combining filter conditions in the Filter Building dialog.
cxSFilterRemoveRow	'&Remove Row'	The caption for a menu item to remove the current filter condition.  The menu is accessible via the Filter Building dialog.
cxSFilterRootButtonCaption	'Filter'	The string displayed in the Filter box at the top of the Filter Building dialog.  Clicking the Filter box activates the popup menu, which allows you to add conditions or a group of conditions and remove the current filter criteria.
cxSFilterRootGroupCaption	'<root>'	Specifies the string displayed as static text within the Filter Building dialog. The string specifies the root list containing all filter conditions set via the dialog.


IcxFilterControl
IcxFilterControl Interface

Hierarchy          Properties             Methods

Represents an interface for objects that need to use the filter control functionality.

Unit

cxFilterControl

IcxFilterControl = interface(IUnknown)

Description

The IcxFilterControl interface declares properties and methods required for objects, that need to use the TcxFilterControl control.  This control is used to build and represent complex filtering conditions applied to the objects’ data.  Such objects should implement the declared properties and methods in order to support bidirectional filter data communication between them and a filter control.

The IcxFilterControl interface is implemented by the TcxGridTableView class of a grid control.

The TcxDBFilterControl control implements the IcxFilterControl interface itself.  The reason is that it operates on standard datasets that do not support this interface.


IcxFilterControl Hierarchy
Hierarchy

IUnknown

     |


Properties for IcxFilterControl
IcxFilterControl Properties

IcxFilterControl          Legend

In IcxFilterControl

Captions

Count

Criteria

FieldName

ItemLinks

ItemLinkNames

Properties


Methods for IcxFilterControl
IcxFilterControl Methods

IcxFilterControl          Legend

In IcxFilterControl

GetCaption

GetCount

GetCriteria

GetFieldName

GetItemLink

GetItemLinkName

GetProperties


IcxFilterControl.Captions

IcxFilterControl          See Also

Designed to get the caption of the specified filter item.

property Captions[Index: Integer]: string;

Description

When implemented, the Captions property should return the caption of a filter item specified by the Index parameter.  For instance, a grid table view object (the TcxGridTableView type) implements this property to obtain the caption of the specified filterable column.

The GetCaption method should be implemented to provide correct functioning of the Captions property.

ReadOnly Property


IcxFilterControl.Count

IcxFilterControl          See Also

Designed to get the number of filter items.

property Count: Integer;

Description

When implemented, the Count property should return the total number of filter items.  For instance, a grid table view object (the TcxGridTableView type) implements this property to obtain the number of all the columns available for filtering.

The GetCount method should be implemented to provide correct functioning of the Count property.

ReadOnly Property


IcxFilterControl.Criteria

IcxFilterControl          See Also

Designed to get the filter criteria applied to the object.

property Criteria: TcxFilterCriteria;

Description

When implemented, the Criteria property should return the TcxFilterCriteria object, which contains the current filter conditions applied to the object.  For instance, a grid table view object (the TcxGridTableView type) implements this property to obtain the value of the gird data controller’s Filter property.

The Criteria is the key property to be implemented by objects which intend to use the filter control functionality to build and apply filter conditions.  The GetCriteria method should be implemented to provide correct functioning of the Count property.

ReadOnly Property


IcxFilterControl.ItemLinks

IcxFilterControl          See Also

Returns a link to the specified filter item.

property ItemLinks[Index: Integer]: TObject;

Description

When implemented, the ItemLinks property should return an object representing a unique link to a filter item identified by the Index parameter.  The GetItemLink method should be implemented to provide the correct ItemLinks property operation.

To determine the name of a particular link, pass its index to the ItemLinkNames zero-based collection.

ReadOnly Property


IcxFilterControl.ItemLinkNames

IcxFilterControl          See Also

Returns the name of a link to the specified filter item.

property ItemLinkNames[Index: Integer]: string;

Description

When implemented, the ItemLinkNames property should return the name of a unique link to a filter item.  The filter item is specified by the Index parameter.

The GetItemLinkName method should be implemented to provide the correct ItemLinkNames property operation.

To access a particular link, pass its index to the ItemLinks zero-based collection.

ReadOnly Property


IcxFilterControl.FieldName

IcxFilterControl          See Also

Obtains the name of the dataset field to which the specified item refers.

property FieldName[Index: Integer]: string;

Description

When implemented, the FieldName property should return the name of a dataset field, which either becomes a filter item itself or is referred to by an explicitly declared filter item.  This property should be implemented by objects, which do not support filtering with the help of the filter criteria object and intend to use the data bound filter control functionality.

The GetFieldName method should be implemented to provide correct functioning of the FieldName property.  If the GetFieldName method returns the empty string, the filter control’s FilterText property will not contain the proper string representation of the defined filter conditions.

ReadOnly Property


IcxFilterControl.Properties

IcxFilterControl          See Also

Obtains the settings of the specified filter item’s editor.

property Properties[Index: Integer]: TcxCustomEditProperties;

Description

When implemented, the Properties property should obtain settings peculiar to an editor associated with the specified item.  The editor is used to display and edit a value to which the specified filter item’s data is compared.  The item whose editor settings are to be obtained is specified by its zero-based index via the Index parameter.

The GetProperties method should be implemented to provide correct functioning of the Properties property.

ReadOnly Property


IcxFilterControl.GetCaption

IcxFilterControl          See Also

Returns the Captions property value.

function GetCaption(Index: Integer): string;

Description

The GetCaption method is designed to be a ‘read’ method of the Captions property.  When implemented, it returns the caption of the specified filter item.  The index of the item is specified by the Index parameter.  Item indexing must be zero-based.


IcxFilterControl.GetCount

IcxFilterControl          See Also

Returns the Count property value.

function GetCount: Integer;

Description

The GetCount method is designed to be a ‘read’ method of the Count property.  When implemented, it returns the number of items (for instance columns or fields), which can be involved in filtering.


IcxFilterControl.GetCriteria

IcxFilterControl          See Also

Returns the Criteria property value.

function GetCriteria: TcxFilterCriteria;

Description

The GetCriteria method is designed to be a ‘read’ method of the Criteria property.  When implemented, it returns the filter criteria object containing the applied filter conditions.


IcxFilterControl.GetItemLink

IcxFilterControl          See Also

Returns the ItemLinks collection item.

function GetItemLink(Index: Integer): TObject;

Description

The GetItemLink method is designed to be a ‘read’ method of the ItemLinks collection.  When implemented, it returns an object representing a link to the specified filter item.  Filter items are identified by their zero-based indexes passed via the Index parameter.

For instance, the GetItemLink method implemented by a data-aware filter control (the TcxDBFilterControl type) returns either a filter item from the Items collection or a field from the bound dataset.

//Delphi

if FItems.Count > 0 then

  Result := FItems[Index]

else

  Result := GetField(Index)

As for a grid Table View (the TcxGridTableView type), it implements the GetItemLink method in a similar manner.

//Delphi

Result := TObject(FilterableColumns[Index].Index);

The ItemLinkNames property and the GetItemLinkName method provide access to unique names (string representations) that are used to distinguish item links created in the filter control.


IcxFilterControl.GetItemLinkName

IcxFilterControl          See Also

Returns the ItemLinkNames collection item.

function GetItemLinkName(Index: Integer): string;

Description

The GetItemLinkName method is designed to be a ‘read’ method of the ItemLinkNames collection.  When implemented, it returns a unique name of a link to the specified filter item.  Item links are identified by their zero-based indexes passed via the Index parameter.

For instance, the GetItemLinkName method implemented by a data-aware filter control (the TcxDBFilterControl type) returns the name of a dataset field bound to a specific filter item.

As for a grid Table View (the TcxGridTableView type), it implements the GetItemLinkName method to return a grid item’s name.

//Delphi

Result := FilterableItems[Index].Name;

The ItemLinks property and the GetItemLink method provide access to item links created in the filter control.


IcxFilterControl.GetFieldName

IcxFilterControl          See Also

Returns the FieldName property value.

function GetFieldName(Index: Integer): string;

Description

The GetFieldName method is designed to be a ‘read’ method of the FieldName property.  When implemented, it returns the name of a filter item specified by the Index parameter.  Item indexing must be zero-based.  The filter items are either the items declared explicitly or the data items (such as fields, columns) available for filtering.  For instance, a data bound filter control (the TcxDBFilterControl type) implements this method in the following way.  First, it checks from which object field names must be obtained.  If there are explicitly declared filter items in the Items property, it returns the value of the FieldName property of the specified filter item.  Otherwise, its return value is the name of the specified field from a dataset object linked to the filter control via the DataSet property.


IcxFilterControl.GetProperties

IcxFilterControl          See Also

Returns the Properties property value.

function GetProperties(Index: Integer): TcxCustomEditProperties;

Description

The GetProperties method is designed to be a ‘read’ method of the Properties property.  When implemented, it returns the properties of the specified editor associated with the item.  The item is specified by its zero-based index via the Index parameter.


Item Link

Item links are used in a filter control to uniquely identify filter items available for building and applying filter conditions.  This is required since an object linked to a filter control may contain several filter items (i.e. grid items) that reference the same data item (i.e. field).  So, there should be a unique correspondence between filter items used in the filter control and the linked object’s filter items.

For this purpose, the IcxFilterControl declares the ItemLinks and ItemLinkNames properties and the GetItemLink and GetItemLinkName methods, which execute the filter items’ unique identification.


Resource Strings

Strings displayed in various message boxes, dialogs and control elements of Express products are stored as resources.  This allows you to easily substitute them with custom strings depending on your needs (for instance, for localization purposes).

To replace the default value of a specific resource string during program execution, use the cxSetResourceString procedure.  This procedure works together with the cxGetResourceString function used by Express Controls.  When controls need a specific string to display, they call the cxGetResourceString function, which returns either the overridden string or the default one (if the string was not overridden).

Resource strings are declared in separate files for individual Express Products.  Use the links below to get information on resource strings available for specific products.  These sections provide resource string identifiers (required by cxSetResourceString) and default values:

Express DataController

Example

A date editor displays the Clear button in its dropdown.  The button’s string is addressed by the cxSDatePopupClear identifier.  The following code substitutes the caption of the button with its German equivalent:

//Delphi

cxSetResourceString(@cxSDatePopupClear, 'Löschen');

//C++ Builder

cxSetResourceString(&_cxSDatePopupClear, "Löschen");

This code changes the caption of the Clear button for all date editors in the current application.


ExpressDataController: Resource Strings

See Also

This section describes the resource strings used by the Express DataController in message boxes when errors occur.  Refer to the Resource Strings  topic for general information on them.  This section shows how to override the default values of resource strings at runtime.

The resource strings used by the Express DataController are declared in the cxDataConsts and cxFilterConsts units.

Unit cxDataConsts

Resource identifier	Value	Description
cxSDataCustomDataSourceIn validCompare	'GetInfoForCompare not implemented'	In provider mode, you are able to implement a faster comparison operation for values in a custom data source.  You need to override two methods: IsNativeCompare and GetInfoForCompare.  If the IsNativeCompare function returns True, but GetInfoForCompare is not implemented, a data controller generates the current error.
cxSDataItemIndexError	'ItemIndex out of range'	Specifies the error message which occurs when you pass an invalid item index in any data controller’s member. Valid item indexes belong to the range from 0 to DataController.ItemCount–1.
cxSDataRecordIndexError	'RecordIndex out of range'	The error message which occurs when a specific record index does not address any valid record in a data controller. Valid record indexes belong to the range from 0 to DataController.RecordCount–1.
cxSDataRowIndexError	'RowIndex out of range'	The error message which occurs when a specific row index does not address any valid record in a data controller. Valid row indexes belong to the range from 0 to DataController.RowCount–1.
cxSDBNotInGridMode	'DataController not in GridMode'	In default mode, (GridMode is disabled), using the DataController.GetSelectedBookmark function generates this error. Use the GetSelectedBookmark function to access selected records only in GridMode.  In default mode, see the view’s Controller.SelectedRecords property.

Unit cxFilterConsts

Resource identifier	Value	Description
cxSFilterAndCaption	'and'	Denotes the AND operator in the text string representing the current filter criteria in the Filter panel. To make the Filter panel visible, see the view’s Filtering.Visible property.
cxSFilterBlankCaption	'blank'	Used to represent NULL values in the Filter panel if the TcxFilterCriteria.Options property does not contain the fcoShowOperatorDescription flag. The Filter panel is designed to display the text representation of the current filter criteria.  To make the Filter panel visible, see the view’s Filtering.Visible property.
cxSFilterBoxAllCaption	'(All)'	Specifies the caption for the element in the filter dropdown list used to remove filter conditions set for a specific column.
cxSFilterBoxBlanksCaption	'(Blanks)'	If any column cell contains a NULL value, the column’s filter dropdown list displays the element represented by the cxSFilterBoxBlanksCaption string.  Selecting this element applies the following filter condition to data: ColumnValue = NULL See the TcxFilterValueList topic for more information. Note: empty strings are considered as NULL values if the fcoSoftNULL option is set to True.
cxSFilterBoxCustomCaption	'(Custom...)'	Specifies the caption for an element in the filter dropdown list.  Selecting this element activates the filter dialog, which allows you to visually specify filter criteria. See the Runtime Filtering section for more information.
cxSFilterBoxNonBlanksCapti on	'(NonBlanks)'	If any column cell contains a non-NULL value, the column’s filter dropdown list displays the element represented by the cxSFilterBoxNonBlanksCaption string.  Selecting this element applies the following filter condition to data: ColumnValue <> NULL See the TcxFilterValueList topic for more information. Note: empty strings are considered as NULL values if the fcoSoftNULL option is set to True.
cxSFilterNotCaption	'not'	Represents the NOT operator (as a part of the NOT OR and NOT AND Boolean operators) in the Filter panel.  See the TcxFilterBoolOperatorKind topic for the list of available Boolean operators. The Filter panel is designed to display the text representation of the current filter criteria. To make the Filter panel visible, see the view’s Filtering.Visible property.
cxSFilterOperatorBeginsWith	'begins with'	If an operand of the LIKE operator specifies the string ending with the PercentWildcard char (‘A%’, for instance), the operator in the Filter panel is represented by the cxSFilterOperatorBeginsWith string.  This representation is in effect if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. For the list of available filter operators, see the TcxFilterOperatorKind topic.
cxSFilterOperatorBetween	'between'	Represents the Between operator in the Filter Building dialog and Filter panel. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorContains	'contains'	If an operand of the LIKE operator specifies the string ending and starting with the PercentWildcard characters (‘%tax%’, for instance), the operator in the Filter panel is represented by the cxSFilterOperatorContains string.  This representation is in effect if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. For the list of available filter operators, see the TcxFilterOperatorKind topic.
cxSFilterOperatorDoesNotBe ginWith	'does not begin with'	If an operand of the NOT LIKE operator specifies the string ending with the PercentWildcard char (‘A%’, for instance), the operator in the Filter panel is represented by the cxSFilterOperatorDoesNotBeginWith string.  This representation is in effect if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. For the list of available filter operators, see the TcxFilterOperatorKind topic.
cxSFilterOperatorDoesNotCo ntain	'does not contain'	If an operand of the NOT LIKE operator specifies the string ending and starting with the PercentWildcard characters (‘%tax%’, for instance), the operator in the Filter panel is represented by the cxSFilterOperatorDoesNotContain string.  This representation is in effect if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. For the list of available filter operators, see the TcxFilterOperatorKind topic.
cxSFilterOperatorDoesNotEn dWith	'does not end with'	If an operand of the NOT LIKE operator specifies the string starting with the PercentWildcard char (‘%list’, for instance), the operator in the Filter panel is represented by the cxSFilterOperatorDoesNotEndWith string.  This representation is in effect if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. For the list of available filter operators, see the TcxFilterOperatorKind topic.
cxSFilterOperatorEndsWith	'ends with'	If an operand of the LIKE operator specifies the string starting with the PercentWildcard char (‘%list’, for instance), the operator in the Filter panel is represented by the cxSFilterOperatorEndsWith string.  This representation is in effect if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. For the list of available filter operators, see the TcxFilterOperatorKind topic.
cxSFilterOperatorEqual	'equals'	Represents the Equals operator in the Custom Filter and Filter Building dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorGreater	'is greater than'	Represents the ‘>’ operator in the Custom Filter and Filter Building dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorGreaterEqu al	'is greater than or equal to'	Represents the ‘>=’ operator in the Custom Filter and Filter Building dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorInFuture	'is in future'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorInList	'in'	Represents the membership test operator in the Filter Building dialog and Filter panel. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorInPast	'is in past'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorIsNotNull	'is not blank'	The Custom Filter and Filter Building dialogs allow you to create a filter condition of type: Item<>NULL Only records containing non-NULL values in this item are selected. The cxSFilterOperatorIsNotNull string represents the ‘<>NULL’ operator in these dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag.
cxSFilterOperatorIsNull	'is blank'	The Custom Filter and Filter Building dialogs allow you to create a filter condition of type: Item=NULL Only records containing NULL values in this item are selected. The cxSFilterOperatorIsNotNull string represents the ‘=NULL’ operator in these dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag.
cxSFilterOperatorLast7Days	'is last 7 days'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLast14Days	'is last 14 days'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLast30Days	'is last 30 days'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLastMonth	'is last month'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLastTwoWeeks	'is last two weeks'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLastWeek	'is last week'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLastYear	'is last year'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorLess	'is less than'	Represents the ‘<’ operator in the Custom Filter and Filter Building dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorLessEqual	'is less than or equal to'	Represents the ‘<=’ operator in the Custom Filter and Filter Building dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorLike	'like'	Represents the LIKE operator in the Custom Filter and Filter Building dialogs. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorNext7Days	'is next 7 days'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNext14Days	'is next 14 days'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNext30Days	'is next 30 days'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNextMonth	'is next month'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNextTwoWeeks	'is next two weeks'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNextWeek	'is next week'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNextYear	'is next year'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNotBetween	'not between'	Represents the NOT BETWEEN operator in the Filter Building dialog and Filter panel. The NOT BETWEEN operator allows you to select values beyond the specified range. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorNotEqual	'does not equal'	Represents the ‘<>’ operator in the Custom Filter and Filter Building dialogs. This string is also used to represent the operator in the Filter panel, if the TcxFilterCriteria.Options property contains the fcoShowOperatorDescription flag. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorNotInList	'not in'	Represents the NOT IN operator in the Filter Building dialog and Filter panel. The NOT IN operator is opposite to the IN operator which is used to test membership of an item in a value list. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorNotLike	'not like'	Represents the NOT LIKE operator in the Custom Filter and Filter Building dialogs. See the TcxFilterOperatorKind topic for the list of available operators.
cxSFilterOperatorThisMonth	'is this month'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorThisWeek	'is this week'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorThisYear	'is this year'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorToday	'is today'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorTomorrow	'is tomorrow'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOperatorYesterday	'is yesterday'	Represents the corresponding operator in the Filter Building dialog and Filter panel. This operator can be applied only to date values. See the TcxFilterOperatorKind topic for more information.
cxSFilterOrCaption	'or'	Denotes the OR operator in the text string representing the current filter criteria in the Filter panel. To make the Filter panel visible, see the view’s Filtering.Visible property.


Item

Data in a grid control is internally represented in a tabular form.  An item is associated with data from a specific table column.  In Table Views or Banded Table Views, an item represents a column.

In Card Views, items designate card rows.


Summary group

A summary group is an association of specific grouping items with group summaries.

The next scheme shows a summary group, which associates grouping items (Customer and OrderNo) with specific group summaries.

When records are grouped by any of these grouping items, the minimum value is calculated by the SaleDate item, the average value by the AmountPaid item and the sum of values in a group by the ItemsTotal item.


Group summary

A group summary is a type of summary calculated against records within a specific group.  You can calculate group summaries when data is grouped by any grouping item.

The following image demonstrates grouping by the EmpNo column. The AmountPaid, ItemsTotal and SaleDate columns calculate group summaries.  Summary values for the AmountPaid and SaleData items are displayed within the group footer panel, while the summary by the ItemsTotal column is displayed within the group caption panel.


Footer summary

A footer summary is calculated against all records within an entire grid control.

In the following image, two footer summaries are provided: the first displays the total number of records in the grid control; the second one displays the maximum value of the last column.


Level

Grid data is presented via levels.  If data is not grouped by any grouping item, it is displayed at level 0.  If you group data, nesting levels are created.  To display data at a specific level, you must click the [+] button.  Thus a level can be defined as a number of [+] buttons you need to click to reach the desired record.

If you group data by two grouping items, three levels are created.


Row Index

Row index identifies the position of a shown (expanded) row within a grid control.  There are two types of rows to be taken into account: data rows and group rows.  Data rows represent data from specific fields.  Group rows display information on a specific group within grid elements called group panels.  The following image shows row indexes in the grid control.  Note that the ‘RISC : MED’ node is collapsed and its underlying rows are not indexed.


Data Group

A data group represents a set of records combined by a certain condition.  Grouping grid data by items creates groups.  The following image displays data in the grid control grouped by two columns.  It demonstrates five data groups.  Each data group is addressed by its index, which specifies the position of this group.

Since you can group data by multiple items, data groups can have other data groups as children.  In the image above data group 2 has data groups 3 and 4 as children.  All data groups have parents.  Data group 1 belongs to data group 0, for instance.  Data groups 0 and 2 are displayed at level 0.  They also have a virtual parent data group whose index is –1.


Record Index

Data in the grid control is internally represented in a tabular form.  One coordinate specifies the record; the other specifies the item.  A record’s index is the integer number used to address it.  Record indexes are not changed due to sorting.  They always point to the same data.


Example TcxFilterCriteriaItemList.AddItem
Example TcxFilterCriteriaItemList.AddItem, TcxFilterCriteriaItemList.AddItemList, TcxFilterCriteria.Root, TcxFilterCriteria.BeginUpdate, TcxFilterCriteria.EndUpdate

The following example demonstrates how to set filter criteria for the following string:

(CustNo < 1000) AND ((Name LIKE ‘A%’) OR (Name LIKE ‘Z%’)).

The DBTableView1CustNo and DBTableView1Name objects are of the TcxGridDBColumn class.  They identify the desired items in a grid control.

To prevent filter criteria from being updated every time a filter condition is added, operations are enclosed within the TcxFilterCriteria.BeginUpdate and TcxFilterCriteria.EndUpdate methods.

//Delphi

var

  AItemList: TcxFilterCriteriaItemList;

//...

  FDataController.Filter.BeginUpdate;

  try

    FDataController.Filter.Root.Clear;

    FDataController.Filter.Root.AddItem(DBTableView1CustNo, foLess, 1000, '1000');

    AItemList := FDataController.Filter.Root.AddItemList(fboOr);

    AItemList.AddItem(DBTableView1Name, foLike, 'A%', 'A%');

    AItemList.AddItem(DBTableView1Name, foLike, 'Z%', 'Z%');

  finally

    FDataController.Filter.EndUpdate;

  end;

//C++ Builder

  FDataController->Filter->BeginUpdate();

  try {

    FDataController->Filter->Root->Clear();

    FDataController->Filter->Root->AddItem(DBTableView1CustNo, foLess, 1000, "1000");

    TcxFilterCriteriaItemList *AItemList := FDataController->Filter->Root->AddItemList(fboOr);

    AItemList->AddItem(DBTableView1Name, foLike, "A%", "A%");

    AItemList->AddItem(DBTableView1Name, foLike, "Z%", "Z%");

  } __finally {

    FDataController->Filter->EndUpdate();

  }


Example TcxDataFilterCriteria.OnGetValueList
Example TcxDataFilterCriteria.OnGetValueList, TcxFilterValueList.FindItemByValue, TcxFilterValueList.FindItemByKind, TcxFilterValueList.Add, TcxFilterValueList.Delete

See also

The following code lists the TcxDataFilterCriteria.OnGetValueList event handler, which customizes a list of values for a filter condition.  In the event handler, two elements are deleted from the list for the DBTableView1EmpNo column.  The first element is of the fviValue type and represents the value 2.  The second element is of the fviCustom type.  Also a new user-defined item is inserted into the value list for the DBTableView1SaleDate column.

//Delphi

procedure TForm1.DBTableView1DataControllerFilterGetValueList(

  Sender: TcxFilterCriteria; AItemIndex: Integer;

  AValueList: TcxDataFilterValueList);

var

  AIndex: Integer;

begin

//change the value list for the DBTableView1EmpNo column

  if AItemIndex = DBTableView1EmpNo.Index then

  begin

    //delete item 2 from the value list

    AIndex := AValueList.FindItemByValue(2);

    if AIndex <> -1 then

      AValueList.Delete(AIndex);

    //delete item of the fviCustom kind from the value list

    AIndex := AValueList.FindItemByKind(fviCustom);

    if AIndex <> -1 then

      AValueList.Delete(AIndex);

  end;

  //add user-defined item to the value list for the
  //DBTableView1SaleDate column

  if AItemIndex = DBTableView1SaleDate.Index then

    AValueList.Add(fviUser, '', 'Filter TODAY', True);

end;

//C++ Builder

procedure TForm1::DBTableView1DataControllerFilterGetValueList(

  TcxFilterCriteria *Sender, int AItemIndex,

  TcxDataFilterValueList *AValueList);

begin

//change the value list for the DBTableView1EmpNo column

  if (AItemIndex == DBTableView1EmpNo->Index) {

    //delete item 2 from the value list

    int AIndex = AValueList->FindItemByValue(2);

    if (AIndex != -1) {

      AValueList->Delete(AIndex);

    }

    //delete item of the fviCustom kind from the value list

    AIndex = AValueList->FindItemByKind(fviCustom);

    if (AIndex != -1) {

      AValueList->Delete(AIndex);

    }

  }

  //add user-defined item to the value list for the
  //DBTableView1SaleDate column

  if (AItemIndex == DBTableView1SaleDate->Index) then

    AValueList->Add(fviUser, "", "Filter TODAY", true);

end;


Example TcxFilterCriteria.PercentWildcard

The next example creates a new filter criterion which limits data values.  Only values that begin with the ‘Mc’ sub-string are accepted.  The PercentWildcard property is set to ‘*’ for demonstrative purposes only.

//Delphi

  FDataController.Filter.PercentWildcard := '*';

  FDataController.Filter.BeginUpdate;

  try

    FDataController.Filter.Root.Clear;

    FDataController.Filter.Root.AddItem(DBTableView1Customer,
      foLike, 'Mc*', 'Mc...');

  finally

    FDataController.Filter.EndUpdate;

  end;

//C++ Builder

  FDataController->Filter->PercentWildcard = "*";

  FDataController->Filter->BeginUpdate();

  try {

    FDataController->Filter->Root->Clear();

    FDataController->Filter->Root->AddItem(DBTableView1Customer,
      foLike, "Mc*", "Mc...");

  } __finally {

    FDataController->Filter->EndUpdate();

  }


Example TcxFilterCriteria.UnderscoreWildcard

The next example demonstrates how to add a filter condition to limit values.  Only values that consist of exactly four characters and contain the ‘an’ sub-string in the middle of the word are accepted.  The first and last letters are undefined.  Words that have any symbols in these positions and contain the ‘an’ substring are selected by this criterion.  The UnderscoreWildcard property is set to ‘?’ for demonstrative purposes only.

//Delphi

  FDataController.Filter.UnderscoreWildcard := '?';

  FDataController.Filter.BeginUpdate;

  try

    FDataController.Filter.Root.Clear;

    FDataController.Filter.Root.AddItem(DBTableView1Customer, foLike,
      '?an?', '.an.');

  finally

    FDataController.Filter.EndUpdate;

  end;

//C++ Builder

  FDataController->Filter->UnderscoreWildcard = "?";

  FDataController->Filter->BeginUpdate();

  try {

    FDataController->Filter->Root->Clear();

    FDataController->Filter->Root->AddItem(DBTableView1Customer, foLike,"?an?', ".an.");

  } __finally {

    FDataController->Filter->EndUpdate();

  }


Example TcxDBDataFilterCriteria.OnBeforeChange

In this example the TcxDBDataFilterCriteria.OnBeforeChange event is used to change the filter for the object of the TQuery class from which data is retrieved.

The first two rows of the query specify:

SELECT *

FROM ORDERS.DB

In this event, the WHERE clause is added.  AFilterText describes a condition to apply.

//Delphi

procedure TForm1.DBTableView1DataControllerFilterBeforeChange(

  Sender: TcxDBDataFilterCriteria; ADataSet: TDataSet;

  const AFilterText: String);

begin

  with Query1 do

  begin

    DisableControls;

    try

      Active := False;

      if AFilterText <> '' then

        //add condition to the query

        SQL[2] := 'WHERE ' + AFilterText;

      else

        SQL[2] := '';

      Active := True;

    finally

      EnableControls;

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::DBTableView1DataControllerFilterBeforeChange(

  TcxDBDataFilterCriteria *Sender, TDataSet *ADataSet,

  const AnsiString AFilterText) {

  Query1->DisableControls();

  try {

    Query1->Active = false;

    if (AFilterText != "") {

      //add condition to the query

      Query1->SQL[2] = "WHERE " + AFilterText;

    } else {

      Query1->SQL[2] = "";

    }

    Query1->Active = true;

  } __finally {

    Query1->EnableControls();

  }

}


Example TcxDataSummaryItems.OnSummary
Example1 TcxDataSummaryItems.OnSummary

By default, summary calculations involve all elements.  In this example a summary representing the number of non-NULL item elements is evaluated.  To modify the default summary calculation, you should write the TcxDataSummaryItems.OnSummary event.  The Done flag indicates whether the value should be ignored.  See the Create summaries topic to learn how to set summaries for a grid control.

//Delphi

procedure TForm1.cxGrid1DBTableView1TcxGridDBDataControllerTcxDataSummary
DefaultGroupSummaryItemsSummary(
  ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;
  var OutArguments: TcxSummaryEventOutArguments);

begin

  if (VarIsNull(OutArguments.Value)) then

    OutArguments.Done := True;

end;

//C++ Builder

void __fastcall TForm1::cxGrid1DBTableView1TcxGridDBDataControllerTcxDataSummary
DefaultGroupSummaryItemsSummary(

  TcxDataSummaryItems *ASender, TcxSummaryEventArguments &Arguments,

  TcxSummaryEventOutArguments &OutArguments) {

  if (VarIsNull(OutArguments.Value)) {

    OutArguments.Done = true;

  }

}


Example2 TcxDataSummaryItems.OnSummary

A summary calculation involves iteration of item elements within a group and evaluation of a specific number (the number of item elements, sum, the maximum value etc.).  It is possible to substitute an element value when calculating a summary.

Let us suppose that you have a table which represents information on the country population and area.  To calculate the maximum density of population within a group of records you can use a summary of the skMax type and write the TcxDataSummaryItems.OnSummary event as follows.  See the Create summaries topic regarding how to set summaries for a grid control.

//Delphi

procedure TForm1.cxGrid1DBTableView1TcxGridDBDataControllerTcxDataSummary
DefaultGroupSummaryItemsSummary(
  ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;
  var OutArguments: TcxSummaryEventOutArguments);

var

  AArea, APopulation: Extended;

begin

  //Locate a value in the specific record for Area item

  AArea := ASender.DataController.Values[Arguments.RecordIndex, DBTableView1Area.Index];

  //Locate a value in the specific record for Population item

  APopulation := ASender.DataController.Values[Arguments.RecordIndex, DBTableView1Population.Index];

  //Set population density to Value

  OutArguments.Value := APopulation / AArea;

end;

//C++ Builder

void __fastcall TForm1::cxGrid1DBTableView1TcxGridDBDataControllerTcxDataSummary
DefaultGroupSummaryItemsSummary(

  TcxDataSummaryItems *ASender, TcxSummaryEventArguments &Arguments,

  TcxSummaryEventOutArguments &OutArguments) {

  //Locate a value in the specific record for Area item

  long double AArea = double(ASender->DataController->Values[Arguments.RecordIndex][0]);

  //Locate a value in the specific record for Population item

  long double APopulation = double(ASender->DataController->Values[Arguments.RecordIndex][0]);

  //Set population density to Value

  OutArguments.Value = double(APopulation / AArea);

end;


Example TcxDataSummary.OnAfterSummary
Example TcxDataSummary.OnAfterSummary, TcxCustomDataController.Groups

In this example, a summary value is calculated based on the results of other two summaries.  The TcxDataSummary.OnAfterSummary event, which occurs when all summaries are already calculated, is used to calculate a new summary.

Let us examine a table that represents information from the pricelist containing three columns: VendorNo, Description, ListPrice.  We want to group data by vendor and calculate three summaries: the summary that displays a sum of the ListPrice column values, the summary representing the number of goods supplied by a specific vendor and the summary that displays the average value of the ListPrice column values.  Though it is possible to create an average summary by specifying its skAverage type, we will calculate it based on two other summary values and format it in a specific manner.

The Initialize procedure groups data by vendor and creates three summaries.  The third summary is of the skNone type.  It is substituted for the average summary in MyAfterSummary (the OnAfterSummary event handler).

//Delphi

procedure TForm1.Initialize;

var

  ASummaryItem: TcxDataSummaryItem;

begin

  //group by vendor

  DBTableView1VendorNo.GroupIndex := 0;

  DBTableView1VendorNo.Visible := False;

  with DBTableView1.DataController.Summary do

  begin

    BeginUpdate;

    try

      //set prefix and postfix for a group capion

      DefaultGroupSummaryItems.BeginText := '{';

      DefaultGroupSummaryItems.EndText := '}';

      //summary on ListPrice

      ASummaryItem := DefaultGroupSummaryItems.Add;

      ASummaryItem.Kind := skSum;

      ASummaryItem.ItemLink := DBTableView1ListPrice;

      ASummaryItem.Position := spFooter;

      //summary on Description

      ASummaryItem := DefaultGroupSummaryItems.Add;

      ASummaryItem.Kind := skCount;

      ASummaryItem.ItemLink := DBTableView1Description;

      ASummaryItem.Position := spFooter;

      //dummy summary on Description

      ASummaryItem := DefaultGroupSummaryItems.Add;

      ASummaryItem.Kind := skNone;

      ASummaryItem.ItemLink := DBTableView1Description;

      //subscribe to the OnAfterSummary event

      OnAfterSummary := MyAfterSummary;

    finally

      EndUpdate;

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::Initialize() {

  //group by vendor

  DBTableView1VendorNo->GroupIndex = 0;

  DBTableView1VendorNo->Visible = False;

  TcxDataSummary *summary = DBTableView1->DataController->Summary;

  summary->BeginUpdate();

  try {

    //set prefix and postfix for a group capion

    summary->DefaultGroupSummaryItems->BeginText = '{';

    summary->DefaultGroupSummaryItems->EndText = '}';

    //summary on ListPrice

    summary->ASummaryItem := DefaultGroupSummaryItems->Add();

    summary->ASummaryItem->Kind = skSum;

    summary->ASummaryItem->ItemLink = DBTableView1ListPrice;

    summary->ASummaryItem->Position = spFooter;

    //summary on Description

    summary->ASummaryItem = DefaultGroupSummaryItems->Add();

    summary->ASummaryItem->Kind = skCount;

    summary->ASummaryItem->ItemLink = DBTableView1Description;

    summary->ASummaryItem->Position = spFooter;

    //dummy summary on Description

    summary->ASummaryItem = DefaultGroupSummaryItems->Add();

    summary->ASummaryItem->Kind = skNone;

    summary->ASummaryItem->ItemLink = DBTableView1Description;

    //subscribe to the OnAfterSummary event

    summary->OnAfterSummary = MyAfterSummary;

  } __finally {

    summary->EndUpdate();

  }

}

The MyAfterSummary method is a TcxDataSummary.OnAfterSummary event handler.  As data is only grouped by one column, we need to iterate the data groups only at level 0.  The TcxCustomDataController.Groups property allows you to determine data group indexes which are required by the TcxDataSummary.GroupSummaryValues property.  The CalculateGroupAverage procedure evaluates the average price for every data group.  The output string for the average summary is constructed by the Format method.

//Delphi

procedure TForm1.MyAfterSummary(ASender: TcxDataSummary);

var

  AChildDataGroupsCount: Integer;

  AChildDataGroupIndex, AParentDataGroupIndex: TcxDataGroupIndex;

  AChildPosition: Integer;

begin

  //iterate through data groups at the level 0

  AParentDataGroupIndex := -1;

  with DBTableView1.DataController.Groups do

  begin

    AChildDataGroupsCount := ChildCount[AParentDataGroupIndex];

    for AChildPosition := 0 to AChildDataGroupsCount - 1 do

    begin

      //data group index of a child

      AChildDataGroupIndex := ChildDataGroupIndex[AParentDataGroupIndex, AChildPosition];

      CalculateGroupAverage(AChildDataGroupIndex);

    end;

  end;

end;

procedure TForm1.CalculateGroupAverage(ADataGroupIndex: TcxDataGroupIndex);

var

  AVarSum, AVarCount, AVarAverage: Variant;

begin

  with DBTableView1.DataController.Summary do

  begin

    //get sum of prices for specific data group

    //the second argument identifies a summary index in the

    //TcxDataSummary.DefaultGroupSummaryItems collection

    AVarSum := GroupSummaryValues[ADataGroupIndex, 0];

    //get records count in a group

    AVarCount := GroupSummaryValues[ADataGroupIndex, 1];

    if not (VarIsNull(AVarSum) or VarIsNull(AVarCount)) then

    begin

      AVarAverage := AVarSum / AVarCount;

      GroupSummaryValues[ADataGroupIndex, 2] := Format('%m / %d = %m', [Double(AVarSum), Integer(AVarCount), Double(AVarAverage)]);

    end;

  end;

end;

//C++ Builder

void __fascall TForm1::MyAfterSummary(TcxDataSummary *ASender);

var

  AChildDataGroupsCount: Integer;

  AChildDataGroupIndex;

  AChildPosition: Integer;

begin

  //iterate through data groups at the level 0

  TcxDataGroupIndex AParentDataGroupIndex = -1;

  TcxDataControllerGroups *groups = DBTableView1->DataController->Groups;

  int AChildDataGroupsCount := groups->ChildCount[AParentDataGroupIndex];

    for (int AChildPosition = 0; AChildPosition < AChildDataGroupsCount; AChildPosition++) {

      //data group index of a child

      AChildDataGroupIndex = groups->ChildDataGroupIndex[AParentDataGroupIndex][AChildPosition];

      CalculateGroupAverage(AChildDataGroupIndex);

    }

  }

}

void __fascall TForm1::CalculateGroupAverage(TcxDataGroupIndex ADataGroupIndex) {

  TcxDataSummary *summary = DBTableView1->DataController->Summary;

  //get sum of prices for specific data group

  //the second argument identifies a summary index in the

  //TcxDataSummary.DefaultGroupSummaryItems collection

  Variant AVarSum = summary->GroupSummaryValues[ADataGroupIndex][0];

  //get records count in a group

  Variant AVarCount = summary->GroupSummaryValues[ADataGroupIndex][1];

  if (!(VarIsNull(AVarSum) || VarIsNull(AVarCount))) {

    Variant AVarAverage = AVarSum / AVarCount;

    TVarRec values[] = {(double)AVarSum, (int)AVarCount, (double)AVarCount};

    Format("%m / %d = %m", values, ARRAYSIZE(values) - 1);

  }

}

The following image demonstrates a grid control after executing the Initialize method.


Example TcxCustomDataController.OnCompare

Suppose you want to change the sorting rules for a specific column representing date/time information.  You have to write an OnCompare event handler to perform this.

The SaleDate column contains values of the TDateTime type.  The following code groups records with the same month in the SaleDate column.  Grouping is applied only when grid data is sorted by this column.  Otherwise, values are compared by the VarCompare function which is implemented in the cxVariants module.

//Delphi

procedure TForm1::MyOnCompareEventHandler(ADataController: TcxCustomDataController; ARecordIndex1, ARecordIndex2, AItemIndex: Integer; const V1, V2: Variant; var Compare: Integer);

var

  AYear, AMonth1, AMonth2, ADay: Word;

begin

  //apply custom sorting only for the SaleDate column

  if (AItemIndex = DBTableView1SaleDate.Index) and

    (VarType(V1) = VarType(V2)) and (VarType(V1) = varDate) then

  begin

    DecodeDate(V1, AYear, AMonth1, ADay);

    DecodeDate(V2, AYear, AMonth2, ADay);

    //group records with the same month

    Compare := AMonth1 - AMonth2;

  end

  else

    //compare values in other columns

    Compare := VarCompare(V1, V2);

end;

//C++ Builder

void __fascall TForm1::MyOnCompareEventHandler(TcxCustomDataController *ADataController, int ARecordIndex1, int ARecordIndex2, int AItemIndex, const Variant &V1, const Variant &V2, int &Compare);

  //apply custom sorting only for the SaleDate column

  if ((AItemIndex == DBTableView1SaleDate->Index) && (VarType(V1) == VarType(V2)) && (VarType(V1) == varDate)) {

    int AYear, AMonth1, AMonth2, ADay;

    DecodeDate(V1, AYear, AMonth1, ADay);

    DecodeDate(V2, AYear, AMonth2, ADay);

    //group records with the same month

    Compare = AMonth1 - AMonth2;

  } else {

    //compare values in other columns

    Compare = VarCompare(V1, V2);

  }


Example TcxCustomDataController.OnCompare 2
Example TcxCustomDataController.OnCompare

In this example, the TcxCustomDataController.OnCompare event is used to group records so that NULL values sort at the bottom of the grid control.  The Compare parameter is set to zero if both values are NULL.  If both values are not equal to NULL, they are compared by the VarCompare function declared in the cxVariants unit.  Otherwise, a value corresponding to the current sorting order by a specified item is assigned to Compare.  The current sorting order is defined via the TcxCustomDataController.GetItemSortOrder method.  Compare is always set so that NULL values are placed at the bottom.

//Delphi

procedure TForm1.MyCompare1(ADataController: TcxCustomDataController; ARecordIndex1, ARecordIndex2, AItemIndex: Integer; const V1, V2: Variant; var Compare: Integer);

const

  SortValueA: array [Boolean] of Integer = (-1, 1);

begin

  if VarType(V1) = varNull then

  begin

    if VarType(V2) = varNull then

      Compare := 0

    else

      Compare := SortValueA[ADataController.GetItemSortOrder(AItemIndex) = soAscending];

  end

  else

    if VarType(V2) = varNull then

      Compare := SortValueA[ADataController.GetItemSortOrder(AItemIndex) = soDescending]

    else

      Compare := VarCompare(V1, V2);

end;

//C++ Builder

void __fastcall TForm1::MyCompare1(TcxCustomDataController *ADataController, int ARecordIndex1, int ARecordIndex2, int AItemIndex, const Variant &V1, const Variant &V2, int &Compare);

  const int SortValueA[2] = {-1, 1};

  if (VarType(V1) == varNull) {

    if (VarType(V2) == varNull) {

      Compare = 0;

    } else {

      Compare = SortValueA[ADataController->GetItemSortOrder(AItemIndex) == Cxcustomdata::soAscending];

    }

  } else {

    if (VarType(V2) == varNull) {

      Compare = SortValueA[ADataController->GetItemSortOrder(AItemIndex) == Cxcustomdata::soDescending];

    } else {

      Compare = VarCompare(V1, V2);

    }

  }

}


Example TcxDBDataModeController.OnDetailIsCurrentQuery

The implementation of the TcxDBDataModeController.OnDetailIsCurrentQuery event is demonstrated in this example.  In this event True is returned if the corresponding parameterized query should not be reopened.  If the query should be reopened, False is returned.

If the query defines the required data (the query parameter specifies the same value as a detail key field value), it is not reopened.

//Delphi

function TForm1.DBTableView1DataControllerDataModeControllerDetailIsCurrentQuery(

  Sender: TcxDBDataModeController; ADataSet: TDataSet;

  const AMasterDetailKeyFieldNames: string;

  const AMasterDetailKeyValues: Variant): Boolean;

begin

  with (ADataSet as TQuery) do

    Result := ParamByName('CustNo').Value = AMasterDetailKeyValues;

end;

//C++ Builder

bool __fastcall TForm1::cxGrid1DBTableView1DataControllerDataModeControllerDetailIsCurrentQuery(

  TcxDBDataModeController *Sender, TDataSet *ADataSet,

  const AnsiString AMasterDetailKeyFieldNames,

  const Variant &AMasterDetailKeyValues) {

  return ((TQuery *)ADataSet)->ParamByName("CustNo")->Value == AMasterDetailKeyValues;

}


Example TcxDBDataModeController.OnDetailFirst

The TcxDBDataModeController.OnDetailFirst event handler is listed in the next example.  It does not reopen the underlying query if it already contains the required data (the query parameter value is the same as the value of the detail key field name passed via the AMasterDetailKeyValues argument).  In this case the current record is only positioned to the first record in the query dataset.

Otherwise the query with a new parameter value is reopened by setting the Active property to True.  The AReopened parameter is set to True in this case.

//Delphi

procedure TForm1.DBTableView1DataControllerDataModeControllerDetailFirst(

  Sender: TcxDBDataModeController; ADataSet: TDataSet;

  const AMasterDetailKeyFieldNames: String;

  const AMasterDetailKeyValues: Variant; var AReopened: Boolean);

begin

  with (ADataSet as TQuery) do

  begin

    if ParamByName('CustNo').Value = AMasterDetailKeyValues then

    begin

      First;

      Exit;

    end;

    DisableControls;

    try

      Active := False;

      ParamByName(AMasterDetailKeyFieldNames).Value := AMasterDetailKeyValues;

      Active := True;

    finally

      EnableControls;

    end;

    AReopened := True;

  end;

end;

//C++ Builder

void __fastcall TForm1::cxGrid1DBTableView1DataControllerDataModeControllerDetailFirst(

      TcxDBDataModeController *Sender, TDataSet *ADataSet,

      const AnsiString AMasterDetailKeyFieldNames,

      const Variant &AMasterDetailKeyValues, bool &AReopened)

{

  TQuery *query = (TQuery *)ADataSet;

  if (query->ParamByName("CustNo")->Value == AMasterDetailKeyValues) {

    query->First();

    return;

  }

  query->DisableControls();

  try {

    query->Active = false;

    query->ParamByName(AMasterDetailKeyFieldNames)->Value = AMasterDetailKeyValues;

    query->Active = true;

  } __finally {

    query->EnableControls();

  }

  AReopened = true;

}


Example: TcxCustomDataSource.AppendRecord, TcxCustomDataSource.InsertRecord

Assume that you implement a custom data source from an external TStringList object (FStringList).  The AppendRecord method should add a new string at the end of the list.  The InsertRecord method should insert a new item in this list at the position specified by the ARecordHandle parameter by moving all following items to the end of the list.  Both AppendRecord and InsertRecord should return the index of the new item as a record handle and call the DataChanged method.  For information on record handles, see the TcxCustomDataSource topic.

//Delphi

type

  TUserDataSource = class(TcxCustomDataSource)

  private

    FStringList: TStringList;

  protected

    //...

    function AppendRecord: Pointer; override;

    function InsertRecord(ARecordHandle: Pointer): Pointer; override;

  end;

implementation

//...

function TUserDataSource.AppendRecord: Pointer;

begin

  Result := Pointer(FStringList.Add(''));

  DataChanged;

end;

function TUserDataSource.InsertRecord(ARecordHandle: Pointer): Pointer;

begin

  FStringList.Insert(Integer(ARecordHandle), '');

  Result := ARecordHandle;

  DataChanged;

end;

//C++ Builder

class TUserDataSource: public TcxCustomDataSource {

  private:

    TStringList * FStringList;

  protected:

    //...

    virtual void * __fastcall AppendRecord(void);

    virtual void * __fastcall InsertRecord(void * ARecordHandle);

};

//...

void * __fastcall TUserDataSource::AppendRecord(void) {

  int res = FStringList->Add("");

  DataChanged();

  return (void*)res;

}

void * __fastcall TUserDataSource::InsertRecord(void * ARecordHandle) {

  FStringList->Insert((int)ARecordHandle, "");

  DataChanged();

  return ARecordHandle;

}


Example: Changing selected records in provider and unbound modes

The following example shows how to access selected records in provider and unbound modes.

The total number of selected rows (data records and grouping rows) is determined by the DataController.GetSelectedCount function.  To iterate selected rows in unbound and provider modes, the data controller’s GetSelectedRowIndex method must be used.  It returns the row index of a specific selected row that can be used to retrieve information on the row using the GetRowInfo function.

Suppose that records of the data controller are displayed within a tvOrders view of the ExpressQuantumGrid4 control.  The following code shows how to change the tvOrdersSaleDate column values of selected records to the current date.

//Delphi

var

  I: Integer;

  ARowIndex: Integer;

  ARowInfo: TcxRowInfo;

begin

  with tvOrders.DataController do

  begin

    BeginUpdate;

    try

      for I := 0 to GetSelectedCount - 1 do

      begin

        ARowIndex := GetSelectedRowIndex(I);

        ARowInfo := GetRowInfo(ARowIndex);

        //Test whether a row is a grouping row

        if ARowInfo.Level < Groups.GroupingItemCount then

          Continue

        else

          //unbound or provider mode

          Values[ARowInfo.RecordIndex, tvOrdersSaleDate.Index] := Now();

      end;

    finally

      EndUpdate;

    end;

  end;

end;

//C++ Builder

  TcxCustomDataController * dc = tvOrders->DataController;

  int ARowIndex;

  TcxRowInfo ARowInfo;

  dc->BeginUpdate();

  try {

    for (int I = 0; I < dc->GetSelectedCount(); I++) {

      ARowIndex = dc->GetSelectedRowIndex(I);

      ARowInfo = dc->GetRowInfo(ARowIndex);

      //Test whether a row is a grouping row

      if (ARowInfo.Level <
          dc->Groups->GroupingItemCount)

        continue;

      else

        dc->Values[ARowInfo.RecordIndex]
          [tvOrdersSaleDate->Index] = Now();

    }

  }

  __finally {

    dc->EndUpdate();

  }

The following code demonstrates another approach to access selected records.  The data controller provides the ForEachRow method to call a custom procedure (a callback function) automatically for each row.  This method is overridden by the TcxDBDataController class, so you can use it in all loading modes (provider, unbound, bound and GridMode).

The first parameter defines whether selected or all rows should be processed.  The custom procedure to be called for each row, is passed as the second parameter of ForEachRow.

To use the ForEachRow method, you have to write a procedure with a specific prototype (see the method’s description).  This procedure should perform operations on a row.  In our example, it changes the tvOrdersSaleDate column value:

//Delphi

procedure TForm1.SetSaleDate(ARowIndex: Integer; ARowInfo: TcxRowInfo);

begin

  with tvOrders.DataController do

  begin

    //Test whether a row is a data record

    if ARowInfo.Level = Groups.GroupingItemCount then

      //unbound or provider mode

      Values[ARowInfo.RecordIndex, tvOrdersSaleDate.Index] := Now();

  end;

end;

//C++ Builder

void __fastcall TForm1::SetSaleDate(int ARowIndex, const TcxRowInfo &ARowInfo) {

  TcxCustomDataController * dc = tvOrders->DataController;

  //Test whether a row is a data record

  if (ARowInfo.Level == dc->Groups->GroupingItemCount)

    //unbound or provider mode

    dc->Values[ARowInfo.RecordIndex][tvOrdersSaleDate->Index] = Now();

}

The code that calls the SetSaleDate method for each row is shown below:

//Delphi

  with tvOrders.DataController do

  begin

    BeginUpdate;

    try

      ForEachRow(True, SetSaleDate);

    finally

      EndUpdate;

    end;

  end;

//C++ Builder

  TcxCustomDataController * ADataController =
    tvOrders->DataController;

  ADataController->BeginUpdate();

  try {

    ADataController->ForEachRow(True, SetSaleDate);

  }

  __finally {

    ADataController->EndUpdate();

  }


Example: TcxDBDataController.GetSelectedBookmark

This example shows how you can iterate selected records in GridMode.  In this mode, a data controller loads only a fixed amount of records from a dataset into memory at a time thus providing better performance with huge datasets (data grouping is not supported in Grid Mode).  If you group data, grid mode is automatically disabled and the data controller will load all records from the underlying dataset to enable data grouping.  To test whether grid mode is currently enabled, the IsGridMode function can be used.

In Grid mode, the data controller automatically creates a bookmark (a TBookmarkStr object) for every selected record.  You can retrieve these bookmarks via the GetSelectedBookmark function and then use them to make a particular dataset record active with the help of the TDataSet.Bookmark property.  The number of selected records is determined by the GetSelectedCount function.

The following code shows how to access selected records displayed by a tvUsers view in the ExpressQuantumGrid4 control.  The dataset displayed by the view contains an EMail field.  For every selected record, an e-mail is sent to the address specified by the EMail field.

//Delphi

procedure TForm1.SpeedButton1Click(Sender: TObject);

var

  I: Integer;

  AEmail, ATextToSend, ASubject: string;

begin

  ATextToSend := 'Message text';

  ASubject := 'Subject';

  with tvUsers.DataController do

  begin

    if not IsGridMode then

    begin

      ShowMessage('Grid mode is disabled');

      Exit;

    end;

    BeginUpdate;

    try

      for I := 0 to GetSelectedCount - 1 do

      begin

        //Grid mode

        DataSet.Bookmark := GetSelectedBookmark(I);

        AEmail := DataSet.FieldValues['EMail'];

        SendEmail(AEmail, ASubject, ATextToSend);

      end;

    finally

      EndUpdate;

    end;

  end;

end;

procedure SendEmail(AEmail, ASubject, ATextToSend: string);

begin

  //...

end;

//C++ Builder

void __fastcall TForm1::SpeedButton1Click(TObject *Sender) {

  String ATextToSend = "Message text";

  String ASubject = "Subject";

  String AEmail;

  TcxDBDataController * dc = tvUsers->DataController;

  if (!dc->IsGridMode()) {

    ShowMessage("Grid mode is disabled");

    return;

  }

  dc->BeginUpdate();

  try {

    for (int I = 0; I < dc->GetSelectedCount(); I++) {

      //Grid mode

      dc->DataSet->Bookmark = dc->GetSelectedBookmark(I);

      AEmail = dc->DataSet->FieldValues["EMail"];

      SendEmail(AEmail, ASubject, ATextToSend);

    }

  }

  __finally {

    dc->EndUpdate();

  }

}

void SendEmail(String AEmail, String ASubject, String ATextToSend) {

  //...

}


Example: TcxCustomDataController.FilteredRecordCount, TcxCustomDataController.FilteredRecordIndex

The number of records that satisfy the applied filter criteria can be obtained via the FilteredRecordCount property.

The following example iterates filtered records in a tvUsers view of the ExpressQuantumGrid4 control and stores values of their key fields in a list.  A key field is a unique field used to identify a dataset record.

After that, filtered records can be accessed by their key field values via the data controller’s LocateByKey or the dataset’s Locate methods.  These methods make a particular record active, thus allowing you to change its field values.

The key field in the current example is identified by the ID field.  To retrieve the ID field value, a filtered record is activated using the FocusedRecordIndex property.  This property identifies the record index of the focused record.  See the FocusedRecordIndex property for more information.

The record index of a specific filtered record is determined by the FilteredRecordIndex property.

//Delphi

var

  I: Integer;

  AKeyFieldValueList: TList;

//...

  with tvUsers.DataController do

  begin

    //Select records with tvUsersCITY column values

    //equal to 'Los Angeles'

    Filter.Clear;

    Filter.Root.AddItem(tvUsersCITY, foEqual, 'Los Angeles',
      'Los Angeles');

    Filter.Active := True;

    AKeyFieldValueList := TList.Create;

    BeginUpdate;

    try

      //Copy key field values of filtered records to the list

      for I := 0 to FilteredRecordCount - 1 do

      begin

        FocusedRecordIndex := FilteredRecordIndex[I];

        AKeyFieldValueList.Add(Pointer(Integer(
          DataSet.FieldValues['ID'])));

      end;

      //do some operation on filtered records using key field values

      //...

    finally

      EndUpdate;

      AKeyFieldValueList.Free;

    end;

  end;

//C++ Builder

  TList * AKeyFieldValueList = new TList;

  TcxDBDataController * dc = tvUsers->DataController;

  //Select records with tvUsersCITY column values

  //equal to 'Los Angeles'

  dc->Filter->Clear();

  dc->Filter->Root->AddItem(tvUsersCITY, foEqual, "Los Angeles",

    "Los Angeles");

  dc->Filter->Active = true;

  dc->BeginUpdate();

  try {

    //Copy key field values of filtered records to the list

    for (int I = 0; I < dc->FilteredRecordCount; I++) {

      dc->FocusedRecordIndex = dc->FilteredRecordIndex[I];

      AKeyFieldValueList->Add(
        (void*)(int)dc->DataSet->FieldValues["ID"]);

    }

    //do some operation on filtered records using key field values

    //...

  }

    __finally {

      dc->EndUpdate();

      delete AKeyFieldValueList;

    }


Example: Changing selected records in bound mode

In bound mode, the data controller (TcxDBDataController) represents data from a TDataSet object.  The data controller does not provide methods to change values of specific record fields in bound mode.  You have to use your dataset’s methods or delayed updates to modify values.

The first approach can be used when you need to modify values of a single record.  You can move the cursor to a dataset record and then change field values using the TDataSet.FieldValues property, for instance.  When synchronization between the data controller and the dataset is enabled, the focused record identified by the FocusedRecordIndex property corresponds to the active dataset record.  So you can use FocusedRecordIndex to move the dataset’s cursor to a specific record.

Changing value(s) of specific field(s) can hide the current dataset record (if filtering is enabled) or change the record position.  This leads to reloading data by the data controller and clearing the selection, if any.

A safer approach to modify selected records is to use delayed updates.  The idea is to store the key field values of selected records and use them later to locate and modify the records.

As a rule, a dataset contains key field(s), which can be used to uniquely identify any dataset record.

Key field values can be obtained by using the GetRecordID function.  In order to use this function, you should assign the key field name(s) (OrderNo, in this example) to the data controller’s KeyFieldNames property.

The following example shows how to modify the SaleDate field values of selected records in a tvOrders view of the ExpressQuantumGrid4 control.  This view displays data from the Orders.db table installed with the BDE.

First, key field values of selected records are stored in a list (FKeyFieldList) by the GetSelectedKeyValues procedure.  To iterate selected records, the ForEachRow method is used.  This enables you to call a custom procedure for each selected row  (in this example, the AddKeyFieldValueToList procedure is called).  The first parameter of ForEachRow specifies whether all or only selected rows should be processed.

Now every selected record is identified by a corresponding value in FKeyFieldList.  For every selected record we need to create a query with an UPDATE command to will change the SaleDate field:

UPDATE Orders SET SaleDate = :SaleDate WHERE OrderNo = :OrderNo'

This updates the Orders table by setting a new value to the SaleDate field of the record(s) with the particular OrderNo value.  The OrderNo and SaleDate field values are set via the query’s Params property.

After all the required records are changed, the dataset’s Refresh method is called in order to notify the data controller that data has changed and should be reloaded.

The main method, called to change selected records, is named Button1Click.

//Delphi

var

  FKeyFieldList: TList;

  FDataController: TcxDBDataController;

//...

procedure TForm1.Button1Click(Sender: TObject);

var

  AQuery: TQuery;

  I: Integer;

begin

  AQuery := TQuery.Create(Self);

  FKeyFieldList := TList.Create();

  try

    GetSelectedKeyValues(tvOrders.DataController);

    AQuery.ParamCheck := True;

    AQuery.DatabaseName := 'DBDEMOS';

    AQuery.SQL.Text := 'UPDATE Orders SET SaleDate = :SaleDate WHERE OrderNo = :OrderNo';

    //Set value for the SaleDate field

    AQuery.Params.ParamByName('SaleDate').Value := Now();

    //Iterate selected records

    for I := 0 to FKeyFieldList.Count - 1 do

    begin

      //Set value for the OrderNo field

      AQuery.Params.FindParam('OrderNo').Value :=
        Variant(Integer(FKeyFieldList[I]));

      //Execute the query

      AQuery.ExecSQL;

    end;

  finally

    FKeyFieldList.Free;

    AQuery.Free;

    tvOrders.DataController.DataSet.Refresh;

  end;

end;

procedure TForm1.GetSelectedKeyValues(ADataController: TcxDBDataController);

begin

  FDataController := ADataController;

  ADataController.ForEachRow(True, AddKeyFieldValueToList);

end;

procedure TForm1.AddKeyFieldValueToList(ARowIndex: Integer;

  ARowInfo: TcxRowInfo);

var

  AKeyFieldValue: Variant;

begin

  with FDataController do

  begin

    //test whether a row is a data record

    if ARowInfo.Level = Groups.GroupingItemCount then

    begin

      AKeyFieldValue := GetRecordId(ARowInfo.RecordIndex);

      FKeyFieldList.Add(Pointer(Integer(AKeyFieldValue)));

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::Button1Click(TObject *Sender) {

  TQuery * AQuery = new TQuery(this);

  FKeyFieldList = new TList();

  try {

    GetSelectedKeyValues(tvOrders->DataController);

    AQuery->ParamCheck = true;

    AQuery->DatabaseName = "DBDEMOS";

    AQuery->SQL->Text = "UPDATE Orders SET SaleDate = :SaleDate WHERE OrderNo = :OrderNo";

    //Set value for the SaleDate field

    AQuery->Params->ParamByName("SaleDate")->Value = Now();

    //Iterate selected records

    for (int I = 0; I < FKeyFieldList->Count; I++) {

      //Set value for the OrderNo field

      AQuery->Params->FindParam("OrderNo")->Value =

        Variant(Integer(FKeyFieldList->Items[I]));

      //Execute the query

      AQuery->ExecSQL();

    }

  } __finally {

    delete FKeyFieldList;

    delete AQuery;

    tvOrders->DataController->DataSet->Refresh();

  }

}

void __fastcall TForm1::GetSelectedKeyValues(TcxDBDataController * ADataController) {

  FDataController = ADataController;

  ADataController->ForEachRow(true, AddKeyFieldValueToList);

}

void __fastcall TForm1::AddKeyFieldValueToList(int ARowIndex, const TcxRowInfo &ARowInfo) {

  //test whether a row is a data record

  if (ARowInfo.Level == FDataController->Groups->GroupingItemCount) {

    int AKeyFieldValue =
      FDataController->GetRecordId(ARowInfo.RecordIndex);

    FKeyFieldList->Add((void*)AKeyFieldValue);

  }

}


Example: TcxCustomDataController.BeginLocate, TcxCustomDataController.EndLocate

The following code searches the record containing a specific value of the EmpNo field in the dataset displayed by a tvEmployee view of ExpressQuantumGrid4.  The TDataSet.Locate method used for searching is enclosed by the BeginLocate and EndLocate methods.  It prevents the data controller from the full data reloading which usually occurs when using Locate.

//Delphi

  AValue: Integer;

//...

  AValue := 71;

  with tvEmployee.DataController do

  begin

    BeginLocate;

    try

      DataSet.Locate('EmpNo', AValue, []);

    finally

      EndLocate;

    end;

  end;

//C++ Builder

  int AValue = 71;

  TcxDBDataController * dc = tvEmployee->DataController;

  dc->BeginLocate();

  try {

    dc->DataSet->Locate("EmpNo", AValue, TLocateOptions());

  } __finally {

    dc->EndLocate();

  }


Example: TcxCustomDataController.SaveToStream, TcxCustomDataController.LoadFromStream

The SaveToStream and LoadFromStream methods provided by a data controller enable you to save and restore data in unbound loading mode.

The following example shows how to save information and restore it from a file for the tvPlanets view in ExpressQuantumGrid4.

//Delphi

var

  AStream: TStream;

//...

//Saving data to a file

  AStream := TFileStream.Create('e:\stream.txt', fmCreate);

  try

    tvPlanets.DataController.SaveToStream(AStream);

  finally

    AStream.Free;

  end;

//...

//Loading data from the file

  AStream := TFileStream.Create('e:\stream.txt', fmOpenRead);

  try

    tvPlanets.DataController.LoadFromStream(AStream);

  finally

    AStream.Free;

  end;

//C++ Builder

  TStream * AStream = new TFileStream("e:\\stream.txt", fmCreate);

//Saving data to a file

  try {

    tvPlanets->DataController->SaveToStream(AStream);

  } __finally {

    delete AStream;

  }

//...

//Loading data from the file

  AStream = new TFileStream("e:\\stream.txt", fmOpenRead);

  try {

    tvPlanets->DataController->LoadFromStream(AStream);

  } __finally {

    delete AStream;

  }


Example: using the foBetween filter operator

This example shows you how to create a filter condition with the BETWEEN operator.  The BETWEEN operator requires two values identifying an inclusive range.  These two values must be combined into an array of variants and this is performed by the VarBetweenArrayCreate function implemented in the cxVariants unit.

To add a filter condition, use the AddItem method of the data controller’s Filter object.  The new filter condition is applied to the cxGrid1DBTableView1PurchaseDate column of the cxGrid1DBTableView1 view.

//Delphi

var

  d1, d2: TDateTime;

//...

  d1 := EncodeDate(2000, 01, 01);

  d2 := EncodeDate(2000, 01, 03);

  cxGrid1DBTableView1.DataController.Filter.AddItem(nil,
    cxGrid1DBTableView1PurchaseDate,  foBetween,
    VarBetweenArrayCreate(d1, d2),
    DateToStr(d1) + ';' + DateToStr(d2));

//C++ Builder

  TDateTime d1, d2;

  d1 = EncodeDate(2000, 01, 01);

  d2 = EncodeDate(2000, 01, 03);

  cxGrid1DBTableView1->DataController->Filter->AddItem(NULL,
    cxGrid1DBTableView1PurchaseDate, foBetween,
    VarBetweenArrayCreate(d1, d2),
    DateToStr(d1) + ";" + DateToStr(d2));


Example: using the foInList filter operator

In this example, the foInList filter operator is applied to the cxGrid1DBTableView1ID column.  The operator allows you to select records by testing the membership of a field value within a specific list (array of variants).  The value list is created by the VarArrayCreate function.

//Delphi

var

  V: Variant;

const

  ID1 = 1; ID2 = 2; ID3 = 3;

//...

  V := VarArrayCreate([0, 2], varVariant);

  V[0] := ID1;

  V[1] := ID2;

  V[2] := ID3;

  cxGrid1DBTableView1.DataController.Filter.AddItem(nil, cxGrid1DBTableView1ID, foInList, V, '(1, 2, 3)');

//C++ Builder

  const ID1 = 1, ID2 = 2, ID3 = 3;

  int Bounds[2] = {0, 2};

  Variant V = VarArrayCreate(Bounds, 1, varVariant);

  V.PutElement(ID1, 0);

  V.PutElement(ID2, 1);

  V.PutElement(ID3, 2);

  cxGrid1DBTableView1->DataController->Filter->AddItem(NULL, cxGrid1DBTableView1ID, foInList, V, "(1, 2, 3)");


Example: using the foYesterday filter operator

This example demonstrates the application of the foYesterday filter operator.  To add the filter condition, use the AddItem method of the data controller’s Filter object.  This requires the comparison operator, comparison value and text representation of the value be supplied.  When using the foYesterday filter operator, the comparison value and its text representation are ignored.

//Delphi

cxGrid1DBTableView1.DataController.Filter.AddItem(nil,
  cxGrid1DBTableView1PurchaseDate, foYesterday, NULL, '');

//C++ Builder

cxGrid1DBTableView1->DataController->Filter->AddItem(NULL,
  cxGrid1DBTableView1PurchaseDate, foYesterday, NULL, "");


Example: using the foEqual filter operator

To create a simple filter condition with the foEqual operator, you can use the AddItem method of the data controller’s Filter object.  In the following example, a filter condition is applied to the cxGrid1DBTableView1ID column of the cxGrid1DBTableView1 view.  This selects records with the ID field equal to 101:

//Delphi

var

  ID: Integer;

  Str: string;

//...

  ID := 101;

  Str := IntToStr(ID);

  cxGrid1DBTableView1.DataController.Filter.AddItem(nil,
    cxGrid1DBTableView1ID, foEqual, ID, Str);

//C++ Builder

  int ID = 101;

  String Str = IntToStr(ID);

  cxGrid1DBTableView1->DataController->Filter->AddItem(NULL,
    cxGrid1DBTableView1ID, foEqual, ID, Str);


Legend

 Protected

 Published

 ReadOnly


cxData Unit Overview
cxData Unit

Classes

TcxDataController


TcxDataController
TcxDataController Object

Hierarchy          Properties          Methods          Events          See Also

Represents the data controller which manages data from a data storage.

Unit

cxData

TcxDataController = class(TcxCustomDataController);

Description

A data controller is an object which provides access to data in a data storage thus enabling you to perform operations on it.  TcxDataController implements working in unbound mode and is required for the internal infrastructure.  It inherits all the functionality of the TcxCustomDataController class and this introduces methods to retrieve data from the user-defined data source provided by the TcxCustomDataSource class descendant; it allows the applying of a set of filter conditions, the calculation of summaries and grouping.


TcxDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |


Properties for TcxDataController
TcxDataController Properties

TcxDataController          Legend

Derived from TcxCustomDataController

CustomDataSource

DisplayTexts

EditOperations

EditState

Filter

FilteredIndexByRecordIndex

FilteredRecordCount

FilteredRecordIndex

FocusedRecordIndex

FocusedRowIndex

Groups

IsEditing

IsPattern

MultiSelect

Options

RecordCount

RowCount

Search

Summary

Values


Methods for TcxDataController
TcxDataController Methods

TcxDataController          Legend

Derived from TcxCustomDataController

 Append

 AppendRecord

 BeginFullUpdate

 BeginUpdate

 BeginUpdateFields

 Cancel

 ChangeDetailExpanding

 ChangeRowSelection

 CheckFocusedSelected

 ClearBookmark

 ClearDetailLinkObject

 ClearDetails

 ClearSelection

 ClearSorting

 CollapseDetails

 DeleteFocused

 DeleteRecord

 DeleteSelection

 Edit

 EndUpdateFields

 EndFullUpdate

 EndUpdate

 FindRecordIndexByText

 ForEachRow

 FocusDetails

 GetDetailDataController

 GetMasterDataController

 GetMasterRecordIndex

 GetPatternDataController

 GetRowDisplayText

 GetRowIndexByRecordIndex

 GetRowInfo

 GetRowValue

 GetSelectedCount

 GetSelectedRowIndex

 GotoBookmark

 GotoFirst

 GotoLast

 GotoNext

 GotoPrev

 Insert

 InsertRecord

 IsBOF

 IsBookmarkAvailable

 IsDetailMode

 IsEOF

 IsGridMode

 IsRowSelected

 LoadFromStream

 MakeRecordVisible

 Post

 RefreshExternalData

 SaveBookmark

 SaveToStream

 SelectAll

 SelectRows

 SetEditValue

 SetValue

 SyncSelected


Events for TcxDataController
TcxDataController Events

TcxDataController          Legend

Derived from TcxCustomDataController

 OnAfterCancel

 OnAfterDelete

 OnAfterInsert

 OnAfterPost

 OnBeforeCancel

 OnBeforeDelete

 OnBeforeInsert

 OnBeforePost

 OnCompare

 OnDataChanged

 OnDetailCollapsed

 OnDetailCollapsing

 OnDetailExpanded

 OnDetailExpanding

 OnFilterRecord

 OnGroupingChanged

 OnNewRecord

 OnRecordChanged

 OnSortingChanged


cxDataStorage Unit Overview
cxDataStorage Unit

Classes

TcxValueType

Other Types

TcxValueTypeClass


TcxValueType
TcxValueType Object

Hierarchy          See Also

Specifies the type of item values.

Unit

cxDataStorage

type

  TcxValueType = class(TObject);

  TcxValueTypeClass = class of TcxValueType;

Description

TcxValueType represents the base class specifying the type of item values.  Items are assigned particular types for the following purposes:

•	performing compare operations for this type value

•	checking the validity of some value

•	determining the size of data this type presents and getting/setting a value at a specific memory offset

•	writing and reading a value to and from a stream

There are value type classes inherited from TcxValueType that correspond to most of TField types:

TField type	TcxValueType descendant
ftBCD, ftCurrency	TcxCurrencyValueType
ftBoolean	TcxBooleanValueType
ftDate, ftTime, ftDateTime	TcxDateTimeValueType
ftFloat	TcxFloatValueType
ftFMTBcd	TcxFMTBcdValueType
ftInteger	TcxIntegerValueType
ftLargeint	TcxLargeIntValueType
ftString	TcxStringValueType
ftWideString	TcxWideStringValueType
ftWord	TcxWordValueType
Other field types	TcxVariantValueType

Also the TcxSmallintValueType and TcxSQLTimeStampValueType classes are provided to present the SmallInt and TSQLTimeStamp types.

In bound mode, items are assigned types automatically according to the table listed above.  In unbound and provider mode you need to specify the item type explicitly by setting the item’s DataBinding.ValueTypeClass property.  You should set DataBinding.ValueTypeClass to the class which matches the type of values an item stores.  For graphical fields, you may use TcxStringValueType.

In unbound mode, ValueTypeClass specifies the default editor assigned to an item.

ValueTypeClass	Default editor
TcxBooleanValueType	TcxCheckBox
TcxCurrencyValueType	TcxCurrencyEdit
TcxDateTimeValueType	TcxDateEdit
TcxFMTBcdValueType	TcxCurrencyEdit
TcxSQLTimeStampValueType	TcxDateEdit

For items with ValueTypeClass set to another value, a simple text editor (TcxTextEdit) is used.

Note:	The TcxObjectValueType class can be used to store a non-visual object that represents arbitrary data for an unbound item.  It is not recommended that you use visual objects for this purpose, since this can raise exceptions when destroying the form that contains these objects.

In bound mode, the default editor is determined by the field type.  See the FieldName property topic for details.


TcxValueType Hierarchy
Hierarchy

TObject

     |


TcxDataControllerSearch
TcxDataControllerSearch Object

Hierarchy          Properties          Methods

Provides methods enabling you to perform incremental searching programmatically.

Unit

cxCustomData

TcxDataControllerSearch = class(TObject)

Description

Most Developer Express controls support the incremental search feature that allows end-users to locate records by typing the desired field values.  Each control has its own set of options controlling whether incremental search feature is available.  At the same time, the options set is similar for all controls and includes an option at the control’s level allowing you to prohibit incremental searching for the entire control and options at the level of objects representing dataset fields that allow you to prohibit incremental searching for particular fields.  (Note, that the control’s level is the grid view’s level if using the ExpressQuantumGrid.)

Regardless of the options described, you can perform incremental searching programmatically, if needed.  This allows you to provide greater control over the searching process.  For instance, you may skip found records that don’t satisfy to your custom conditions, etc.  To provide programmatic incremental searching, use the TcxDataControllerSearch object’s methods.  This object can be accessed via the Search property of your control’s data controller.

The main methods you will use are the Locate, LocateNext and Cancel.  These methods allow you to start searching, locate the next record satisfying to the search text and cancel searching respectively.

Note: some controls do not support incremental searching performed via the TcxDataControllerSearch object due to complex data representation structures.  An example of such a control is a tree list.  This control provides its own methods that enable programmatic incremental searching.


TcxDataControllerSearch Hierarchy
Hierarchy

TObject

     |


Properties for TcxDataControllerSearch
TcxDataControllerSearch Properties

TcxDataControllerSearch          Legend

In TcxDataControllerSearch

ItemIndex

Locked

Searching

SearchText


Methods for TcxDataControllerSearch
TcxDataControllerSearch Methods

TcxDataControllerSearch          Legend

In TcxDataControllerSearch

Cancel

Create

Locate

LocateNext

Lock

Unlock


TcxDataControllerSearch.ItemIndex

TcxDataControllerSearch

Specifies the index of the field where incremental searching is to be performed.

property ItemIndex: Integer;

Description

This property is for internal use only.  Do not use it in applications.  The field where to search is specified by a Locate method’s parameter.


TcxDataControllerSearch.Locked

TcxDataControllerSearch

Determines whether the incremental search controller is locked.

property Locked: Boolean;

Description

This property is for internal use only.  Do not use it in applications.

ReadOnly Property


TcxDataControllerSearch.Searching

TcxDataControllerSearch

Returns a value indicating whether incremental searching is being performed.

property Searching: Boolean;

Description

Read the Searching property value to determine whether incremental searching is in progress.  This property returns True regardless of whether incremental searching has been initiated by an end user or via code.

ReadOnly Property


TcxDataControllerSearch.SearchText

TcxDataControllerSearch

Returns the current incremental search string.

property SearchText: string;

Description

Use the SearchText property to determine which text an end user has typed since the incremental search has been initiated.  Note that only the characters that had a match in the target field’s values are included into the string.  So the SearchText property value always matches the start of a target field’s value.  If incremental searching is not in progress, the SearchText property returns an empty string.

ReadOnly Property


TcxDataControllerSearch.Cancel

TcxDataControllerSearch

Cancels incremental searching.

procedure Cancel;

Description

Use the Cancel method to stop incremental searching being performed at the moment.  This method’s effect is equivalent to pressing the Esc key when incremental searching is in progress.  This results in resetting the search string and leaving the focus on the last found record.


TcxDataControllerSearch.Create

TcxDataControllerSearch

Creates a new instance of the TcxDataControllerSearch class.

constructor Create(ADataController: TcxCustomDataController);

Description

You do not need to create TcxDataControllerSearch instances manually.  Data controller objects automatically create such objects to initialize their Search property.  When a data controller calls the TcxDataControllerSearch object’s constructor it passes itself as the ADataController parameter, which specifies the owner data controller instance.


TcxDataControllerSearch.Locate

TcxDataControllerSearch

Locates the first record whose field contains the specified sub-string at the beginning.

function Locate(AItemIndex: Integer; const ASubText: string): Boolean;

Description

Use the Locate method to start incremental searching.  This method’s AItemIndex property specifies the index of the field where to search.  The ASubText parameter sets the search string.  The Locate method searches starting from the current record downwards until the search text matches the beginning of the specified field’s value.  If a match exists, the focus moves to the found record and the search text is highlighted.  The Locate method returns True in this case.  If the method scans all records and no match is found, False is returned.  Note that if the last record is reaches with no matches, the search is continued from the first record until the start record is reached.

Use the LocateNext method to search the next/previous match for the specified search string.


TcxDataControllerSearch.LocateNext

TcxDataControllerSearch

Locates the next or previous record matching the search criteria specified by the Locate method.

function LocateNext(AForward: Boolean): Boolean;

Description

Use the LocateNext method to continue incremental searching that has been initiated using the Locate method.  The search direction is specified by the AForward parameter.  If the parameter value is True, the method searches for a match starting from the current record downwards.  Otherwise, the upward search is performed.  If the LocateNext method finds a match until the last or first record is reached, the found record becomes focused and the method returns True.  Otherwise, the method returns False and the focus remains unchanged.


TcxDataControllerSearch.Lock

TcxDataControllerSearch

Locks the search controller.

procedure Lock;

Description

This method is for internal use only.  You have no need to use it in applications.


TcxDataControllerSearch.Unlock

TcxDataControllerSearch

Unlocks the search controller.

procedure Unlock;

Description

This method is for internal use only.  You have no need to use it in applications.


cxDBFilterControl Unit Overview
cxDBFilterControl Unit

Classes

TcxDBFilterControl

TcxDBFilterOptions

TcxFilterItem

TcxFilterItemCollection


TcxDBFilterControl
 TcxDBFilterControl Object

Hierarchy          Properties          Methods          Events          See Also

Represents a filter control operating on TDataSet descendants.

Unit

cxDBFilterControl

TcxDBFilterControl = class(TcxCustomFilterControl, IcxFilterControl)

Description

Use the TcxDBFilterControl to facilitate managing filter operations for end users when filtering should be performed by means of a dataset.  The TcxDBFilterControl allows end users to visually construct complex filter criteria by combining simple filter conditions for individual items (fields in the linked dataset) using logical operators.  The TcxDBFilterControl automatically processes the specified filter conditions and generates the value for the FilterText property.  You can use this value to programmatically apply filtering to the linked dataset object.

The TcxCustomFilterControl class implements the basic functionality of a data-bound filter control.  The TcxDBFilterControl class introduces several properties and overrides some methods used for managing dataset filter operations.

A dataset to be filtered is specified by the DataSet property.  You can use the Items property to designate particular dataset fields to be available for constructing filter conditions.

If you don’t need to filter data by means of a dataset, you can use the TcxFilterControl instead.  This control links to an object supporting the IcxFilterControl interface (typically, a grid table view) and allows users to manage filtering of such an object by building specific filter conditions.


TcxDBFilterControl Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomFilterControl

     |


Properties for TcxDBFilterControl
TcxDBFilterControl Properties

TcxDBFilterControl          Legend

In TcxDBFilterControl

DataSet

FilterOptions

Items

Derived from TcxCustomFilterControl

Color

Criteria

FilterLink

FilterText

FontBoolOperator

FontCondition

FontItem

FontValue

NullString

ShowLevelLines

SortItems

WantTabs

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxDBFilterControl
TcxDBFilterControl Methods

TcxDBFilterControl          Legend

In TcxDBFilterControl

Create

Destroy

GetFilterTextEx

GetPropertiesClassFromFieldType

Derived from TcxCustomFilterControl

ApplyFilter

BuildFromCriteria

Clear

LoadFromFile

LoadFromStream

Localize

SaveToFile

SaveToStream

Derived from TcxControl

InvalidateRect


Events for TcxDBFilterControl
TcxDBFilterControl Events

TcxDBFilterControl          Legend

Derived from TcxCustomFilterControl

OnApplyFilter


TcxDBFilterControl.DataSet

TcxDBFilterControl

Specifies a dataset object to which filter conditions should be applied.

property DataSet: TDataSet;

Description

Use the DataSet property to specify a TDataSet-derived object, which should be filtered based upon filter conditions defined in a filter control.

A dataset object linked to the data aware filter control via the DataSet property exposes all its filterable fields to be available for filtering.  End users can select from the list of these fields when visually constructing an individual filter condition.  You can use the Items property to specify fields to participate in building filter conditions.  The FieldName property of each Items collection’s member should be set to the name of a field from the linked dataset.


TcxDBFilterControl.FilterOptions

TcxDBFilterControl          See Also

Provides access to filter options.

property FilterOptions: TcxDBFilterOptions;

Description

Use the FilterOptions property to gain access to the different filter options represented by the TcxDBFilterOptions class.  These options set specific conditions for controlling filtering and the display of filter text.


TcxDBFilterControl.Items

TcxDBFilterControl

Specifies the collection of fields involved in filtering.

property Items: TcxFilterItemCollection;

Description

The Items property represents a collection of items referring to specific dataset fields, which can be involved in composing filter conditions in a filter control.  You can use the Items property to explicitly declare items in the collection and link them to the desired fields.

By default the collection is empty.  In this case, all the fields of the linked dataset can participate in filtering.  The bound dataset is specified by the DataSet property.

When the Items collection is not empty and its members refer to fields from the linked dataset (via the FieldName property), only specified items (represented by the Caption property values) will be displayed in the dropdown list of items to which filtering can be applied.

Additionally, you can use either the mechanism of a repository and repository items (RepositoryItem) or the PropertiesClass and Properties objects to assign an editor to an item.  The assigned editor will be used to edit the value to which the item is compared.


TcxDBFilterControl.Create

TcxDBFilterControl          See Also

Creates a data-bound filter control.

constructor Create(AOwner: TComponent); override;

Description

Use the Create method to create a new filter control at runtime.  The AOwner parameter specifies the owner of the newly created control (typically the form).  Be sure to specify the Parent property of the newly created filter control.  Otherwise the control will not be displayed.


TcxDBFilterControl.Destroy

TcxDBFilterControl          See Also

Destroys the data-bound filter control.

destructor Destroy; override;

Description

The Destroy method is used to dispose the TcxDBFilterControl and free any allocated memory.  Do not use this method in applications.  Use the Free method instead.


TcxDBFilterControl.GetFilterTextEx

TcxDBFilterControl          See Also

Returns the text representation of the filter criteria, defined by a filter control, with the fields’ names that are enclosed by the AFieldNamePrefix and AFieldNamePostfix delimiters.

function GetFilterTextEx(const AFieldNamePrefix, AFieldNamePostfix: string): string;

Description

The GetFilterTextEx method forces the AFieldNamePrefix and AFieldNamePostfix delimiters to be used around the fields’ names if the fields of the underlying dataset contain spaces in their names. Which arguments should be passed into the method (for example, single quotes or square brackets) is dependent upon the type of the database used. If no delimiters are required pass the empty strings as arguments.

The AFieldNamePrefix parameter specifies a delimiter followed by the field’s name.

The AFieldNamePostfix parameter specifies a delimiter following the field’s name.


TcxDBFilterControl.GetPropertiesClassFromFieldType

TcxDBFilterControl

Returns a class which represents the settings of the editor associated with the AFieldType type of the dataset field.

function GetPropertiesClassFromFieldType(AFieldType: TFieldType): TcxCustomEditPropertiesClass; virtual;

Description

Use the GetPropertiesClassFromFieldType method to get the class responsible for the editor’s settings associated with the AFieldType type of the dataset field.


TcxDBFilterOptions
TcxDBFilterOptions Object

Hierarchy          Properties          Methods          See Also

Contains options controlling the filtering and display of filter text.

Unit

cxDBFilterControl

TcxDBFilterOptions = class(TPersistent)

Description

The TcxDBFilterOptions class declares a number of properties that describe the different filtering options.  The TcxDBFilterOptions object can be accessed via the FilterOptions property of the TcxDBFilterControl object.


TcxDBFilterOptions Hierarchy
Hierarchy

TPersistent

     |

TcxDBFilterOptions


Properties for TcxDBFilterOptions
TcxDBFilterOptions Properties

TcxDBFilterOptions          Legend

In TcxDBFilterOptions

DateTimeFormat

PercentWildcard

SoftNull

SupportedBetween

SupportedIn

SupportedLike

UnderscoreWildcard


Methods for TcxDBFilterOptions
TcxDBFilterOptions Methods

TcxDBFilterOptions          Legend

In TcxDBFilterOptions

Create

ProcessFilterOperators


TcxDBFilterOptions.DateTimeFormat

TcxDBFilterOptions

Controls formatting of date-time values.

property DateTimeFormat: string;

Description

The DateTimeFormat property specifies the formatting of date-time values when they are converted to strings within the FilterText property value.  The value of the DateTimeFormat property represents a standard Delphi Date Time Format String composed from specifiers representing values to be inserted into the formatted string.  For a complete description of date and time format strings, see the Date-Time format strings topic in the Delphi help.


TcxDBFilterOptions.PercentWildcard

TcxDBFilterOptions          See Also

Specifies the character used to represent any number of symbols in the filter condition of the LIKE type.

property PercentWildcard: Char;

Description

When comparing string values, it is possible to use the symbol specified by the PercentWildcard property to represent any possible character (number, letter, or punctuation) or set of characters in the filter condition of the LIKE type.  The wildcard symbol can be used for any characters, in the same relative position as the given characters.  You can assign any character to be used as a wildcard.

The default value of the PercentWildcard property is '%'.


TcxDBFilterOptions.SoftNull

TcxDBFilterOptions

Specifies whether empty strings are considered as NULL values when comparing.

property SoftNull: Boolean;

Description

Use the SoftNull property to control how the data-aware filter control treats blank field values.  If this property is set to True, empty strings are considered as NULL values when comparing.  Otherwise, they are interpreted as blank strings (‘’).

The default value of the SoftNull property is False.


TcxDBFilterOptions.SupportedBetween

TcxDBFilterOptions          See Also

Specifies whether the BETWEEN operator is supported by the database system used.

property SupportedBetween: Boolean;

Description

The SupportedBetween property serves to indicate whether the BETWEEN operator is supported by the database system used for data provision.  This property controls whether the between and not between operators are provided within the comparison operators dropdown list.

The BETWEEN conditional operator is used in SQL statements to test whether or not a value (stated before the keyword BETWEEN) is "between" the two values stated after the keyword BETWEEN.  For instance:

SELECT emloyeeid, lastname, age, salary

FROM employee_info

WHERE age BETWEEN 30 AND 40;

Although most database systems use ANSI SQL, some also have their own additional proprietary extensions.  So, the BETWEEN operator may be treated differently by different databases.  Its availability depends upon the database you are using.  Set the SupportedBetween property to False if your database management system does not support the BETWEEN operator.

Important Note: The SupportedBetween property should be set to False if you perform dataset filtering using the BDE-enabled dataset’s filter support mechanism (i.e. when you assign the FilterText property value to the Filter property of the dataset and then set the dataset’s Filtered property to True).

The default value of the SupportedBetween property is True.


TcxDBFilterOptions.SupportedIn

TcxDBFilterOptions          See Also

Specifies whether the IN operator is supported by the database system used.

property SupportedIn: Boolean;

Description

The SupportedIn property indicates whether the IN operator is supported by the database system used for data provision.  This property value affects the presence of the in and not in operators within the dropdown list of comparison operators.

The IN conditional operator is really a set membership test operator.  That is, it is used in SQL statements to test whether or not a value (stated before the keyword IN) is "in" the list of values provided after the keyword IN.  For example:

SELECT emloyeeid, lastname, salary

FROM employee_info

WHERE lastname IN ('Fernandez', 'Jones', 'Roberts', 'Gates');

Although most database systems use ANSI SQL, some also have their own additional proprietary extensions.  So, the IN operator may be treated differently by different databases.  Its availability depends upon the database you are using.  Set the SupportedIn property to False if your database management system does not support the IN operator.

Note: The SupportedIn property should be set to False if you perform dataset filtering using the BDE-enabled dataset’s filter support mechanism (i.e. when you assign the FilterText property value to the Filter property of the dataset and then set the dataset’s Filtered property to True).

The default value of the SupportedIn property is True.


TcxDBFilterOptions.SupportedLike

TcxDBFilterOptions          See Also

Specifies whether the LIKE operator is supported by the database system used.

property SupportedLike: Boolean;

Description

The SupportedLike property indicates whether the LIKE operator is supported by the database system used for data provision.  This property value affects the presence of the like and not like operators within the dropdown list of comparison operators.

The LIKE pattern matching operator can be used in SQL statements to select only rows that are "like" what you specify.  The percent sign '%' (or other specified by the PercentWildcard property) can be used as a wild card to match any possible character that might appear before or after the characters specified.  For instance:

SELECT emloyeeid, lastname, salary

FROM employee_info

WHERE lastname LIKE 'F%';

Although most database systems use ANSI SQL, some also have their own additional proprietary extensions. So, the LIKE operator may be treated differently by different databases.  Its availability depends upon the database you are using.  Set the SupportedLike property to False if your database management system does not support the LIKE operator.

Note: The SupportedLike property should be set to False if you perform dataset filtering using the BDE-enabled dataset’s filter support mechanism (i.e. when you assign the FilterText property value to the Filter property of the dataset and then set the dataset’s Filtered property to True).

The default value of the SupportedLike property is True.


TcxDBFilterOptions.UnderscoreWildcard

TcxDBFilterOptions          See Also

Specifies the symbol used to represent any single character in the filter condition of the LIKE type.

property UnderscoreWildcard: Char;

Description

When comparing string values it is possible to use the symbol specified by the UnderscoreWildcard property to represent any single character in the filter condition of the LIKE type.  You can assign any character to be used as a wildcard.

The default value of the UnderscoreWildcard property is '_'.


TcxDBFilterOptions.Create

TcxDBFilterOptions

Creates a new TcxDBFilterOptions class instance.

constructor Create(AFilterControl: TcxDBFilterControl);

Description

The Create method is used to create and initialize a new instance of the TcxDBFilterOptions object.

The AFilterControl parameter represents a data-aware filter control owning the newly created object.

You have no need to use this constructor in your applications.  The TcxDBFilterOptions object is created automatically, when the filter control initializes its FilterOptions property.


TcxDBFilterOptions.ProcessFilterOperators

TcxDBFilterOptions

Processes the list of supported filter operators based upon the values of the SupportedBetween, SupportedIn and SupportedLike properties.

procedure ProcessFilterOperators(var SupportedOperations: TcxFilterControlOperators);

Description

The ProcessFilterOperators method is used to process the list of supported filter operators specified by the SupportedOperations parameter.  The method checks the state of the SupportedBetween, SupportedIn and SupportedLike properties one after another, and if a property is inactive removes the corresponding operator from the specified list.